Skip to main content
POST
/
messages
/
email
cURL
curl --request POST \
  --url https://api.useanima.sh/v1/messages/email \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": "<string>",
  "to": [
    "jsmith@example.com"
  ],
  "subject": "<string>",
  "body": "<string>",
  "fromIdentityId": "<string>",
  "cc": [],
  "bcc": [],
  "bodyHtml": "<string>",
  "attachments": [
    {
      "filename": "<string>",
      "contentId": "<string>",
      "contentType": "<string>",
      "content": "<string>",
      "url": "<string>"
    }
  ],
  "headers": {},
  "metadata": {}
}
'
{
  "id": "<string>",
  "agentId": "<string>",
  "fromAddress": "<string>",
  "toAddress": "<string>",
  "subject": "<string>",
  "body": "<string>",
  "bodyHtml": "<string>",
  "headers": {},
  "metadata": {},
  "threadId": "<string>",
  "inReplyTo": "<string>",
  "externalId": "<string>",
  "sentAt": "2023-11-07T05:31:56Z",
  "receivedAt": "2023-11-07T05:31:56Z",
  "attachments": [
    {
      "id": "<string>",
      "filename": "<string>",
      "mimeType": "<string>",
      "sizeBytes": 1,
      "storageKey": "<string>",
      "url": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "detectedMimeType": "<string>"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Body

application/json

Request body for sending an email through an agent

agentId
string
required

ID of the agent sending the email

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
to
string<email>[]
required

List of recipient email addresses (at least one required)

Minimum array length: 1
subject
string
required

Email subject line (max 998 characters per RFC 2822)

Required string length: 1 - 998
body
string
required

Plain-text body of the email

Minimum string length: 1
fromIdentityId
string

Optional EmailIdentity ID to send from. Must belong to this agent and be verified. If omitted, the agent's primary identity is used. Use this to route different message types through different identities (e.g. transactional from @brawz.ai, support from @support.brawz.ai). List the agent's identities first via agent_email_identity_list to discover available IDs.

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
cc
string<email>[]

List of CC recipient email addresses

bcc
string<email>[]

List of BCC recipient email addresses

bodyHtml
string

Optional HTML body of the email

attachments
object[]

Optional file attachments. Max 25MB total across all attachments (after base64 decode for inline, after fetch for URL-source); max 20 attachments per email. Each entry provides either inline base64 content or a public url for server-fetch.

Maximum array length: 20
headers
object

Custom email headers as key-value pairs

metadata
object

Arbitrary key-value metadata to attach to the message

Response

200 - application/json

OK

Full message resource representation

id
string
required

Unique identifier of the message

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
agentId
string
required

ID of the agent that sent or received the message

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
channel
enum<string>
required

Communication channel used

Available options:
EMAIL,
SMS,
MMS,
VOICE
direction
enum<string>
required

Whether the message was inbound or outbound

Available options:
INBOUND,
OUTBOUND
status
enum<string>
required

Current delivery status

Available options:
QUEUED,
SENT,
DELIVERED,
FAILED,
BOUNCED,
BLOCKED,
PENDING_APPROVAL
fromAddress
string
required

Sender address (email or phone number)

toAddress
string
required

Recipient address (email or phone number)

subject
string | null
required

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

body
string
required

Plain-text content of the message

bodyHtml
string | null
required

HTML content of the message, or null if not available

headers
object | null
required

Raw message headers as key-value pairs, or null

metadata
object | null
required

Arbitrary metadata attached to the message, or null

threadId
string | null
required

Thread identifier for conversation grouping, or null

inReplyTo
string | null
required

Message ID this message is replying to, or null

externalId
string | null
required

Provider-assigned external identifier, or null

sentAt
string<date-time> | null
required

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

receivedAt
string<date-time> | null
required

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

attachments
object[]
required

File attachments associated with this message

createdAt
string<date-time>
required

Timestamp when the message record was created

updatedAt
string<date-time>
required

Timestamp when the message record was last updated