Send a transactional email

Transactional email is the mail your product sends one person at a time — receipts, password resets, order confirmations. This guide builds a single sendReceipt(order) function you call from checkout. It sends an HTML receipt, never double-sends when the request is retried, and reports delivery back so you can mark the order fulfilled.

Verify a domain and create the inbox

Verify the domain you send from, then create the inbox the receipts come from. Both are one-time steps.

dairo domain add yourapp.com
dairo domain recheck yourapp.com          # repeat until the domain verifies
dairo inbox create receipts --domain yourapp.com
# → inbox_123  receipts@yourapp.com

The DNS records to publish are covered in Add and verify a domain. The code below expects an API key with the messages:send scope in the DAIRO_API_KEY environment variable.

Send the receipt

One call sends the receipt. Two details keep it safe to run from checkout:

An idempotency key tied to the order. A retry with the same key returns the original send instead of mailing a second receipt. See Retries and idempotency.
A complaint guard. If the recipient previously reported your mail as spam, Dairo refuses the send with a 400 instead of letting it damage your sending reputation. Treat that as “stop emailing this person,” not an error to retry.

import { Dairo, DairoError } from "dairo";

const dairo = new Dairo({ apiKey: process.env.DAIRO_API_KEY! });
const RECEIPTS_INBOX = "inbox_123";

export async function sendReceipt(order: {
  id: string;
  email: string;
  total: string;
}): Promise<string | null> {
  try {
    const result = await dairo.messages.send(
      {
        inboxId: RECEIPTS_INBOX,
        to: order.email,
        subject: `Your receipt for order #${order.id}`,
        html: `<h1>Thanks for your order</h1>
               <p>Order <strong>#${order.id}</strong></p>
               <p>Total: <strong>${order.total}</strong></p>`,
      },
      // Same order, same key: a retry returns the original send.
      { idempotencyKey: `receipt-${order.id}` },
    );
    return result.id; // the message id — store it on the order
  } catch (err) {
    if (
      err instanceof DairoError &&
      err.status === 400 &&
      err.message.includes("complained")
    ) {
      await markUnmailable(order.email); // recipient reported spam — stop contacting them
      return null;
    }
    throw err;
  }
}

from dairo import Dairo, DairoError

dairo = Dairo()  # reads DAIRO_API_KEY
RECEIPTS_INBOX = "inbox_123"

def send_receipt(order: dict) -> str | None:
    try:
        result = dairo.messages.send(
            inbox_id=RECEIPTS_INBOX,
            to=order["email"],
            subject=f"Your receipt for order #{order['id']}",
            html=(
                "<h1>Thanks for your order</h1>"
                f"<p>Order <strong>#{order['id']}</strong></p>"
                f"<p>Total: <strong>{order['total']}</strong></p>"
            ),
            # Same order, same key: a retry returns the original send.
            idempotency_key=f"receipt-{order['id']}",
        )
        return result.id  # the message id — store it on the order
    except DairoError as err:
        if err.status_code == 400 and "complained" in err.message:
            mark_unmailable(order["email"])  # recipient reported spam
            return None
        raise

curl -X POST https://api.dairo.app/v1/messages \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-1042" \
  -d '{
    "inboxId": "inbox_123",
    "to": "ada@example.com",
    "subject": "Your receipt for order #1042",
    "html": "<h1>Thanks for your order</h1><p>Order <strong>#1042</strong> — Total: <strong>$48.00</strong></p>"
  }'

An immediate send completes while the request is open, so the response is the final outcome — sent with an id, or a precise error, never a “queued, maybe later”:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "sent",
  "providerMessageId": "msg_pm_9f8c2a1b4e7d",
  "warnings": [],
  "channel": "email"
}

Store the returned id on the order record. It is how you match the delivery, bounce, and complaint events that arrive later. When the recipient has previously complained, the send is refused instead:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Could not send email: recipient complained (ada@example.com). Recipient complained — do not contact again. To override deliberately, set ignoreComplaints=true in the API/MCP request or pass --ignore-complaints in the CLI."
  }
}

A complaint refusal means stop, not retry. Overriding it with ignoreComplaints is a deliberate human decision, never an automation default — Land in the inbox covers when that is appropriate.

Rich receipts with React

For anything beyond simple markup, send a React Email component and Dairo renders it — no build step or render dependency in your app. source accepts up to 64 KiB of component code and props up to 32 KiB of JSON.

await dairo.messages.send(
  {
    inboxId: RECEIPTS_INBOX,
    to: order.email,
    subject: `Your receipt for order #${order.id}`,
    react: {
      source: `export default function Receipt({ id, total }) {
        return (
          <div>
            <h1>Thanks for your order</h1>
            <p>Order #{id} — Total: {total}</p>
          </div>
        );
      }`,
      props: { id: order.id, total: order.total },
    },
  },
  { idempotencyKey: `receipt-${order.id}` },
);

One send carries exactly one body — text, html, react, or a stored template. Combining two in a single request returns a 400. If every receipt shares one layout, save it as a template and send it by reference instead of inlining the source each time.

Confirm delivery

Subscribe once to the delivery events and match each one back to its order by messageId — no polling.

dairo webhook create \
  --url https://yourapp.com/dairo/webhook \
  --event message.delivered \
  --event message.bounced \
  --event message.complained
# Store the printed signing secret — it is shown once.

Handle the events inside a signature-verified endpoint. Build a webhook receiver is the complete endpoint this handler slots into:

switch (event.type) {
  case "message.delivered":
    await markReceiptDelivered(event.data.messageId);
    break;
  case "message.bounced":
    // bounceType "Permanent" means the address is dead — stop sending to it.
    await flagBadAddress(event.data.recipient, event.data.bounceType);
    break;
  case "message.complained":
    // Dairo already blocks future sends to this address; mirror it in your data.
    await markUnmailable(event.data.recipient);
    break;
}

If you would rather not run a receiver, poll instead: dairo.messages.get(messageId) returns the send with its current status, and dairo.messages.listEvents(messageId) returns its delivery timeline.

Next steps

Send an email — every request field, plus scheduling, attachments, and contacts.
Track delivery — the status lifecycle behind the message.* events.
Webhooks — every event type, header, and payload.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

Send a transactional email

Verify a domain and create the inbox

Send the receipt

Rich receipts with React

Confirm delivery

Next steps

​Verify a domain and create the inbox

​Send the receipt

​Rich receipts with React

​Confirm delivery

​Next steps

Verify a domain and create the inbox

Send the receipt

Rich receipts with React

Confirm delivery

Next steps