Skip to main content
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. 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, 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.
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. 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.
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.
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.