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.
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.
