email-threads

Create a message from a mailbox

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; scheduled sends are unavailable. A suspended mailbox cannot send and returns 403.

post/v1/email/mailboxes/{mailbox_id}/messages

Request

  • Base URL: https://us1.platform.bird.com
  • URL: https://us1.platform.bird.com/v1/email/mailboxes/{mailbox_id}/messages
  • Auth: one of:
    • HTTP bearer
    • API key in cookie bird_session

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Request body

subjectstring required

Message subject line.

htmlstring

HTML body. At least one of html or text must be provided.

textstring

Plain-text body. At least one of html or text must be provided.

metadataobject

Arbitrary JSON object stored on the send and echoed in webhook payloads. Cap: 2 KB serialized.

category'marketing' | 'transactional'

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.

Example request

{
  "to": [
    "delivered@messagebird.dev"
  ],
  "subject": "Your quote",
  "text": "Hi, here is the quote you asked for."
}

Response

Message accepted for asynchronous delivery and recorded as the first message of a new conversation.

idstring required

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'inbound' | 'outbound' required

Which way the message went. inbound means you received it, outbound means you sent it.

channelstring required

Channel this message lives on. Always email.

thread_idstring required
fromstring email required

Sender address.

tostring[] required

Recipient addresses on the To line.

ccstring[] required

Recipient addresses on the Cc line. Empty when the message had none.

delivered_tostring email nullable required

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.

subjectstring nullable required

Message subject. Null when the message had no subject.

previewstring nullable required

Short plain-text preview of the message body.

extracted_textstring nullable

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.

labelsstring[] required

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.

statusstring nullable required

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

authentication'pass' | 'fail' | 'unknown' | 'null' nullable required

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.

spf_passboolean nullable required

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_passboolean nullable required

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_passboolean nullable required

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_atstring date-time required

Scheduled permanent-deletion time. 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_countinteger required

Number of attachments on the message.

reference_idsstring[] required

RFC 5322 References header entries used to thread the conversation.

contact_idstring required
occurred_atstring date-time required

When the message was received or accepted for sending.

Example response

{
  "id": "rem_01krdgeqcxet5s7t44vh8rt9mg",
  "channel": "email",
  "thread_id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
  "subject": "Re: Your order",
  "labels": [
    "inbox",
    "unread"
  ],
  "attachment_manifest": [
    {
      "id": "rea_01krdgeqcxet5s7t44vh8rt9mg",
      "filename": "invoice.pdf",
      "content_type": "application/pdf"
    }
  ],
  "contact_id": "con_01krdgeqcxet5s7t44vh8rt9mg",
  "source": {
    "resource": "/v1/email/inbound-messages/rem_01krdgeqcxet5s7t44vh8rt9mg"
  }
}

Changes

No recorded changes to this operation across all 2 revisions of this API.