Magic links and OTP emails are high-trust, time-sensitive messages. MultiMail delivers them fast and keeps every send observable so agent-driven auth flows stay auditable.
Authentication emails sit on the critical path of user login. A 30-second delivery delay kills a 10-minute magic link. A poorly formatted message or a spoofable sender domain drops user confidence and completion rates. When an AI agent triggers these sends — as part of a self-service onboarding flow, an automated access request, or a session refresh — the stakes are higher: the agent cannot manually verify delivery or respond to a failed send the way a human operator would. You need infrastructure that is fast, observable, and correct by construction.
MultiMail's send_email endpoint handles authentication emails as first-class transactional messages. Sends return a message_id immediately, and delivery confirmation fires a webhook to your endpoint so your agent knows whether the token reached the inbox before proceeding. The gated_send oversight mode lets agents read inboxes and monitor delivery autonomously — low risk — while routing outbound authentication sends through a lightweight approval step. This keeps high-trust sends auditable without adding latency to the happy path.
Your backend or agent generates a cryptographically secure token — HMAC-SHA256, TOTP, or random bytes — and stores it with an expiry timestamp. MultiMail does not generate or store tokens. You own the secret material, expiry logic, and single-use enforcement.
Pass the token embedded in a magic link URL, or as a standalone OTP code, to the send_email endpoint. Set priority: 'high' to bypass standard rate-limit queuing. MultiMail validates the from address against your verified sender domains before accepting the request and signs the outbound message with DKIM on your domain.
MultiMail routes the message through hardened sending infrastructure and fires a delivery webhook to your endpoint when the message is handed off to the recipient's MX. Your agent correlates the message_id from the send response to the webhook event, confirming the token reached the inbox before the expiry window closes.
Bounced or deferred messages trigger a failure webhook with a status code and error detail. Your agent can act on this — retry with a secondary address, fall back to an alternative channel, or surface the failure to a human approver via the gated approval queue. MultiMail does not silently drop bounces.
If the recipient mailbox is a MultiMail address, use read_email and tag_email to mark the authentication thread as consumed once login completes. This gives you a clean audit trail: sent, delivered, consumed — or expired without use.
from multimail import MultimailClient
import secrets
import time
client = MultimailClient(api_key="$MULTIMAIL_API_KEY")
"cm"># Your auth layer generates the token — MultiMail never sees raw secrets
raw_token = secrets.token_urlsafe(32)
expiry = int(time.time()) + 600 "cm"># 10-minute window
magic_link = f"https://app.yourproduct.com/auth/verify?token={raw_token}&exp={expiry}"
result = client.send_email(
mailbox_id="[email protected]",
to="[email protected]",
subject="Your secure sign-in link",
html=f"""
<p>Click the link below to sign in. It expires in 10 minutes.</p>
<p><a href="{magic_link}">Sign in to YourProduct</a></p>
<p>If you didn&"cm">#039;t request this, you can ignore this email.</p>
<p style="color:#888;font-size:12px;">
This link was generated for your current session and can only be used once.
</p>
""",
text=f"Sign in: {magic_link}\n\nExpires in 10 minutes. If you didn&"cm">#039;t request this, ignore this email.",
priority="high",
tags=["auth", "magic-link"]
)
# Store message_id — delivery confirmation arrives at your webhook endpoint
print(f"Queued: {result.message_id}, status: {result.status}")Generate and deliver a passwordless sign-in link. The SDK call returns a message_id you use to correlate with the delivery webhook.
"cm"># In production use a TOTP library (pyotp, speakeasy) — this is illustrative
OTP="847291"
curl -X POST https://api.multimail.dev/v1/send_email \
-H "Authorization: Bearer $MULTIMAIL_API_KEY" \
-H "Content-Type: application/json" \
-d &"cm">#039;{
"mailbox_id": "[email protected]",
"to": "[email protected]",
"subject": "Your one-time sign-in code",
"html": "<p>Your sign-in code is <strong style=\\"font-size:28px;letter-spacing:6px;\\">847291</strong></p><p>This code expires in 10 minutes and can only be used once.</p><p style=\\"color:#888;font-size:12px;\\">If you did not request this code, you can ignore this email.</p>",
"text": "Your sign-in code is 847291. Expires in 10 minutes. Do not share this code.",
"priority": "high",
"tags": ["auth", "otp"]
}&"cm">#039;
"cm"># Response:
"cm"># {
"cm"># "message_id": "msg_01abc...",
"cm"># "status": "queued",
"cm"># "queued_at": "2026-04-19T10:00:00Z"
"cm"># }
"cm">#
"cm"># Delivery confirmation fires to your webhook:
"cm"># POST https://yourproduct.com/webhooks/multimail
"cm"># {"event": "delivered", "message_id": "msg_01abc...", "delivered_at": "2026-04-19T10:00:04Z"}Direct API call to deliver a 6-digit one-time password from any language or serverless function.
from multimail import MultimailClient
client = MultimailClient(api_key="$MULTIMAIL_API_KEY")
def send_auth_email(user_email: str, magic_link: str) -> dict:
"""
Send a magic link. Returns immediately — delivery confirmation
arrives asynchronously at your /webhooks/multimail endpoint.
"""
result = client.send_email(
mailbox_id="[email protected]",
to=user_email,
subject="Your secure sign-in link",
html=f&"cm">#039;<p>Sign in: <a href="{magic_link}">{magic_link}</a></p>'
f&"cm">#039;<p>Expires in 10 minutes. One-time use only.</p>',
text=f"Sign in: {magic_link}\nExpires in 10 minutes.",
priority="high",
tags=["auth", "magic-link"]
)
return {"message_id": result.message_id, "status": result.status}
"cm"># Webhook handler — your agent acts on delivery status
def handle_multimail_webhook(event: dict):
message_id = event["message_id"]
if event["event"] == "delivered":
"cm"># Token delivery confirmed — update session state
mark_token_as_delivered(message_id)
elif event["event"] in ("bounced", "failed"):
"cm"># Agent escalates: retry, fallback channel, or human review
error_detail = event.get("error_detail", "unknown")
escalate_delivery_failure(message_id, error_detail)Full agent loop: send the authentication email, handle delivery confirmation via webhook, escalate failures. Works inside any agent framework that can call HTTP endpoints.
"cm">// MCP tool invocation — send_email
"cm">// Works in Claude Desktop, Cursor, Windsurf, and any MCP-compatible client
{
"mailbox_id": "[email protected]",
"to": "[email protected]",
"subject": "Your secure sign-in link",
"html": "<p>Sign in here: <a href='https://app.yourproduct.com/auth/verify?token=aBcDeFgH'>Click to sign in</a></p><p>Expires in 10 minutes. One-time use only.</p><p style='color:#888;font-size:12px;'>If you did not request this, you can safely ignore this email.</p>",
"text": "Sign in: https:"cm">//app.yourproduct.com/auth/verify?token=aBcDeFgH\nExpires in 10 minutes.",
"priority": "high",
"tags": ["auth", "magic-link"]
}
// MCP server response:
// {
// "message_id": "msg_01abc...",
// "status": "queued",
// "queued_at": "2026-04-19T10:00:00Z"
"cm">// }When MultiMail is connected as an MCP server, send authentication emails directly from any MCP-compatible client using the send_email tool.
Authentication tokens are typically valid for 10 minutes. MultiMail's high-priority send path with webhook delivery confirmation gives your agent a confirmed delivery signal within seconds — not after the token has already expired.
Authentication emails are high-phishing-target messages. MultiMail signs every send with DKIM on your verified sender domain, improving deliverability and giving recipients a cryptographic signal that the message is legitimate, not a spoofed clone.
Every authentication email is logged with sender, recipient, timestamp, and delivery status. Under gated_send mode, outbound sends are also visible to a human reviewer, giving you an auditable trail for SOC 2 compliance and incident response.
Bounced or deferred messages trigger webhooks with actionable status codes. Your agent can retry, fall back to an alternative channel, or escalate to a human approver. MultiMail does not silently discard delivery failures.
Dedicate a mailbox (e.g., [email protected]) to authentication sends to isolate reputation from marketing or notification traffic. A spam complaint on a newsletter cannot affect delivery rates for your login flows.
Email infrastructure built for AI agents. Verifiable identity, graduated oversight, and a 50-tool MCP server. Formally verified in Lean 4.