How to Send Transactional Emails with an API: Python Example

A password-reset API call can return 202 Accepted even though the message has only been queued, not delivered. That gap matters when an account notification is part of a live user flow. This guide shows how to send transactional emails with an API, maps the request fields, and gives you a runnable Python example plus checks for safe production use. We also cover when SMTP fits better and why provider regions and limits belong in pre-launch testing.

To send a transactional email through an API, your application authenticates with an email provider and submits an HTTPS request containing a sender, recipient, subject, and body or template. The provider returns a response showing whether it accepted the request. Verify the sending domain, keep credentials server-side, and monitor delivery events; acceptance alone does not confirm inbox delivery.

What transactional email is—and when to use it

A transactional email is sent because a specific action or event in an application calls for a message. A purchase can trigger a receipt; a password-reset request can trigger a reset link; and a change to account details can trigger a security notification. The recipient and content follow from that event, so the message helps someone complete an action or understand a change to their account.

A marketing campaign has a different purpose: it sends promotional or informational content to a selected audience, often according to a schedule or segment rather than an individual event. A product announcement sent to a mailing list is a campaign; a notice that a user’s subscription payment failed is transactional. The distinction matters because these messages have different triggers and recipients, even when the same platform sends both.

We built Volanea to handle both categories: it combines transactional email with campaigns and event-triggered automation on one API. That lets a team use one platform for application notifications and audience campaigns without treating a bulk promotion as a transaction. (Volanea)

What you need before sending through an API

Before writing the request, make sure you have five things in place: access to a provider account, an approved sender, credentials, a recipient address, and the message content. Provider setup differs: Scaleway’s API guide calls for a Scaleway account, an API key, suitable Organization permissions, and a configured domain. SendGrid’s API instructions require the from address to use a domain authenticated on the account.

Prepare the sender address and, if needed, its display name. Keep the API key or other secret in server-side configuration, not browser code or a public repository. For the recipient, use the address that should receive this specific event notification; have a subject and plain-text or HTML body ready, or select a provider-supported template.

These prerequisites are concrete in Volanea too: we require domain verification before sending to real recipients, while our sending account does not require an Amazon SES production-access request (Volanea and Amazon SES). Once these pieces are ready, you can map them into the provider’s request format.

How an API request sends a transactional email

An API send is a request-response flow: your application builds a message payload, sends it to the provider over HTTPS, and receives a response indicating whether the provider accepted the request. For example, Twilio SendGrid’s Mail Send API accepts an HTTP POST at https://api.sendgrid.com/v3/mail/send; its basic request uses an Authorization: Bearer header and JSON content (SendGrid’s API instructions).

The payload describes who is sending and receiving the message, and what the recipient should see. SendGrid’s basic request includes a from email, at least one to recipient, a string subject, and content with a media type such as text/plain and a nonempty value. The content can instead be rendered from a template; the subject may also come from a dynamic template or personalization. An optional identifier—such as an order ID in your own system—can help correlate the send with the event that triggered it, but it is not a substitute for the provider’s response or delivery events.

After submission, distinguish acceptance from delivery: SendGrid’s 202 Accepted means the request was accepted for processing and queued, not that it reached the inbox. Volanea’s documented REST sending endpoint is POST /v1/send, with template rendering and delivery handled in its sending pipeline (Volanea).

Send a transactional email with a Python API example

This minimal example uses Twilio SendGrid’s Mail Send API. Install the requests package, set SENDGRID_API_KEY to an API key with mail-sending permission, and replace the sender and recipient with email addresses appropriate for your account. SendGrid requires the from address to belong to an authenticated domain. Its endpoint accepts an HTTP POST with a bearer token and JSON body (SendGrid API instructions).

import os
import requests

url = "https://api.sendgrid.com/v3/mail/send"
payload = {
    "personalizations": [{"to": [{"email": "recipient@example.com"}]}],
    "from": {"email": "notices@your-authenticated-domain.com"},
    "subject": "Your account is ready",
    "content": [{"type": "text/plain", "value": "Your account has been created."}],
}

