Skip to content

Documentation

Send email from FastAPI.

An endpoint that answers at once and sends in a background task.

Before you start

You need a verified sending domain (see Domains) and an API key (under API keys in the dashboard; it is shown once). Keep the key in an environment variable on your server, never in code that runs in a browser or an app.

Install

The Python client has no dependencies and is synchronous, so it fits a plain def function that FastAPI runs in its thread pool.

Terminal
pip install mailtruss fastapi

The endpoint

A background task runs after the response is sent, so the visitor does not wait for the email. A failure is logged with the request ID, which you can search in the dashboard's API logs. The idempotency key makes a retry safe.

main.py
import html
import logging
​
from fastapi import BackgroundTasks, FastAPI
from mailtruss import Mailtruss, MailtrussError
from pydantic import BaseModel
​
app = FastAPI()
mail = Mailtruss() # reads MAILTRUSS_API_KEY from the environment
log = logging.getLogger("mail")
​
​
class Signup(BaseModel):
email: str
name: str
​
​
def send_welcome(email: str, name: str) -> None:
try:
mail.emails.send(
from_="Acme <hello@yourdomain.com>", to=email, subject="Welcome to Acme",
html=f"<p>Hi {html.escape(name)}, thanks for signing up.</p>",
idempotency_key=f"welcome:{email}",
)
except MailtrussError as e:
log.error("welcome email failed: %s", e)
​
​
@app.post("/signup", status_code=202)
def signup(body: Signup, tasks: BackgroundTasks):
tasks.add_task(send_welcome, body.email, body.name)
return {"queued": True}

Try it without sending real mail

Send to delivered@mailtruss.test first. It works before any domain is verified and reaches no real mailbox, so you can check your code and see the recorded timeline. Then try bounced@mailtruss.test to see what a bounce looks like. All the test addresses are listed under Sending.

See what happened

Open the message under Emails in the dashboard: it shows the recorded timeline, what each event proves, and a diagnosis if something went wrong. Or fetch it with GET /api/v1/emails/:id/events. To be told as it happens, add a webhook.

If it fails

API requests answer with an error name and message. The common ones:

  • 403 invalid_api_key or 401 missing_api_key: the key is wrong, revoked or not sent. Send it as Authorization: Bearer ms_live_….
  • 403 domain_not_verified: the from address is on a domain that is not verified. Publish the DNS records and re-check.
  • 422 validation_error: fix the field the message names. Nothing was sent and no quota was used.
  • 429 rate_limit_exceeded: back off for the Retry-After header. See rate limits.

Problems that happen after a message is accepted (bounces, complaints) are explained under delivery errors.

Other guides

Last updated

Something wrong or unclear on this page?

Report an issue