> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Python

# Python SDK

Official **Python** client for the Mailofly REST API.

**Package:** [`mailofly`](https://pypi.org/project/mailofly/) · **Requires:** Python 3.9+ · **Quickstart:** [Python](/docs/getting-started/python.md)

***

## Install

```bash theme={null}
pip install mailofly
# or
uv add mailofly
```

***

## Initialize

```python theme={null}
import os
from mailofly import Mailofly, MailoflyError

client = Mailofly(
    os.environ["MAILOFLY_API_KEY"],
)
```

Create an API key under **[API keys](https://www.mailofly.com/user/api-keys)** first.

***

## Send email

```python theme={null}
try:
    result = client.emails.send({
        "from": "Acme <onboarding@example.com>",
        "to": ["alex@example.com"],
        "subject": "Hello",
        "html": "<p>Thanks for signing up.</p>",
    })
    print("Sent:", result["id"])
except MailoflyError as e:
    print(e.status, e.error, e.detail_message)
    raise
```

### With a saved template

```python theme={null}
client.emails.send({
    "from": "Acme <onboarding@example.com>",
    "to": ["alex@example.com"],
    "template": {
        "id": "uuid-of-template",
        "variables": {"first_name": "Alex"},
    },
})
```

`client.compose.send` is deprecated and forwards to `/v1/emails`.

### Batch send (up to 100 emails)

```python theme={null}
result = client.batch.send([
    {
        "from": "Acme <onboarding@example.com>",
        "to": ["foo@example.com"],
        "subject": "hello world",
        "html": "<h1>it works!</h1>",
    },
    {
        "from": "Acme <onboarding@example.com>",
        "to": ["bar@example.com"],
        "subject": "world hello",
        "html": "<p>it works!</p>",
    },
])
print([row["id"] for row in result["data"]])
```

***

## Resources

| Namespace | Methods |
| - | - |
| `client.identities` | `list`, `get`, `update`, `delete` *(creation is dashboard-only)* |
| `client.accounts` | *(deprecated alias for `client.identities`)* |
| `client.contacts` | `list`, `create`, `get`, `update`, `delete` |
| `client.templates` | `list`, `create`, `get`, `update`, `delete` |
| `client.segments` | `list`, `create`, `get`, `update`, `delete`, `contacts.list/add/remove` |
| `client.campaigns` | `list`, `create`, `get`, `update`, `delete`, `runs`, `send` |
| `client.emails` | `list`, `get`, `send` |
| `client.batch` | `send` |
| `client.compose` | `send` (deprecated) |
| `client.mail_logs` | `list` |

### Examples

```python theme={null}
identities = client.identities.list()

client.contacts.create({
    "email": "alex@example.com",
    "first_name": "Alex",
    "custom_fields": {"plan": "pro"},
})

client.campaigns.send("campaign-uuid", {"send_now": True})

logs = client.mail_logs.list(status="failed", page=1, page_size=50)
```

***

## Discovery (no API key)

```python theme={null}
meta = Mailofly.discovery()
print(meta.get("resources"))
```

***

## Error handling

```python theme={null}
from mailofly import MailoflyError

try:
    client.identities.list()
except MailoflyError as e:
    # e.status — HTTP status
    # e.error — error code string
    # e.detail_message — human-readable message
    pass
```

***

## Related

* [Python quickstart](/docs/getting-started/python.md)
* [API: Emails](https://docs.mailofly.com/api/emails)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.