Request
- Base URL: https://api.useanima.sh/v1
- URL: https://api.useanima.sh/v1/messages/{id}/labels
- Auth: one of:
- HTTP bearer
- API key in header X-API-Key
Path parameters
ID of the message to relabel
Request body
Labels to add. Adding read removes unread and vice versa — they are one state under two names, and a message always carries exactly one of them.
Labels to remove. Removing unread marks the message read (and removing read marks it unread); a message is never left with neither.
Response
OK
Unique identifier of the message
ID of the agent that sent or received the message
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.
Communication channel used
Whether the message was inbound or outbound
Current delivery status
Sender address (email or phone number)
Recipient address (email or phone number)
Message subject line, or null for channels that do not support subjects
Plain-text content of the message
HTML content of the message, or null if not available
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.
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.
Raw message headers as key-value pairs, or null
Arbitrary metadata attached to the message, or null
Thread identifier for conversation grouping, or null
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.
Message ID this message is replying to, or null
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.
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.
Timestamp when the message was sent, or null if not yet sent
Timestamp when the message was received, or null for outbound messages
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.
Timestamp when the message record was created
Timestamp when the message record was last updated
Changes
No recorded changes to this operation across all 1 revision of this API.