Metadata-Version: 2.4
Name: mailtd
Version: 2.0.0
Summary: Official Python SDK for Mail.td — temp mail & temporary email with REST API, webhooks, and custom domains.
Author: Mail.td
License: MIT
Project-URL: Homepage, https://mail.td
Project-URL: Documentation, https://docs.mail.td
Project-URL: Repository, https://github.com/mailtd/mailtd-python
Keywords: temp-mail,temporary-email,disposable-email,email-testing,email-api,test-email,email-verification,mailtd,mail-td,sdk
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: argon2-cffi>=23.1.0

# mailtd

[![PyPI version](https://img.shields.io/pypi/v/mailtd.svg)](https://pypi.org/project/mailtd/)
[![PyPI downloads](https://static.pepy.tech/badge/mailtd/month)](https://pepy.tech/project/mailtd)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Official Python SDK for [Mail.td](https://mail.td) — temp mail & temporary email with REST API, webhooks, and custom domains. Instant inboxes, password protected, sign in from any device.

- **Temp Mail API** — Create and manage temporary email addresses programmatically
- **Webhooks** — Get notified in real-time when emails arrive
- **Custom Domains** — Use your own domain for branded temporary mailboxes
- **Password Protected** — Sign in to the same mailbox from any device

## Install

```bash
pip install mailtd
```

Requires Python 3.9+.

## Quick Start

```python
from mailtd import MailTD

client = MailTD("td_...")

# Create a temporary email address
account = client.accounts.create("test@mail.td", password="mypassword")

# List messages
messages, page = client.messages.list(account.id)

# Get a message
msg = client.messages.get(account.id, messages[0].id)
print(msg.subject, msg.text_body)
```

## Use Cases

- **Automated testing** — Create temp mail addresses in CI/CD to test signup flows, OTP verification, and transactional emails
- **Email verification testing** — Validate that your app sends the right emails with the right content
- **QA environments** — Give each test run its own mailbox, then tear it down

## Authentication

All API calls require a Pro API Token (`td_...`). Pass it when creating the client:

```python
# With a token string
client = MailTD("td_...")

# With custom base URL
client = MailTD("td_...", base_url="https://api.mail.td")

# As context manager
with MailTD("td_...") as client:
    messages, _ = client.messages.list(account_id)
```

## Resources

### Accounts

```python
domains = client.accounts.list_domains()
account = client.accounts.create("user@mail.td", password="pass123")
info = client.accounts.get(account_id)
client.accounts.reset_password(account_id, password="newpass")
client.accounts.delete(account_id)
```

### Messages

```python
messages, page = client.messages.list(account_id)
msg = client.messages.get(account_id, message_id)
eml = client.messages.get_source(account_id, message_id)
attachment = client.messages.get_attachment(account_id, message_id, 0)
client.messages.mark_as_read(account_id, message_id)
count = client.messages.batch_mark_as_read(account_id, all=True)
client.messages.delete(account_id, message_id)
```

### Domains (Pro)

```python
domains = client.domains.list()
result = client.domains.create("example.com")
status = client.domains.verify(domain_id)
client.domains.delete(domain_id)
```

### Webhooks (Pro)

```python
webhook = client.webhooks.create("https://example.com/hook", events=["email.received"])
deliveries = client.webhooks.list_deliveries(webhook.id)
secret = client.webhooks.rotate_secret(webhook.id)
client.webhooks.delete(webhook.id)
```

### Tokens (Pro)

```python
result = client.tokens.create("CI Token")
tokens = client.tokens.list()
client.tokens.revoke(token_id)
```

### Billing (Pro)

```python
status = client.billing.get_status()
client.billing.cancel()
client.billing.resume()
url = client.billing.get_portal_url()
```

### User (Pro)

```python
me = client.user.get_me()
accounts = client.user.list_accounts()
client.user.delete_account(account_id)
client.user.reset_account_password(account_id, password="newpass")
messages, page = client.user.list_account_messages(account_id)
```

## Error Handling

```python
from mailtd import MailTD, APIError

try:
    client.accounts.create("taken@mail.td", password="...")
except APIError as e:
    print(e.status)  # 409
    print(e.code)    # "address_taken"
```

## Links

- [Website](https://mail.td) — Temp mail & temporary email with REST API
- [API Documentation](https://docs.mail.td) — Full API reference
- [Node.js SDK](https://www.npmjs.com/package/mailtd) — `npm install mailtd`
- [Go SDK](https://github.com/mailtd/mailtd-go) — `go get github.com/mailtd/mailtd-go`
- [CLI](https://github.com/mailtd/mailcx-cli) — Command-line tool

## License

MIT
