Metadata-Version: 2.4
Name: orevail
Version: 1.0.0
Summary: The official Python SDK for Orevail — the stateless transactional and temporary email network.
Author-email: Orevail Core Team <developer@orevail.com>
License: MIT
Project-URL: Homepage, https://orevail.com
Project-URL: Documentation, https://orevail.com/docs
Project-URL: Repository, https://github.com/orevail/orevail-python
Keywords: orevail,email,transactional,inbound,tempmail,sandbox,testing,dkim,smtp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# 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`:

```bash
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.

```python
from orevail import Orevail

# Create a virtual user mailbox dynamically
reg_info = Orevail.create_user("test-runner@orevail.com")

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:

```python
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.

```python
# Send a transactional email
receipt = client.send_email(
    sender="test-runner@orevail.com",
    recipient="customer@example.com",
    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).

```python
# Poll the incoming mail stream
inbox = client.get_emails("test-runner@orevail.com", 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:

```python
# 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:

```python
from orevail import Orevail, OrevailAuthError, OrevailAPIError, OrevailError

try:
    client = Orevail(api_key="invalid_key")
    client.get_emails("test-runner@orevail.com")
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.
