post/email/send

Request

  • Base URL: https://api.useanima.sh/v1
  • URL: https://api.useanima.sh/v1/email/send
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Request body

agentIdstring required

ID of the agent sending the email

fromIdentityIdstring

Optional EmailIdentity ID to send from. An agent has exactly one email identity, so the only valid value is that one — supply it to assert which address you expect to send as, or omit it and the agent's identity is used. Discover the ID via GET /agents/{agentId}/email-identities.

tostring[] required

List of recipient email addresses (at least one required)

ccstring[]

List of CC recipient email addresses

bccstring[]

List of BCC recipient email addresses

subjectstring required

Email subject line (max 998 characters per RFC 2822)

bodystring required

Plain-text body of the email

bodyHtmlstring

Optional HTML body of the email

headersobject

Custom email headers as key-value pairs

metadataobject

Arbitrary key-value metadata to attach to the message

inReplyTostring

The message this email replies to: either an RFC 5322 Message-ID (with or without angle brackets, e.g. from an inbound email's externalId) or an Anima message id (cuid). The reply joins that message's thread and emits In-Reply-To/References so external clients thread it too.

referencesstring[]

Explicit References chain, oldest first: one RFC 5322 Message-ID per entry (an email's externalId). Anything else, such as an Anima message id, is ignored. On a reply, this chain is used only if it includes the replied-to message's Message-ID; otherwise, or if omitted, the chain is derived from the replied-to message automatically (its References plus its Message-ID).

Response

OK

idstring required

Unique identifier of the message

agentIdstring required

ID of the agent that sent or received the message

inboxIdstring nullable required

ID of the inbox this message belongs to — the inbox it was delivered to (inbound) or sent from (outbound). Null when no inbox backs the address: SMS/MMS/voice messages, and email sent from an email identity that has no inbox (such as a custom-domain identity added to an agent). Pass it to GET /messages?inboxId= to list one inbox's mail.

channel'EMAIL' | 'SMS' | 'MMS' | 'VOICE' | 'WHATSAPP' | 'RCS' required

Communication channel used

direction'INBOUND' | 'OUTBOUND' required

Whether the message was inbound or outbound

status'QUEUED' | 'SENT' | 'DELIVERED' | 'FAILED' | 'BOUNCED' | 'BLOCKED' | 'PENDING_APPROVAL' required

Current delivery status

fromAddressstring required

Sender address (email or phone number)

toAddressstring required

Recipient address (email or phone number)

subjectstring nullable required

Message subject line, or null for channels that do not support subjects

bodystring required

Plain-text content of the message

bodyHtmlstring nullable required

HTML content of the message, or null if not available

extractedTextstring nullable required

Plain-text body with the quoted reply chain and signature stripped — just what this sender actually wrote. Read this instead of body to avoid re-reading (and paying for) the whole thread on every message. Null when nothing was extracted: non-email channels, messages your agent sent, and mail received before this field existed — so extractedText ?? body is always correct. Best-effort and heuristic; body remains the verbatim source of truth. Known weak cases: forwards and bottom-posted replies have no separable 'new' part, so this returns the full body rather than nothing.

extractedHtmlstring nullable required

HTML body with quoted reply chains removed. Same semantics as extractedText; bodyHtml stays verbatim. Quoting styles that mark the chain with a sibling element rather than wrapping it (Outlook) are not stripped here — extractedText still is.

headersobject nullable required

Raw message headers as key-value pairs, or null

metadataobject nullable required

Arbitrary metadata attached to the message, or null

threadIdstring nullable required

Thread identifier for conversation grouping, or null

labelsstring[] required

Workflow labels on this message. Always contains exactly one of the system labels unread or read; may also contain archived, spam (the inbound spam verdict — see includeSpam on list/search), and any labels you add yourself. Stored lowercase, deduped, and sorted. Change them with PATCH /messages/{id}/labels.

inReplyTostring nullable required

Message ID this message is replying to, or null

externalIdstring nullable required

External identifier, or null. For email: the RFC 5322 Message-ID (bare, no angle brackets) — pass it as inReplyTo to reply in-thread. For SMS: the provider-assigned message id.

deletedAtstring date-time nullable required

When this message was moved to Trash, or null if it is live. Deleted messages are hidden from listings unless deleted is set to include or only, and can be brought back with POST /messages/{id}/restore. Nothing purges them.

sentAtstring date-time nullable required

Timestamp when the message was sent, or null if not yet sent

receivedAtstring date-time nullable required

Timestamp when the message was received, or null for outbound messages

readAtstring date-time nullable required

Outbound WhatsApp and RCS messages only: when the recipient's device reported the message as read. Null for inbound messages and for every other channel. Unrelated to the read and unread labels, which record whether the agent has handled a message.

createdAtstring date-time required

Timestamp when the message record was created

updatedAtstring date-time required

Timestamp when the message record was last updated

Changes

No recorded changes to this operation across all 1 revision of this API.