Invoice #1234

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Email

> Send transactional and marketing emails through the Orbit API

# Email

Send beautiful, reliable emails through Orbit's email infrastructure powered by Resend. Build templates with React Email for pixel-perfect rendering across all clients, or send simple HTML and plain text.

## Send an Email

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/email \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "notifications@yourdomain.com",
    "subject": "Your invoice is ready",
    "html": "<h1>Invoice #1234</h1><p>Your invoice for $49.00 is attached.</p>",
    "attachments": [
      {
        "filename": "invoice-1234.pdf",
        "content_type": "application/pdf",
        "content": "base64-encoded-content"
      }
    ]
  }'
```

## Using Templates

Templates are a two-step flow: render your email-builder blocks into a complete HTML document, then send that HTML through the standard send endpoint. The direct `/messages/email` endpoint takes a finished `html` (or `text`) body — it does not accept a `template_id` or `variables`.

**Step 1 — render blocks to HTML** with `POST /api/v1/messages/email-builder/render`. Merge values inline using `{{...}}` tags in your block content:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/email-builder/render \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_email",
    "blocks": [
      {
        "type": "header",
        "content": { "title": "Welcome, Alex!" }
      },
      {
        "type": "text",
        "content": { "text": "Thanks for joining Acme Corp. We are glad to have you." }
      }
    ]
  }'
```

The response contains the rendered HTML:

```json theme={null}
{ "data": { "html": "<!DOCTYPE html>...", "templateId": "etpl_..." } }
```

**Step 2 — send the rendered HTML** through `POST /api/v1/messages/email`:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/email \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "hello@yourdomain.com",
    "subject": "Welcome to Acme Corp",
    "html": "<!DOCTYPE html>..."
  }'
```

Save reusable templates with `POST /api/v1/messages/email-builder/save` and list them with `GET /api/v1/messages/email-builder/list`.

## Features

* **Transactional email** — receipts, notifications, password resets
* **Marketing email** — campaigns, newsletters, announcements
* **React Email templates** — build and preview templates with React components
* **Attachments** — PDF, images, and other file types (up to 25 MB total, 10 MB per file, with a MIME allowlist). Each attachment requires a `content_type`.
* **Custom domains** — send from your own domain with DKIM, SPF, and DMARC
* **Tracking** — open tracking, click tracking, and engagement webhooks
* **Suppression lists** — automatic bounce and complaint handling

## Domain Setup

To send from your own domain, add the following DNS records in **Channels > Email > Domains**:

| Record      | Type  | Purpose              |
| ----------- | ----- | -------------------- |
| DKIM        | TXT   | Email authentication |
| SPF         | TXT   | Sender authorization |
| DMARC       | TXT   | Delivery policy      |
| Return-Path | CNAME | Bounce handling      |

Orbit verifies your DNS records automatically — verification typically completes within minutes.

## Webhook Events

Email engagement fires its own event types:

| Event           | Description                      |
| --------------- | -------------------------------- |
| `email.opened`  | Recipient opened the email       |
| `email.clicked` | Recipient clicked a tracked link |

Delivery outcomes are reported on the channel-agnostic message events, not on
email-specific types. Subscribe to these to track delivery, bounces, and complaints:

| Event               | Description                                        |
| ------------------- | -------------------------------------------------- |
| `message.delivered` | Email accepted by the recipient server             |
| `message.failed`    | Email bounced (hard or soft) or was marked as spam |

Each `message` event carries `channel: "email"` and the originating `message_id`,
so you can filter for email traffic and correlate back to the send.