response = requests.post(
    url,
    headers={
        "Authorization": f"Bearer {os.environ['SENDGRID_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=15,
)
response.raise_for_status()
print(response.status_code)

The JSON maps the recipient, sender, subject, and plain-text body to SendGrid’s required message fields. Keep the API key in an environment variable rather than embedding it in source code. SendGrid’s basic request uses text/plain; its API also supports extending the content with HTML, CC/BCC, or attachments, as described in its test-email instructions.

API or SMTP: which sending method should you use?

An email API sends a structured request over HTTP; SMTP submits a message through a mail-transfer protocol. Both can deliver transactional email, but they fit different application architectures. Twilio SendGrid supports both SMTP and its Mail Send API, whose endpoint accepts an HTTP POST request. The API is a natural fit when your application already makes HTTP calls and needs to pass message data or template variables as structured fields. It also makes the request-response exchange explicit in application code.

SMTP can be simpler when the software you’re integrating with already expects a mail server: provide its SMTP settings instead of writing a provider-specific HTTP integration. That can suit existing systems or libraries built around SMTP, while an API may be more convenient for a new service with its own request-handling code. Choose based on what your application supports and how you want to manage the integration—not on an assumption that one protocol guarantees better delivery.

We offer both options: Volanea has a REST sending endpoint and an SMTP relay, so teams can use either method while sending through the same email platform. SendGrid’s Mail Send API setup documents its HTTP request approach.

Test the integration and handle API errors

Before connecting an API call to a user action, test it with a controlled recipient and inspect both the HTTP response and the provider’s event or delivery records. For Twilio SendGrid, confirm the from address belongs to an authenticated domain; a mismatched sender can produce 403. A 400 points to malformed or invalid request content, while 401 can mean the authorization grant is invalid, expired, or revoked. Check the response body for the specific error rather than retrying every failure unchanged. (SendGrid error codes)

Treat 202 Accepted as queued for processing, not proof that the message reached the inbox. Record the provider’s response and a correlation identifier with the application event, then monitor delivery events so a later bounce or rejection is visible. (SendGrid’s 202 guidance)

Keep API keys in server-side environment variables or a secrets manager; never put them in browser code, source control, or logs. On failure, preserve a sanitized error and retry only transient errors with bounded backoff; make retries idempotent at the application level to avoid duplicate receipts or password-reset messages. In Volanea, send records and event logs help trace message outcomes without logging credentials.

Production considerations: regions, limits, and delivery

Before you route production traffic, check that the provider’s region and quotas fit your application. Scaleway Transactional Email is available only in fr-par, and its send API endpoint includes that region: https://api.scaleway.com/transactional-email/v1alpha1/regions/fr-par/emails. A region constraint can affect where your integration runs and which endpoint it calls.

Scaleway’s published default monthly quota is 10,000 emails. Its default maximum is 10 recipients per email, but each recipient counts as a separate email toward quota. The API’s maximum email size is 2 MB, including attachments, and that limit is not upgradable. Check these constraints against your expected volume and payloads before launch; request a quota increase from Support if your validated account needs more capacity. Scaleway assesses sending capacity case by case, so do not treat the published maximum as guaranteed throughput for a new account. Its capabilities page does not state a fixed numerical sending rate limit.

After deployment, monitor provider events and your own send records for accepted, delivered, bounced, and otherwise failed messages. A successful API acceptance is not proof that a message reached an inbox; alert on delivery problems and reconcile provider status with the application event that triggered each email. For Volanea, the API provides send records, delivery, open, click, bounce, and unsubscribe statistics, plus event logs.

FAQ

Do I need a marketing email add-on to send transactional email?

Not inherently: transactional sends are event-triggered, while campaign tools serve audience messaging, and provider packaging differs. Volanea combines transactional email, campaigns, and event-triggered automation on one API, so teams can use one platform for both without treating a promotion as a transaction.

Do all providers verify sender domains the same way?

No. SendGrid requires the sender address to belong to an authenticated domain and recommends domain authentication with SPF and DKIM records. Scaleway requires a configured and verified domain with SPF, DKIM, MX, and DMARC records. Check the provider’s specific domain setup before sending to real recipients.

Do all transactional email APIs use the same request format?

No. SendGrid’s Mail Send API uses an Authorization: Bearer header and a JSON request, while Scaleway’s documented example uses an X-Auth-Token header and includes a Project ID in the request body. Follow your provider’s documented endpoint, authentication method, and payload format rather than assuming one schema works across services.