Transactional email

Transactional emails are automated, API-triggered messages to one recipient after something happens in your product — receipts, invites, password resets, magic links.

They are not campaigns and not Journey enrollments. You design the email once in Audryo, publish it, then your backend calls transactional_send whenever you need to deliver that template.

Reference: sendTransactionalEmail Scope: deliver Always send: Idempotency-Key derived from your business id (order id, reset token id, …)

How it works

1. Compose a Message Document in the product (or via API) with merge tags.
2. Publish the revision in the app (API: status: "confirmed").
3. Send from your backend with recipient email + optional data variables.
4. Audryo queues delivery through your connected ESP and records the delivery. In sandbox mode the email lands in the Sandbox inbox instead, and the response includes "sandbox": true.

Prerequisites

1. A verified sending identity (Resend recommended) — only once the project is live. In sandbox mode you can integrate without one.
2. A Message Document with status: "confirmed" — see Emails.
3. A workspace API token that includes deliver.

Personalization

• Contact properties: {{ contact.first_name }}
• Fallback when empty: {{ contact.first_name | "there" }}
• Data variables from the send call: {{ data.order_id }} or {{ order_id }}

Malformed filters are linted when you revise/confirm — fix them before going live. Data variable names are case-sensitive.

Send

email is required. Optionally pass:

• externalId — upsert/link a contact
• dataVariables — merge-tag values for this send
• contactProperties — update properties on the contact

curl -X POST "$AUDRYO_API_BASE/projects/$PROJECT_ID/message_documents/$MESSAGE_ID/transactional_send" \
  -H "Authorization: Bearer $AUDRYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-$ORDER_ID" \
  -d '{
    "email": "amelia@example.com",
    "externalId": "usr_9f1c2a",
    "dataVariables": {
      "order_id": "ord_1842",
      "total": "$42.00",
      "receipt_url": "https://app.example.com/orders/ord_1842"
    }
  }'

Eligibility and suppressions

Transactional sends still fail closed on hard suppressions (bounce, complaint, manual block, blocklist). Connect your ESP webhook so provider feedback stays fresh.

Unsubscribed marketing contacts may still receive genuine transactional mail when policy allows — but promotional content must not use this path.

Testing safely

1. Build your integration while the project is in sandbox mode. Every call runs the real pipeline, and the rendered email — with your dataVariables filled in — appears in Emails → Sandbox inbox. Check it there or read it with GET /sandbox_messages.
2. Use Audryo’s test delivery on the Message Document for visual checks.
3. For API integration tests, send with a stable Idempotency-Key so retries do not duplicate.
4. After going live, prefer internal addresses first; watch ESP logs and Audryo recipient reports before production traffic.

Common errors

Related

• Types of emails
• Emails
• Webhooks
• Best practices