orevail 1.0.0

The official Python SDK for Orevail — the stateless transactional and temporary email network.

Orevail Python SDK

The official, zero-dependency Python library for interacting with the Orevail Developer Mail Network.

Orevail is a developer-first transactional and temporary email network. By designing routes on high-reputation domains and validating them with 2048-bit DKIM keys, Orevail allows you to test inbound mail parsing loops, run transactional flows, and mock sandbox accounts easily without getting flagged by spam-reputation checkers.

---

Key Features

• Zero Dependencies: Built entirely on top of Python's standard urllib module. No need to install requests or other third-party dependencies.
• Type-Hinted: Fully typed for modern Python editors (VS Code, PyCharm).
• Resilient: Clean mapping of API error payloads to custom, descriptive exceptions (OrevailAuthError, OrevailAPIError).
• Compatible: Tested and supported across all active Python versions (>= 3.7).

---

Installation

Install the package via pip:

pip install orevail

---

Quickstart Guide

1. Instant Mailbox Allocation

Create a virtual sandbox address on-the-fly. The API key is returned exactly once in this payload.

from orevail import Orevail

# Create a virtual user mailbox dynamically
reg_info = Orevail.create_user("[e-mail]")

print(f"Allocated Email: {reg_info['email']}")
print(f"Sandbox API Key: {reg_info['api_key']}")

2. Initializing the Authenticated Client

Once you have your sandbox API key, initialize the authenticated client:

from orevail import Orevail

client = Orevail(api_key="your_orevail_api_key_here")

3. Send Outbound Transactional Emails

Enqueue emails into Orevail's outbox. Outbound emails are cryptographically signed with DKIM on-the-fly and routed instantly.

# Send a transactional email
receipt = client.send_email(
    sender="[e-mail]",
    recipient="[e-mail]",
    subject="Your Verification Token",
    text="Your security token is: 884712",
    html="<p>Your security token is: <strong>884712</strong></p>"
)

print(f"Outbox Job Queued. Job ID: {receipt['jobId']}")

4. Fetch and Parse Inbox Mails

Check the sandbox mailbox to parse incoming emails (e.g. testing outbound alerts, registration loops, or parse triggers).

# Poll the incoming mail stream
inbox = client.get_emails("[e-mail]", direction="incoming", limit=10)

print(f"Retrieved {inbox['count']} messages:")
for mail in inbox["emails"]:
    print("-" * 40)
    print(f"From: {mail['sender']}")
    print(f"Subject: {mail['subject']}")
    print(f"Body: {mail['body_text']}")
    
    # Check for attachments
    if mail.get("attachments"):
        print(f"Attachments: {[att['filename'] for att in mail['attachments']]}")

5. Download Email Attachments

Fetch raw binary content files associated with an incoming email:

# If an attachment exists, download its raw content
attachment_bytes = client.download_attachment(attachment_id=12)

with open("downloaded_invoice.pdf", "wb") as f:
    f.write(attachment_bytes)

---

Exception Handling

Orevail wraps exceptions cleanly to help you debug quickly:

from orevail import Orevail, OrevailAuthError, OrevailAPIError, OrevailError

try:
    client = Orevail(api_key="invalid_key")
    client.get_emails("[e-mail]")
except OrevailAuthError as e:
    print(f"Credentials Rejected: {e}")
except OrevailAPIError as e:
    print(f"API Error [{e.status_code}]: {e}")
except OrevailError as e:
    print(f"General SDK failure: {e}")

---

License

MIT License. Created by the Orevail Core Team.