Documentation
Sign inGet started

Send a message from a mailbox

POST
/v1/email/mailboxes/{mailbox_id}/messages
const msg = await bird.email.mailboxes.messages.create("mbx_01abc", {
  to: ["customer@example.com"],
  subject: "Hello",
  text: "Hi there!",
});
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, because the mailbox is who the message comes from. We set the RFC 5322 Message-ID, so later replies from the recipients thread back into the conversation automatically. The send is added to the mailbox's remembered messages and returned as the conversation's first message. A mailbox always sends immediately, so this endpoint does not accept a scheduled send. A suspended mailbox cannot send and returns 403.
请求载荷
to
array of string or object
必填
Primary recipients. Each entry is a plain email string, an RFC 5322 mailbox string (Jane <jane@acme.com>), or an object with an optional display name.
显示子参数
to.email
string
必填
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@acme.com>), or an object with an optional display name.
显示子参数
cc.email
string
必填
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@acme.com>), or an object with an optional display name.
显示子参数
bcc.email
string
必填
Email address.
bcc.name
string
Display name shown alongside the address in mail clients.
subject
string
必填
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).
显示子参数
reply_to.email
string
必填
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). Keep total raw attachment content at or below 15 MB for reliable headroom. Attachment metadata stays on the message's attachment_manifest, and the bytes are downloadable for 30 days.
显示子参数
attachments.filename
string
必填
The name the recipient sees on the attachment.
attachments.content
string
必填
The file's bytes, base64-encoded. What you send here counts toward the message's 20 MB limit after encoding and MIME wrapping, not at its raw size.
attachments.content_type
string
The file's MIME type. Leave it out and we work it out from the extension on filename. This is what we check against the list of executable and script types we refuse.
attachments.content_id
string
An RFC 2392 Content-ID for the file. Set it and the attachment is shown inline, so your HTML body can point at it with <img src="cid:{content_id}"/>. Leave it out and the file arrives as an ordinary attachment the recipient downloads.
tags
array of object
Structured {name, value} labels for filtering and analytics on the sent-message log. Cap: 20 tags per send.
显示子参数
tags.name
string
必填
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
tags.value
string
必填
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, which controls suppression policy:
  • marketing: Blocks on all suppression reasons.
  • transactional: Allows delivery through complaint and unsubscribe suppressions, for receipts, password resets, and similar operational mail.
Possible values: marketing, transactional
响应载荷
id
string
必填
Message ID. Received messages have a rem_ ID, sent messages an em_ ID: the same IDs used by the received-message and sent-message logs.
direction
string
必填
Which way the message went. inbound means you received it, outbound means you sent it.
Possible values: inbound, outbound
channel
string
必填
Channel this message lives on. Always email.
thread_id
string
必填
Conversation this message belongs to.
from
string
必填
Sender address.
to
array of string
必填
Recipient addresses on the To line.
cc
array of string
必填
Recipient addresses on the Cc line. Empty when the message had none.
delivered_to
nullable string
必填
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
必填
Message subject. Null when the message had no subject.
preview
nullable string
必填
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 tier, in 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.
labels
array of string
必填
Labels on this message. A received message always has exactly one placement label:
  • inbox: Accepted mail.
  • archive: The message's conversation was filed away.
  • spam: The message failed sender authentication.
  • blocked: The message was rejected by the mailbox's receive policy or rules.
A received message also has unread until it is read. trash marks a message in the trash, in either direction. Custom labels share the same list, and a message has at most 20 labels in total.
status
nullable string
必填
Folded delivery status of a sent message:
  • accepted: Accepted for sending.
  • sent: Handed off to the provider.
  • delivered: All attempted recipients delivered.
  • failed: Terminal failure.
Null for received messages.
recipients
nullable array
必填
Terminal per-recipient delivery outcomes of a sent message, filled in as each one becomes known and kept for the mailbox's full retention tier. 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.
authentication
nullable string
必填
Whether the sender of a received message was authenticated. pass means the sender's identity was verified. fail means it was checked and did not verify. unknown means no verdict could be determined, and the sender should not be treated as verified. Null for sent messages. This field is readable for the mailbox's full retention tier, so the verdict is still available after the 30-day received-message log has expired.
Possible values: pass, fail, unknown, null
spf_pass
nullable boolean
必填
Whether SPF passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.
dkim_pass
nullable boolean
必填
Whether DKIM passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.
dmarc_pass
nullable boolean
必填
Whether DMARC passed for the sender of a received message. Null for sent messages and when no verdict is available. This field is kept for the mailbox's retention tier.
purge_at
string
必填
When the message will be permanently deleted: the end of the mailbox's retention tier, pulled nearer (at most 30 days out) while the message is in the trash. Restore a trashed message before then with PATCH {"labels": {"remove": ["trash"]}}.
attachment_count
integer
必填
Number of attachments on the message.
attachment_manifest
array of object
必填
Attachment metadata (filename, content type, size). Stays readable for the mailbox's retention tier even after the attachment bytes themselves have expired.
显示子属性
attachment_manifest.id
string
必填
Attachment ID, used to download the attachment bytes.
attachment_manifest.filename
nullable string
必填
Original filename, or null when the attachment had none.
attachment_manifest.content_type
nullable string
必填
MIME content type, or null when it could not be determined.
attachment_manifest.size
integer
必填
Attachment size in bytes.
reference_ids
array of string
必填
RFC 5322 References header entries used to thread the conversation.
contact_id
nullable string
必填
Contact linked to this message, or null when none is linked.
source
object
必填
Link to the message's entry in the received-message or sent-message log, which has delivery analytics such as per-recipient events. Log entries expire 30 days after the message occurred.
显示子属性
source.resource
string
必填
API path of the log entry for this message.
source.available_until
string
必填
When the log entry (and the message's original rendered source) expires.
occurred_at
string
必填
When the message was received or accepted for sending.