API recipes & code patterns
Ready-to-use code patterns for the eight most common email scenarios — welcome emails, OTPs, invoices with attachments, dynamic templates, scheduled sends, batch delivery, and inbound webhooks.
Looking for quick, copy-pasteable code for a specific use case? Here are production-tested patterns for the eight most common email scenarios in emitd.
All examples work with either the official @emitd/sdk or plain HTTPS fetch / requests.
1. User welcome email (HTML + Plaintext)
Send a branded welcome email immediately upon signup. Providing both html_body and text_body ensures maximum deliverability across all mail clients (including Apple Watch and terminal email readers).
import { Emitd } from "@emitd/sdk";
const emitd = new Emitd({ apiKey: process.env.EMITD_API_KEY! });
const { message_id } = await emitd.email.send({
from: "Acme Team <welcome@acme.com>",
to: ["newuser@example.com"],
subject: "Welcome to Acme — your account is ready",
html_body: `
<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
<h1>Welcome to Acme, Alex!</h1>
<p>Thanks for creating an account. You can now access your dashboard and create your first project.</p>
<a href="https://app.acme.com/get-started" style="display:inline-block;padding:12px 24px;background:#2563eb;color:#fff;text-decoration:none;border-radius:6px;">Get Started</a>
</div>
`,
text_body: "Welcome to Acme, Alex! Thanks for creating an account. Get started at https://app.acme.com/get-started",
message_stream: "outbound",
tags: { source: "onboarding", tier: "free" },
});2. Password reset / Login OTP (Sub-second priority)
Authentication emails demand instant delivery. Use message_stream: "outbound" to route through emitd's high-priority transactional IP pool. Avoid tracking pixels on OTPs to prevent spam false positives.
{
"from": "security@acme.com",
"to": ["user@example.com"],
"subject": "Your Acme login code: 849204",
"html_body": "<p>Your one-time login code is <strong>849204</strong>. It expires in 10 minutes.</p>",
"text_body": "Your one-time login code is 849204. It expires in 10 minutes.",
"message_stream": "outbound",
"track_opens": false,
"track_clicks": false,
"tags": { "type": "auth_otp" }
}3. Transactional receipt with PDF attachment
Send an invoice or receipt with a file attachment. You can supply the file inline as base64 or upload it once to R2 via POST /v1/attachments.
{
"from": "billing@acme.com",
"to": ["finance@client.com"],
"subject": "Invoice #4029 from Acme Inc.",
"html_body": "<p>Thank you for your business. Your receipt is attached.</p>",
"message_stream": "outbound",
"attachments": [
{
"filename": "Invoice-4029.pdf",
"content_type": "application/pdf",
"content": "JVBERi0xLjQKJcTl8uXrp/Og0MTGCjQgMCBvYmoK..."
}
]
}4. Server-side dynamic template rendering
Instead of embedding HTML markup in application code, create a template in the console (or with the AI Design Studio) and pass variable models dynamically:
{
"from": "orders@acme.com",
"to": ["customer@example.com"],
"template_alias": "order-confirmation",
"template_model": {
"customer_name": "Sarah",
"order_id": "ORD-92810",
"total_amount": "$149.00",
"tracking_url": "https://acme.com/track/ORD-92810"
},
"message_stream": "outbound"
}emitd validates the template version, renders Handlebars variables server-side, and enqueues the email in a single atomic operation.
5. Scheduled send (Reminders & digests)
Hold an email and automatically dispatch it at a specific time in the future by providing scheduled_at (epoch milliseconds UTC):
{
"from": "reminders@acme.com",
"to": ["attendee@example.com"],
"subject": "Your webinar begins in 1 hour",
"html_body": "<p>Don't forget — our workshop starts at 2:00 PM.</p>",
"scheduled_at": 1783389600000,
"message_stream": "outbound"
}While still scheduled, you can reschedule via PATCH /v1/email/{id} or cancel with DELETE /v1/email/{id}.
6. Idempotent retries (Safe network blips)
In distributed architectures, timeouts and network hiccups can cause clients to retry requests. Pass an Idempotency-Key header on any send:
curl https://api.emitd.com/v1/email \
-H "Authorization: Bearer $EMITD_API_KEY" \
-H "Idempotency-Key: payment_charge_892147_email" \
-H "Content-Type: application/json" \
-d '{ ... }'If the request is retried within 24 hours, emitd replays the original 202 Accepted result with the existing message_id without sending a second copy or charging additional quota.
7. Bulk email sending (Up to 100 per call)
When dispatching notifications to multiple recipients simultaneously, POST /v1/email/batch processes up to 100 messages in one network roundtrip:
{
"items": [
{
"from": "news@acme.com",
"to": ["user1@example.com"],
"subject": "Monthly product digest",
"html_body": "<h1>Updates for October</h1>...",
"message_stream": "broadcast"
},
{
"from": "news@acme.com",
"to": ["user2@example.com"],
"subject": "Monthly product digest",
"html_body": "<h1>Updates for October</h1>...",
"message_stream": "broadcast"
}
]
}8. Inbound email parsing webhook
Receive incoming emails on your custom domain without running an SMTP server. When a recipient replies to your email, emitd posts parsed JSON to your webhook endpoint:
{
"type": "inbound.received",
"message_id": "inb_7f840a1b",
"timestamp": 1783389612000,
"data": {
"from": "customer@gmail.com",
"to": "support@yourdomain.com",
"subject": "Re: Order #92810 inquiry",
"text_body": "Can you please update my shipping address to 123 Main St?",
"html_body": "<div>Can you please update my shipping address to 123 Main St?</div>",
"headers": {
"message-id": "<CA+d128@mail.gmail.com>",
"in-reply-to": "<msg_2h8Kd0Rk9Qa@emitd.com>"
},
"attachments": []
}
}Learn how to configure MX routing and verify signatures in the Inbound email guide.