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

# Send a transactional email

> Send your application's composed message using your organization's verified sending identity.

`POST /v1/transactional-emails` sends one message to a primary recipient, with
optional CC and BCC recipients. Your app supplies the words and structured body blocks.
Erdo renders matching HTML and plain text, sends the message, and records it in
the [sent email log](https://docs.erdo.ai/sent-email.md).

Use an **unscoped organization API key**. Sessions, guest tokens, external-user
tokens, and scoped API keys cannot send. Select the organization through the
usual authentication header; the body accepts no organization or sender identity.
The organization needs a [verified sending domain](https://docs.erdo.ai/sending-domains.md), either
its own or the effective identity inherited from its manager. A missing identity
returns `failed_precondition` instead of sending from Erdo's default address.

```json theme={null}
{
  "to": "buyer@example.com",
  "cc": ["desk@example.com"],
  "bcc": ["archive@example.com"],
  "subject": "Your receipt",
  "preheader": "Payment received.",
  "body": [
    {"type": "heading", "text": "Thank you"},
    {"type": "paragraph", "text": "We have received your payment."},
    {"type": "button", "label": "View receipt", "url": "https://example.com/receipts/123"}
  ],
  "attachments": ["file:6f0b8123-9915-45df-97d3-591e519b66ca"],
  "reply_to": "support@example.com",
  "idempotency_key": "receipt-123"
}
```

`to`, `subject`, `body`, and `idempotency_key` are required. `cc`, `bcc`, `preheader`,
`reply_to`, and `attachments` are optional. Each attachment is a `file:<id>` handle
from your organization's [files](https://docs.erdo.ai/files.md). The caller must be allowed to read every
file. A send accepts up to 20 files, 1 MiB per file and 5 MiB total. The email log
stores each file reference and its display metadata; it does not copy file bytes.
Addresses must be bare email addresses, with no
display names or duplicates across To, CC and BCC. The combined limit is 50
recipients, including the primary address. The subject
accepts at most 255 characters and cannot contain line breaks; the preheader
accepts at most 300. The key accepts at most 256 characters, starts with a letter or number,
and uses only letters, numbers, `.`, `_`, `:`, and `-`.

Body accepts 1–50 blocks. Supported types are `heading`, `subheading`,
`paragraph` (each with `text`), `details` (with `rows` of label/value strings),
`table` (with `headers` and `rows` of strings), `button` (with `label` and `url`),
`link_list` (with `urls`), and `divider`. Button and link-list URLs must be absolute
HTTP(S) or `mailto:` URLs. Raw HTML is not an input format.

```bash theme={null}
curl -X POST https://api.erdo.ai/v1/transactional-emails \
  -H "Authorization: Bearer $ERDO_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @message.json

erdo --org acme email send --file message.json
# Or: cat message.json | erdo --org acme email send --file -
```

MCP clients use `erdo_send_transactional_email` in the `messaging` toolset with
the same fields and credentials. `erdo email send --file message.json` accepts
the same `attachments` array.

```json theme={null}
{
  "message_id": "6f0b8123-9915-45df-97d3-591e519b66ca",
  "status": "sent",
  "replayed": false
}
```

`message_id` is Erdo's audit ID; use it with `GET /v1/emails/:emailID` or
`erdo email sent get <message_id>`. `sent` means the provider accepted the
message. Read the log for delivery, bounce, or complaint updates.

Reuse the same key and payload when retrying an uncertain result. An accepted
send returns its original ID and `status: "sent"`, with `replayed: true`, even
when its delivery status has since changed. A changed payload under the same
key returns `invalid_argument`. A concurrent send still in progress returns
`already_exists`. Ambiguous attempts beyond the provider's 24-hour deduplication
window require reconciliation rather than a resend. Keys are scoped to the
organization. CC and BCC recipients count toward the existing daily limit of 50
distinct recipients.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.