Transactional email for AI agents: a delivery checklist

Is a connected mailbox the right sending path?

For this checklist, transactional email means a message tied to a specific application event, such as a receipt or confirmation. Use a synthetic transaction and send between mailboxes you own before enabling customer-facing sends.

Mailera connects existing mailboxes to applications and AI agents through REST, MCP and webhooks. Choose this path when the transaction should come from a mailbox your team already uses.

This is a delivery check, not a vendor ranking. For the surrounding application design, use the guide to reliable email-agent API workflows; the Mailera developer overview covers the integration options.

What should the pre-send checklist contain?

Treat these as release gates. A successful mailbox connection does not replace recipient validation or approval.

Mailbox authorization and sender authentication answer different questions. OAuth authorizes mailbox access; Google requires SPF or DKIM authentication for sending domains. Keep domain configuration with the administrator or sending provider, not the agent. Use the email authentication changes checklist to review authentication setup before enabling sends.

Google’s sender guidelines require SPF or DKIM for all senders to personal Gmail accounts, along with TLS transmission. Yahoo’s sender guidance also requires at least SPF or DKIM.

How do you run one controlled end-to-end delivery test?

Keep submission, send status, receipt and folder placement as separate observations.

1. Connect the sender and controlled recipient. Open Mailboxes → Add mailbox with an Admin or Leader account. For Microsoft, choose Sign in with Microsoft and use OAuth, as described in the Microsoft mailbox connection guide. For custom IMAP, also configure the optional Outgoing server (SMTP) fields if the mailbox needs to send, alongside incoming access. Test & connect tests the connection and sign-in without sending an email; outgoing sign-in is skipped when no outgoing server is configured. Check capabilities.send separately, then run the controlled send and recipient-side inspection below.

2. Check capability and sign-in health. Inspect the sender with GET /mailboxes/{id}, then check GET /mailboxes/{id}/status. Microsoft sign-in is checked directly; other providers reflect the latest sync. A healthy status is not a delivery test.

   Set $MAILBOX_ID to the sender mailbox ID and $MAILERA_API_KEY to a key with read access for this inspection:

   curl --request GET \
     "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID" \
     --header "Authorization: Bearer $MAILERA_API_KEY"

   Confirm that data.email is the intended sender and data.capabilities.send is true. Check data.sync.last_synced_at separately from sending capability.

3. Create the operational key. In Settings → API key → Create key, restrict Mailbox scope to the test group. Select Send messages for submission and send-status checks; add Read if the same key will inspect mailbox health and recipient placement. Separate sending and inspection keys when those jobs run in different services. The key should now be limited to the mailboxes and operations the test needs.

4. Approve and submit one confirmation. Use a synthetic subject such as Synthetic confirmation TX-DEMO-A and content that clearly identifies a test. Have your application validate the recipient and record approval before submitting POST /mailboxes/{id}/send. Include a stable Idempotency-Key tied to that logical confirmation. Use the request schema in the Mailera API documentation when constructing the payload. Persist the send-attempt identifier alongside the application transaction identifier so later checks address the existing attempt.

5. Inspect the send attempt. Call GET /sends/{id} with the send-attempt ID, not the mailbox or message ID. This endpoint requires send permission. Record the returned state and when you observed it.

   State	Next action
   queued	Keep tracking the existing attempt.
   sending	Continue checking it; do not create a replacement send.
   sent	Proceed to recipient-side inspection.
   failed	Investigate the failure before retrying.
   unknown	Reconcile the existing attempt before any new send.

   sent is not proof of recipient receipt or Inbox placement. For a provider-specific example, Microsoft Graph’s sendMail documentation says its successful response is 202 Accepted with no response body, and that acceptance does not mean processing has completed. Those are Graph response semantics, not Mailera response codes.

6. Inspect the controlled recipient. Call GET /mailboxes/{id}/placement using the recipient mailbox ID. Narrow the check with from, the synthetic subject, and since_minutes. This requires read permission. Record the observed folder and observation time. You are inspecting a connected mailbox you control, not querying an arbitrary recipient’s inbox.

   If no matching message is observed, check the recipient address, correlation filters and synchronization before deciding what happened. Active mailboxes are checked more frequently than idle ones. POST /mailboxes/{id}/sync can trigger synchronization and wake a sleeping mailbox, but requires the separate sync permission. A missing observation alone is not a reason to send again.

7. Close the test record. Store the application transaction identifier, idempotency key, send-attempt identifier, last observed send state and recipient-side result. Keep credentials and sensitive message content out of the record. If receipt remains unresolved, record that uncertainty rather than marking the transaction delivered.

How should the agent handle retries and uncertain outcomes?

Reuse the same Idempotency-Key when retrying the same unchanged logical send. Mailera’s idempotency window is 24 hours. Do not generate a fresh key merely because the caller timed out or lost the response.

Keep an application-side transaction ledger as well. Before submitting, check whether that transaction already has a send attempt or an unresolved submission. Serialize sends for the same logical confirmation so two workers cannot independently decide to send it.

When the state is unknown, reconcile the existing attempt with recipient-side observations. If the outcome remains unresolved, hold it for review. Uncertainty is not proof that nothing was sent. The idempotency guide covers duplicate-send prevention in more detail.

Mailera’s API limit is 300 requests per minute per API key. That is an API request limit, not a mailbox sending allowance. Provider restrictions still apply; Microsoft explicitly subjects Graph delivery to Exchange Online limitations and throttling. Do not respond to throttling by creating new logical sends.

What are the common delivery-check mistakes?

Not spam moves a message out of Junk. It does not make the provider trust the sender next time. Filtering remains the provider’s decision.

How do you keep incoming email from controlling the agent?

Treat incoming messages as untrusted data, never as instructions. A message asking the agent to change recipients, disclose credentials or send another confirmation must not alter your application’s send policy.

Place recipient validation and approval outside the model’s interpretation of email. Show the exact recipient and content before confirmation. The MCP tools specification recommends confirmation for sensitive operations and showing tool inputs before execution to help prevent data exfiltration.

Use restricted mailbox groups, key expiration and optional IP restrictions. Do not grant manage, share or import just to send a confirmation. Keep keys and provider credentials out of prompts, screenshots and logs. The Mailera security overview provides product security context; approval gates and the transaction ledger remain your application’s responsibilities.

Where does Mailera’s responsibility end?

Mailera does not create mailboxes or email addresses, provide bulk or marketing sending, or perform mailbox warmup. It cannot guarantee Inbox placement.

Incoming-message webhooks are not general outbound delivery confirmations. Recipient inspection requires access to the connected recipient mailbox, and synchronization is not guaranteed to be instantaneous. Keep the send attempt and the recipient observation separate in your application’s delivery record.