Skip to Content
Docs
Guides

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.

POST /v1/email
{
  "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.

POST /v1/email with Base64 attachment
{
  "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:

POST /v1/email with template
{
  "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):

POST /v1/email with scheduling
{
  "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:

POST /v1/email/batch
{
  "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:

Incoming webhook event: inbound.received
{
  "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.

On this page