Create 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!",
});

msg = client.email.mailboxes.messages.create(
    "mbx_01krdgeqcxet5s7t44vh8rt9mg",
    to=[{"address": "user@example.com"}],
    subject="Hello",
    text="Hi there",
)
print(msg.id, msg.thread_id)

msg, err := client.Email.Mailboxes.Messages.Create(context.Background(), "mbx_123", bird.EmailMailboxesMessagesCreateParams{
	To:      []string{"customer@example.com"},
	Subject: "Following up",
	HTML:    "<p>Hi, just checking in.</p>",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id)

bird email mailboxes compose <mailbox-id> \
  --subject 'Your quote' \
  --text 'Hi, here is the quote you asked for.' \
  --to delivered@messagebird.dev

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": [
      "delivered@messagebird.dev"
    ],
    "subject": "Your quote",
    "text": "Hi, here is the quote you asked for."
  }'

प्रतिक्रिया202

{
  "scheduled_message_id": "msm_01krdgeqcxet5s7t44vh8rt9mg",
  "mailbox_id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
  "id": "rem_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "inbound",
  "channel": "email",
  "thread_id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
  "subject": "Re: Your order",
  "labels": [
    "inbox",
    "unread"
  ],
  "recipients": [
    {
      "status": "delivered"
    }
  ],
  "authentication": "pass",
  "attachment_manifest": [
    {
      "id": "rea_01krdgeqcxet5s7t44vh8rt9mg",
      "filename": "invoice.pdf",
      "content_type": "application/pdf"
    }
  ],
  "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
  "source": {
    "resource": "/v1/email/inbound-messages/rem_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

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. For an immediate send, the message is added to the mailbox and returned as the conversation's first message. Set scheduled_at to send later: the response reserves the message and conversation IDs with status scheduled and links the separate schedule through scheduled_message_id. The message joins the conversation only at dispatch. A suspended mailbox cannot send and returns 403.

पैरामीटर

mailbox_idstring

Mailbox identifier. Starts with mbx_.

Request Payload

scheduled_at

string

Send between 30 seconds and 30 days ahead, sharing the scheduled-email allowance. The scheduled send is listed separately and enters the conversation only at dispatch. Sender, mailbox and send-volume eligibility are rechecked then; refusal fails the schedule record without adding a conversation message. Retention starts at dispatch. Attachments are not supported on scheduled messages; send now or schedule without attachments.

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.

चाइल्ड पैरामीटर दिखाएँ

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.

चाइल्ड पैरामीटर दिखाएँ

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.

चाइल्ड पैरामीटर दिखाएँ

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).

चाइल्ड पैरामीटर दिखाएँ

Email address, optionally in RFC 5322 mailbox form with an embedded display name.

An email address with an optional display name.

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 the mailbox's retention tier.

चाइल्ड पैरामीटर दिखाएँ

tags

array of object

Structured {name, value} labels for filtering and analytics on the sent-message log. Cap: 20 tags per send.

चाइल्ड पैरामीटर दिखाएँ

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

cancel_on_reply

boolean

When scheduled_at is set, cancel if an inbound message arrives in the conversation before dispatch is claimed. Defaults to false: the frozen parent, recipients and content are sent unchanged even if new mail arrives.

Response Payload

scheduled_message_id

string

Separate schedule record, always present when status is scheduled.

scheduled_at

string

Planned send time on a scheduled acknowledgement.

mailbox_id

string

Owning mailbox, always present on scheduled acknowledgements.

notice

string

Informational notice when conversation retention expires before dispatch; the reserved thread is recreated without expired messages.

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 is filed in Spam.
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

आवश्यक

Aggregate delivery status of a sent message:

scheduled: Acknowledgement only; the separate schedule is linked by scheduled_message_id.
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

आवश्यक

DMARC result for the domain in the received message's From header.

pass: SPF or DKIM passed and aligned with that domain.
fail: DMARC was evaluated and did not pass.
unknown: no trustworthy verdict is available.

This follows dmarc_pass and does not verify a particular person. The receiving provider currently supplies no DMARC result, so received messages report unknown.

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 the receiving provider reports that SPF authorized the envelope sender for the sending server. A soft failure is false. Missing, neutral and inconclusive results are null. Sent messages have null results. Kept for the mailbox retention tier.

dkim_pass

nullable boolean

आवश्यक

Whether the receiving provider verified a DKIM signature. A passing signature makes this true even when another signature fails. Missing signatures and inconclusive verification results are null. Sent messages have null results. Kept for the mailbox retention tier.

dmarc_pass

nullable boolean

आवश्यक

Whether SPF or DKIM passed and aligned with the domain in the message's From header. The receiving provider currently supplies no DMARC result, so this is null. Sent messages have null results. Kept for the mailbox retention tier.

purge_at

string

आवश्यक

Scheduled permanent-deletion time. For a scheduled acknowledgement, this is based on the due time and replaced with actual dispatch-based retention once it sends. This is the end of the mailbox's retention tier, moved to no more than 30 days in the future 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). Both the metadata and the attachment bytes stay available for the mailbox's retention tier.

चाइल्ड एट्रिब्यूट दिखाएँ

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.

चाइल्ड एट्रिब्यूट दिखाएँ

occurred_at

string

आवश्यक

When the message was received or accepted for sending. For a scheduled acknowledgement, the time it is due to send, replaced by the actual send time once it sends.

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

इम्प्लीमेंटेशन ब्रीफ़ पाएँ

const msg = await bird.email.mailboxes.messages.create("mbx_01abc", {
  to: ["customer@example.com"],
  subject: "Hello",
  text: "Hi there!",
});

msg = client.email.mailboxes.messages.create(
    "mbx_01krdgeqcxet5s7t44vh8rt9mg",
    to=[{"address": "user@example.com"}],
    subject="Hello",
    text="Hi there",
)
print(msg.id, msg.thread_id)

msg, err := client.Email.Mailboxes.Messages.Create(context.Background(), "mbx_123", bird.EmailMailboxesMessagesCreateParams{
	To:      []string{"customer@example.com"},
	Subject: "Following up",
	HTML:    "<p>Hi, just checking in.</p>",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id)

bird email mailboxes compose <mailbox-id> \
  --subject 'Your quote' \
  --text 'Hi, here is the quote you asked for.' \
  --to delivered@messagebird.dev

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": [
      "delivered@messagebird.dev"
    ],
    "subject": "Your quote",
    "text": "Hi, here is the quote you asked for."
  }'

प्रतिक्रिया202

{
  "scheduled_message_id": "msm_01krdgeqcxet5s7t44vh8rt9mg",
  "mailbox_id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
  "id": "rem_01krdgeqcxet5s7t44vh8rt9mg",
  "direction": "inbound",
  "channel": "email",
  "thread_id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
  "subject": "Re: Your order",
  "labels": [
    "inbox",
    "unread"
  ],
  "recipients": [
    {
      "status": "delivered"
    }
  ],
  "authentication": "pass",
  "attachment_manifest": [
    {
      "id": "rea_01krdgeqcxet5s7t44vh8rt9mg",
      "filename": "invoice.pdf",
      "content_type": "application/pdf"
    }
  ],
  "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
  "source": {
    "resource": "/v1/email/inbound-messages/rem_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

Create a message from a mailbox

पैरामीटर

Request Payload

Response Payload

संबंधित संसाधन