Metadata-Version: 2.4
Name: trivumo
Version: 0.1.2
Summary: Official Python SDK for Trivumo email testing.
Author-email: Trivumo <support@trivumo.com>
License: MIT
Project-URL: Homepage, https://trivumo.com
Project-URL: Issues, https://github.com/trivumo/trivumo-python/issues
Project-URL: Repository, https://github.com/trivumo/trivumo-python
Project-URL: Documentation, https://trivumo.com/docs/SDK's/python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: test
Requires-Dist: pytest>=9.0.0; extra == "test"
Requires-Dist: python-dotenv>=1.2.0; extra == "test"
Requires-Dist: resend>=2.32.2; extra == "test"

# Trivumo Python SDK

Official Python SDK for Trivumo.

Trivumo helps you test email-driven workflows by providing disposable inboxes, email capture, message inspection, OTP extraction, link validation, and automation-friendly APIs.

## Installation

Install from PyPI:

```bash
pip install trivumo
```

Or install locally during development:

```bash
pip install -e .
```

---

## Quick Start

```python
from trivumo import TrivumoClient

trivumo = TrivumoClient(
    apiKey="your_api_key",
    domain="sandbox.trivumo.com",
)

email = trivumo.generate_email()

print(email)
```

---

## Wait for an Email

```python
message = trivumo.wait_for_message(
    {
        "to": email,
        "subject": "Verify your account",
    }
)

print(message.subject)

if message.html:
    print(message.html.body)
```

---

## Get Messages

```python
response = trivumo.get_messages(
    {
        "to": email,
    }
)

print(f"Page {response['page']} of {response['totalPages']}")

for message in response["data"]:
    print(message["subject"])
```

### PaginatedResponse

```python
{
    "page": 1,
    "totalPages": 3,
    "data": [...]
}
```

---

## Get a Message by Reference ID

```python
message = trivumo.get_message("msg_123")

print(message.subject)
print(message.fromEmail)
```

---

## Execute an Action and Wait for the Resulting Email

Useful when an action triggers an email, such as:

- Clicking a button in Playwright
- Submitting a signup form
- Calling an API endpoint
- Creating a password reset request

```python
def trigger_action():
    # perform whatever causes an email to be sent
    pass

message = trivumo.wait_for_message_after(
    trigger_action,
    {
        "to": email,
        "subject": "Verify your account",
    }
)

print(message.subject)
```

---

## Async Actions

When using async frameworks such as Playwright Async:

```python
async def trigger_action():
    await page.click("#signup")

message = await trivumo.wait_for_message_after_async(
    trigger_action,
    {
        "to": email,
        "subject": "Verify your account",
    }
)
```

---

## Filtering Messages

```python
messages = trivumo.get_messages(
    {
        "to": email,
        "subject": "Verify your account",
        "fromEmail": "noreply@example.com",
    }
)
```

Available filters:

- `subject`
- `fromEmail`
- `to`
- `receivedAfter`
- `page`

---

## Error Handling

SDK errors raise `TrivumoError`.

```python
from trivumo_sdk import TrivumoError

try:
    message = trivumo.get_message("invalid")
except TrivumoError as error:
    print(error)
    print(error.status)
    print(error.code)
```

---

## API Reference

### TrivumoClient

```python
TrivumoClient(
    apiKey: str,
    domain: str,
    baseUrl: str = "https://trivumo.com/api/v1",
    timeout: float = 30,
    retries: int = 3,
)
```

### Methods

```python
generate_email(username=None)
```

Generate an email address within your namespace.

```python
get_messages(filters=None)
```

Retrieve messages matching the supplied filters.

```python
get_message(reference_id)
```

Retrieve a single message.

```python
wait_for_message(filters=None, options=None)
```

Poll until a matching message is received.

```python
wait_for_message_after(action, filters=None, options=None)
```

Execute a synchronous action and wait for a matching message.

```python
wait_for_message_after_async(action, filters=None, options=None)
```

Execute an asynchronous action and wait for a matching message.
