Send a message from a mailbox
POST
/v1/email/mailboxes/{mailbox_id}/messages
curl -X POST "https://us1.platform.bird.com/v1/email/mailboxes/{mailbox_id}/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": [
"customer@example.com"
],
"subject": "Your quote",
"text": "Hi — here is the quote you asked for."
}'Sends a new message from the mailbox's own address and starts a new conversation with it. The request mirrors the plain send request minus from — the mailbox is the sender identity — and Bird mints the RFC 5322 Message-ID, so later replies from the recipients thread back into the conversation automatically. The send is recorded in the mailbox's durable memory and returned as the conversation's first message. Scheduled sends are not accepted on the mailbox surface. A suspended mailbox cannot send and returns 403.
Anfrage-Nutzlast
to
array of string or object
erforderlich
Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (Jane <jane@example.com>), or an object with an optional display name.
Untergeordnete Parameter anzeigen
to.email
string
erforderlich
Email address.
to.name
string
Display name shown alongside the address in mail clients.
cc
array of string or object
CC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (Jane <jane@example.com>), or an object with an optional display name.
Untergeordnete Parameter anzeigen
cc.email
string
erforderlich
Email address.
cc.name
string
Display name shown alongside the address in mail clients.
bcc
array of string or object
BCC recipients. Each entry is a plain email string, an RFC 5322 mailbox string (Jane <jane@example.com>), or an object with an optional display name.
Untergeordnete Parameter anzeigen
bcc.email
string
erforderlich
Email address.
bcc.name
string
Display name shown alongside the address in mail clients.
subject
string
erforderlich
Message subject line.
html
string
HTML body. At least one of html or text must be provided.
text
string
Plain-text body. At least one of html or text must be provided.
reply_to
array of string or object
Reply-To addresses. When omitted, the mailbox's default_reply_to applies (replies then come back to the mailbox itself).
Untergeordnete Parameter anzeigen
reply_to.email
string
erforderlich
Email address.
reply_to.name
string
Display name shown alongside the address in mail clients.
attachments
array of object
File attachments. The send is rejected when the estimated generated message size exceeds 20 MB (bodies plus all attachments after base64 encoding). Attachment metadata endures on the message's attachment_manifest; the bytes are downloadable for 30 days.
Untergeordnete Parameter anzeigen
attachments.filename
string
erforderlich
Filename shown to the recipient. Required.
attachments.content
string
erforderlich
Base64-encoded attachment bytes. Required. Counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
attachments.path
string
Preview feature — provide a URL and Bird fetches the attachment for you. Currently unavailable. Use content instead. The schema currently requires content, so a request with only path is rejected with 422 for missing content; a request supplying both content and path is rejected with 422 unsupported_feature until this preview ships. When generally available: HTTPS-only, single redirect followed and re-validated, private IP ranges blocked, request timeout enforced, fetched content counts toward the 20 MB estimated generated message-size cap after encoding and MIME wrapping.
attachments.content_type
string
MIME type. Inferred from filename extension when omitted. Used to enforce the blocklist of disallowed executable / script types.
attachments.content_id
string
RFC 2392 Content-ID. When set, the attachment is rendered inline and can be referenced from the HTML body as <img src="cid:{content_id}"/>. When omitted, the attachment is rendered as a regular file attachment.
tags
array of object
Structured {name, value} labels for filtering and analytics on the sent-message log. Cap: 20 tags per send.
Untergeordnete Parameter anzeigen
tags.name
string
erforderlich
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
tags.value
string
erforderlich
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
metadata
object
Arbitrary JSON object stored on the send and echoed in webhook payloads. Cap: 2 KB serialized.
category
string
Content classification — controls suppression policy. marketing blocks on all suppression reasons; transactional allows delivery through complaint and unsubscribe suppressions. Default: transactional.
Antwort-Payload
id
string
erforderlich
Message ID. Received messages carry a rem_ ID, sent messages an em_ ID — the same IDs used by the received-message and sent-message logs.
direction
string
erforderlich
Direction of the message — inbound for a received message, outbound for a sent one.
channel
string
erforderlich
Channel this message was carried on. Always email.
thread_id
string
erforderlich
Conversation this message belongs to.
from
string
erforderlich
Sender address.
to
array of string
erforderlich
Recipient addresses on the To line.
cc
array of string
erforderlich
Recipient addresses on the Cc line. Empty when the message had none.
delivered_to
nullable string
erforderlich
Address the message was actually delivered to, when it differs from the mailbox address (for example mail routed in from another address). Null for sent messages and for mail addressed directly to the mailbox.
subject
nullable string
erforderlich
Message subject. Null when the message had no subject.
preview
nullable string
erforderlich
Short plain-text preview of the message body.
extracted_text
nullable string
Plain-text content of the message with quoted history stripped — readable for the mailbox's full retention period, both directions. Always present when fetching a single message; on list endpoints it is included only when the request sets include=extracted_text. Null when no text could be extracted.
read
nullable boolean
erforderlich
Whether the message has been marked read. Null for sent messages.
disposition
nullable string
erforderlich
Where the message landed: inbox for accepted mail, blocked (receive policy or rules), or unauthenticated (failed sender authentication). Null for sent messages. Trash state is carried separately in trashed_at.
status
nullable string
erforderlich
Folded delivery status of a sent message: accepted, sent (provider handoff), delivered (all attempted recipients delivered), or failed (terminal failure). Null for received messages.
recipients
nullable array
erforderlich
Terminal per-recipient delivery outcomes of a sent message, folded in as they become known — part of the message's durable memory. Null for received messages and before any recipient reaches a terminal state. Per-recipient event detail lives on the sent-message log (source) for 30 days.
spf_pass
nullable boolean
erforderlich
Whether SPF passed for the sender of a received message. Null for sent messages and when no verdict was computable. Part of the message's durable memory — readable for the mailbox's full retention period, so the verdict survives after the 30-day inbound log has expired.
dkim_pass
nullable boolean
erforderlich
Whether DKIM passed for the sender of a received message. Null for sent messages and when no verdict was computable. Durable for the mailbox's retention period.
dmarc_pass
nullable boolean
erforderlich
Whether DMARC passed for the sender of a received message. Null for sent messages and when no verdict was computable. Durable for the mailbox's retention period.
trashed_at
nullable string
erforderlich
When the message was moved to the trash, or null when it is not trashed. Trashed messages are purged 30 days after trashing; restore it with PATCH {"trashed": false} before then.
rank
number
Relevance rank of this result. Present only on search results, higher is more relevant.
attachment_count
integer
erforderlich
Number of attachments on the message.
attachment_manifest
array of object
erforderlich
Attachment metadata (filename, content type, size). Remains readable for the mailbox's retention period even after the attachment bytes themselves have expired.
Untergeordnete Attribute anzeigen
attachment_manifest.id
string
erforderlich
Attachment ID, used to download the attachment bytes.
attachment_manifest.filename
nullable string
erforderlich
Original filename, or null when the attachment had none.
attachment_manifest.content_type
nullable string
erforderlich
MIME content type, or null when it could not be determined.
attachment_manifest.size
integer
erforderlich
Attachment size in bytes.
reference_ids
array of string
erforderlich
RFC 5322 References header entries used to thread the conversation.
labels
array of string
erforderlich
Labels applied to this message. A message carries at most 20 labels.
contact_id
nullable string
erforderlich
Contact linked to this message, or null when none is linked.
source
object
erforderlich
Link to the message's entry in the received-message or sent-message log, which carries delivery analytics such as per-recipient events. Log entries expire 30 days after the message occurred.
Untergeordnete Attribute anzeigen
source.resource
string
erforderlich
API path of the log entry for this message.
source.available_until
string
erforderlich
When the log entry (and the message's original rendered source) expires.
occurred_at
string
erforderlich
When the message was received or accepted for sending.