GroundmailDocs

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

pip install groundmail

For the Django email backend:

pip install 'groundmail[django]'

2. Configure your API key

export GROUNDMAIL_API_KEY=gm_your_key_here

3. Send an email (API client)

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"])
# 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:

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 for request fields. The Python SDK accepts the same JSON shapes as the REST API.

Source

Package source lives in python/ in the public groundmail-sdks repository.