# Groundmail with Python

Use the Python SDK in Django, Flask, FastAPI, Celery workers, or any server-side Python app where your API key can stay private.

## 1. Install the SDK

```bash
pip install groundmail
```

For the Django email backend:

```bash
pip install 'groundmail[django]'
```

## 2. Configure your API key

```bash
export GROUNDMAIL_API_KEY=gm_your_key_here
```

## 3. Send an email (API client)

```python
import os

from groundmail import Groundmail

tx = Groundmail(os.environ["GROUNDMAIL_API_KEY"])

result = tx.emails.send(
    from_="ops@yourdomain.com",
    to="user@example.com",
    subject="Your receipt",
    html="<p>Thanks for your purchase.</p>",
)

print(result["id"], result["status"])
```

## Django email backend (recommended)

```python
# settings.py
EMAIL_BACKEND = "groundmail.django.EmailBackend"
# Uses GROUNDMAIL_API_KEY from the environment.
# Optional: EMAIL_HOST-style settings are not used; configure the API key via env.
```

Then send as usual:

```python
from django.core.mail import EmailMultiAlternatives

msg = EmailMultiAlternatives(
    subject="Your receipt",
    body="Thanks for your purchase.",
    from_email="ops@yourdomain.com",
    to=["user@example.com"],
)
msg.attach_alternative("<p>Thanks for your purchase.</p>", "text/html")
msg.extra_headers["X-Groundmail-Tag"] = "campaign=welcome"
msg.extra_headers["X-Groundmail-Idempotency-Key"] = "receipt-123"
msg.send()
```

`X-Groundmail-Tag` uses `name=value`. Pass a list of tag strings for multiple tags. Custom non-reserved headers are forwarded to the API `headers` field. Optional: `X-Groundmail-Scheduled-At` (ISO 8601).

## Resources

The client includes thin wrappers for common API resources:

- `tx.emails` — send, batch, list, cancel, resend, test webhooks, deliverability insights
- `tx.domains` — create, verify, apply DNS, update, delete
- `tx.webhooks` — CRUD for webhook endpoints
- `tx.templates` — CRUD plus publish
- `tx.suppressions` — list, create, remove

See the [API reference](https://docs.groundmail.dev/emails) for request fields. The Python SDK accepts the same JSON shapes as the REST API.

## Source

Package source lives in [`python/`](https://github.com/Groundmail/groundmail-sdks/tree/main/python) in the public [groundmail-sdks](https://github.com/Groundmail/groundmail-sdks) repository.
