Messages · MachineMail Docs

[01/28]List Messages

Method	Path	Summary
`GET`	`/v0/inboxes/{inbox_id}/messages`	List Messages
`POST`	`/v0/inboxes/{inbox_id}/messages/batch-get`	Batch Get Messages
`POST`	`/v0/inboxes/{inbox_id}/messages/batch-update`	Batch Update Messages
`GET`	`/v0/inboxes/{inbox_id}/messages/search`	Search Messages
`POST`	`/v0/inboxes/{inbox_id}/messages/send`	Send Message
`GET`	`/v0/inboxes/{inbox_id}/messages/{message_id}`	Get Message
`PATCH`	`/v0/inboxes/{inbox_id}/messages/{message_id}`	Update Message
`DELETE`	`/v0/inboxes/{inbox_id}/messages/{message_id}`	Delete Message
`GET`	`/v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`	Get Attachment
`GET`	`/v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download`	Download Attachment
`POST`	`/v0/inboxes/{inbox_id}/messages/{message_id}/forward`	Forward Message
`GET`	`/v0/inboxes/{inbox_id}/messages/{message_id}/raw`	Get Raw Message
`POST`	`/v0/inboxes/{inbox_id}/messages/{message_id}/reply`	Reply To Message
`POST`	`/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all`	Reply All Message
`GET`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages`	List Messages in Pod
`POST`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-get`	Batch Get Messages in Pod
`POST`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-update`	Batch Update Messages in Pod
`GET`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/search`	Search Messages in Pod
`POST`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/send`	Send Message in Pod
`GET`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}`	Get Message in Pod
`PATCH`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}`	Update Message in Pod
`DELETE`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}`	Delete Message in Pod
`GET`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}`	Get Attachment in Pod
`GET`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download`	Download Attachment in Pod
`POST`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/forward`	Forward Message in Pod
`GET`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/raw`	Get Raw Message in Pod
`POST`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply`	Reply To Message in Pod
`POST`	`/v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply-all`	Reply All Message in Pod

List Messages

http

GET /v0/inboxes/{inbox_id}/messages

Messages in the inbox, newest first.

Spam, blocked, trash, quarantined and unauthenticated messages are hidden unless you pass the matching include_* flag or ask for the label in labels. Spam, blocked, trash and unauthenticated also need the matching label_*_read permission; without it the flag is ignored.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Query parameters

FieldDescription

limit``integer

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

page_token``string

next_page_token from the previous page.

ascending``boolean

Sort oldest first.

labels``string[]

Only items with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them.

before``string (date-time)

Only items with a timestamp before this time.

after``string (date-time)

Only items with a timestamp after this time.

include_spam``boolean

Include spam (needs label_spam_read; ignored without it).

include_blocked``boolean

Include blocked mail (needs label_blocked_read; ignored without it).

include_unauthenticated``boolean

Include unauthenticated mail (needs label_unauthenticated_read; ignored without it).

include_trash``boolean

Include trash (needs label_trash_read; ignored without it).

include_quarantine``boolean

Include quarantined messages (trust level quarantined).

q``string

Full-text filter: the words must appear in the subject, sender, recipients, body or attachment file names. Combines with the other filters.

Response

200 A page of messages (application/json)

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

messages MessageItem[] Required

Ordered by timestamp, newest first unless ascending is set.

Each item of messages is a MessageItem:

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

SPF, DKIM and DMARC verdicts for a received message, each with the domain it is about, as recorded when the message reached MachineMail: by the receiving mail provider (for example Amazon SES), or by the Authentication-Results header of the server that delivered it to MachineMail. A mechanism that was not evaluated is absent. The whole field is absent on sent messages, on messages injected through POST /inbound/raw (their headers are not believed), when nothing was evaluated, and on messages received before the field was introduced. As in AgentMail, only verdicts that speak for the sender are kept. spf is present only when spf_domain is aligned with the sender (shares an organizational domain with the From domain, or with the Sender domain when From spans several domains): an unaligned SPF result is withheld whatever its value. dkim and dmarc are withheld when From spans more than one domain or could not be parsed. Unlike the trust report (trust.authentication), which collapses each result to the values MachineMail scores on and adds aligned, these are the uncollapsed results: permerror and temperror stay as they are. dkim_domain is the signing domain as written: compare it with the From domain before treating a DKIM pass as proof of the sender, and use trust.level (or the UNAUTHENTICATED label) to decide whether to act on the message. Do not reject mail on dmarc: fail alone: forwarding breaks it.

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

Errors

Status	Meaning
`400`	Invalid request: error.type is validation and error.param names the field.
`401`	Missing, invalid, expired or revoked credential.
`403`	The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
`404`	Not found. Also returned for resources outside the credential scope.
`500`	Unexpected server error.

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

{
  "count": 1,
  "limit": 50,
  "next_page_token": "eyJvIjo1MH0",
  "messages": [\
    {\
      "inbox_id": "agent@machinemail.dev",\
      "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",\
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "labels": ["UNREAD"],\
      "timestamp": "2026-10-01T12:00:00.000Z",\
      "from": "Support Agent <agent@machinemail.dev>",\
      "to": ["customer@example.com"],\
      "cc": ["team@example.com"],\
      "bcc": ["audit@example.com"],\
      "subject": "Order #1042",\
      "preview": "Thanks for the quick reply.",\
      "attachments": [\
        {\
          "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
          "filename": "invoice.pdf",\
          "size": 2048,\
          "content_type": "application/pdf",\
          "content_disposition": "string",\
          "content_id": "string"\
        }\
      ],\
      "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "references": ["string"],\
      "headers": {\
        "key": "value"\
      },\
      "authentication_results": {\
        "spf": "pass",\
        "dkim": "pass",\
        "dmarc": "pass",\
        "spf_domain": "string",\
        "dkim_domain": "string",\
        "dmarc_domain": "string",\
        "arc_sealer": "string"\
      },\
      "size": 2048,\
      "updated_at": "2026-10-01T12:00:00.000Z",\
      "created_at": "2026-10-01T12:00:00.000Z",\
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",\
      "direction": "inbound",\
      "delivery_status": "sent",\
      "trust_level": "verified"\
    }\
  ]
}

Batch Get Messages

http

POST /v0/inboxes/{inbox_id}/messages/batch-get

Up to 100 messages by ID in one request, as full Message objects. Duplicate IDs are read once; IDs past the first 100 distinct ones are dropped. Missing IDs and IDs from other inboxes are omitted: compare count with limit (the number of IDs you sent).

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Request body

Content type: application/json.

FieldDescription

message_ids``string[]Required

IDs of the messages to fetch. Only the first 100 distinct IDs are read.

Response

200 The messages found (application/json)

FieldDescription

limit``integerRequired

Number of IDs in the request.

count``integerRequired

Number of messages returned.

messages Message[] Required

Found messages, in request order. IDs not found in the inbox are omitted.

Each item of messages is a Message:

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

reply_to``string[]

Reply-to addresses. In format username@domain.com or Display Name username@domain.com.

text``string

Plain text body. Untrusted: agents should read trust.content.text or extracted_text.

html``string

HTML body. Untrusted.

extracted_text``string

New text content, without quoted replies.

extracted_html``string

New HTML content, without quoted replies.

received_via``"raw"

raw when the message was injected with POST /inbound/raw (authentication not verified).

held_at``string (date-time)

When the message arrived, for inbound mail that was held because the organization reached a Free plan limit. created_at is then when it was delivered (released).

trust TrustReport

Trust report of an inbound message.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/batch-get" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_ids": [\
    "msg_01k6x3a1g00000d0m6pt2y5f7h"\
  ]
}'

Response 200

{
  "limit": 50,
  "count": 1,
  "messages": [\
    {\
      "inbox_id": "agent@machinemail.dev",\
      "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",\
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "labels": ["UNREAD"],\
      "timestamp": "2026-10-01T12:00:00.000Z",\
      "from": "Support Agent <agent@machinemail.dev>",\
      "to": ["customer@example.com"],\
      "cc": ["team@example.com"],\
      "bcc": ["audit@example.com"],\
      "subject": "Order #1042",\
      "preview": "Thanks for the quick reply.",\
      "attachments": [\
        {\
          "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
          "filename": "invoice.pdf",\
          "size": 2048,\
          "content_type": "application/pdf",\
          "content_disposition": "string",\
          "content_id": "string"\
        }\
      ],\
      "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "references": ["string"],\
      "headers": {\
        "key": "value"\
      },\
      "authentication_results": {\
        "spf": "pass",\
        "dkim": "pass",\
        "dmarc": "pass",\
        "spf_domain": "string",\
        "dkim_domain": "string",\
        "dmarc_domain": "string",\
        "arc_sealer": "string"\
      },\
      "size": 2048,\
      "updated_at": "2026-10-01T12:00:00.000Z",\
      "created_at": "2026-10-01T12:00:00.000Z",\
      "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",\
      "direction": "inbound",\
      "delivery_status": "sent",\
      "trust_level": "verified",\
      "reply_to": ["agent@machinemail.dev"],\
      "text": "Thanks for the quick reply.",\
      "html": "<p>Thanks for the quick reply.</p>",\
      "extracted_text": "Thanks for the quick reply.",\
      "extracted_html": "<p>Thanks for the quick reply.</p>",\
      "received_via": "raw",\
      "held_at": "2026-10-01T12:00:00.000Z",\
      "trust": {\
        "level": "verified",\
        "score": 0.8,\
        "basis": "trusted_domain",\
        "authentication": {\
          "spf": "pass",\
          "dkim": "pass",\
          "dmarc": "pass",\
          "aligned": false\
        },\
        "sender": {\
          "address": "agent@machinemail.dev",\
          "domain": "example.com",\
          "prior_correspondence": false,\
          "on_allow_list": false,\
          "on_block_list": false,\
          "free_mail_provider": false,\
          "trusted_domain": {\
            "id": "string",\
            "domain": "example.com",\
            "scope": "org"\
          },\
          "trusted_domain_shadowed_by": "block"\
        },\
        "content": {\
          "text": "Thanks for the quick reply.",\
          "html": "<p>Thanks for the quick reply.</p>",\
          "segments": [{}],\
          "hidden_text_found": false,\
          "zero_width_found": false,\
          "tracking_pixels": 1,\
          "agent_instructions_detected": false,\
          "warnings": ["string"]\
        },\
        "links": [\
          {\
            "href": "string",\
            "text": "Thanks for the quick reply.",\
            "final_url": "https://example.com",\
            "domain": "example.com",\
            "display_mismatch": false,\
            "shortener": false,\
            "suspicious": false,\
            "reasons": []\
          }\
        ],\
        "attachments": [\
          {\
            "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
            "filename": "invoice.pdf",\
            "content_type": "application/pdf",\
            "risk": "low",\
            "reasons": [],\
            "extracted_text": "Thanks for the quick reply."\
          }\
        ],\
        "classification": {\
          "is_spam": 0.8,\
          "is_phishing": 0.8,\
          "contains_instructions_to_agent": 0.8,\
          "requests_credentials_or_payment": 0.8,\
          "urgency": 0.8,\
          "category": "transactional",\
          "language": "string",\
          "backend": "string",\
          "input_hash": "string",\
          "cached": false\
        },\
        "provider_verdicts": {\
          "spam": "pass",\
          "virus": "pass",\
          "source": "string"\
        },\
        "reasons": ["string"],\
        "computed_at": "2026-10-01T12:00:00.000Z"\
      }\
    }\
  ]
}

Batch Update Messages

http

POST /v0/inboxes/{inbox_id}/messages/batch-update

Apply one label change to up to 100 messages: the same add_labels and remove_labels apply to every message. Messages are updated one at a time, not atomically. Missing IDs are skipped: compare count with limit.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_update.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Request body

Content type: application/json.

FieldDescription

message_ids``string[]Required

IDs of the messages to update. Only the first 100 distinct IDs are updated.

add_labels``string | string[]

Label or labels to add to every message.

remove_labels``string | string[]

Label or labels to remove from every message.

Response

200 The updated messages (application/json)

FieldDescription

limit``integerRequired

Number of IDs in the request.

count``integerRequired

Number of messages updated.

updates UpdateMessageResponse[] Required

Updated messages with their new labels, in request order. IDs not found are omitted.

Each item of updates is a UpdateMessageResponse:

FieldDescription

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message after the update.

Errors

Status	Meaning
`400`	Invalid request: error.type is validation and error.param names the field.
`401`	Missing, invalid, expired or revoked credential.
`402`	Free plan: removing SPAM or QUARANTINE makes the message count toward the messages cap and storage from now on, and the organization is over one (limit_key messages_per_month, messages_per_day or storage_bytes). The labels are unchanged. Paid plans are never refused.
`403`	The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
`404`	Not found. Also returned for resources outside the credential scope.
`409`	Conflicts with an existing resource.
`500`	Unexpected server error.

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/batch-update" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_ids": [\
    "msg_01k6x3a1g00000d0m6pt2y5f7h"\
  ],
  "add_labels": "string"
}'

Response 200

{
  "limit": 50,
  "count": 1,
  "updates": [\
    {\
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "labels": ["UNREAD"]\
    }\
  ]
}

Search Messages

http

GET /v0/inboxes/{inbox_id}/messages/search

Full-text search across messages in the inbox, newest first (not ranked by relevance). Every word of q must appear in the subject, sender, recipients (to and cc), body text or attachment file names. Spam, trash, blocked, quarantined and unauthenticated messages are always excluded.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Query parameters

FieldDescription

q``stringRequired

Words to find in the subject, sender, recipients (to and cc), body text or attachment file names. (min length 1)

limit``integer

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

page_token``string

next_page_token from the previous page.

before``string (date-time)

Only messages before this time.

after``string (date-time)

Only messages after this time.

ascending``boolean

Sort oldest first.

Response

200 A page of matching messages (application/json)

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

messages MessageItem[] Required

Matching messages, newest first unless ascending is set.

Each item of messages is a MessageItem:

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/search?q=invoice" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

Send Message

http

POST /v0/inboxes/{inbox_id}/messages/send

At least one of to, cc or bcc is required.

A message can have at most 50 recipients: to, cc and bcc together, each address counted once. An unclaimed sandbox inbox can have at most 5. More is a 400``validation error with param: "to".

Recipients that are suppressed or on a send block list, and paused inboxes, return 403. An unclaimed sandbox inbox sending to a disposable email address returns 403 with code: "disposable_email_not_allowed" and param set to the field holding it (to, cc or bcc). 502 upstream_error when the email provider refuses or fails the send: nothing is sent or stored, and error.message says whether retrying can help.

Attachments given by url are fetched by the API (public http(s) only, no redirects, at most 10 MB, 20 second timeout).

An unclaimed sandbox agent can send at most 10 messages to at most 10 different recipients per rolling 24 hours: 429 with Retry-After past that. Writing again to an address already counted is free. Claiming the inbox lifts the caps.

When MachineMail pauses sending (for the platform, a plan, or this organization because of its bounce or complaint rate), the send returns 403 account_suspended and nothing is sent; an organization limited to replies can still reply in its existing threads. Organizations on the Free plan may be limited to sending to people who emailed them first (403) and to a number of different recipients per rolling 24 hours (429). Messages that look like phishing are held and not sent (403).

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_send.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Request body

Content type: application/json.

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

to``string | string[]

Recipient address or addresses.

cc``string | string[]

CC recipient address or addresses.

bcc``string | string[]

BCC recipient address or addresses.

subject``string

Subject of the message.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

Each item of attachments is a SendAttachment:

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

Response

201 Sent (application/json)

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

Errors

Status	Meaning
`400`	Invalid request: error.type is validation and error.param names the field.
`401`	Missing, invalid, expired or revoked credential.
`402`	Free plan over its messages cap: 3,000 a month or 100 a day, inbound messages and outbound recipients together (each recipient counts once). error.limit_key is messages_per_month or messages_per_day; resets_at and Retry-After say when the allowance resets (absent when this message has more recipients than the cap itself). Paid plans are never refused.
`403`	The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
`404`	Not found. Also returned for resources outside the credential scope.
`409`	Conflicts with an existing resource.
`429`	Unclaimed sandbox agent over a send cap: at most 10 messages to at most 10 different recipients per rolling 24 hours. Retry-After says when the next send fits. Claiming the inbox lifts the caps. Also returned when a Free organization goes over its daily number of different recipients.
`500`	Unexpected server error.
`501`	Not implemented.
`502`	The email provider refused or failed the send (error.type is upstream_error). Nothing was sent and no message was stored. error.message says why: a rejected message or recipient is final, and so is a used-up sending quota until it resets; a throttled or unavailable provider can be retried later. A scheduled draft whose send fails this way is marked send_status: failed, unless the provider could not take mail for now (throttled, sending paused, quota used up, or unavailable): it stays scheduled and is retried.

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/send" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'

Response 201

{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

Get Message

http

GET /v0/inboxes/{inbox_id}/messages/{message_id}

Message content is untrusted: when feeding an LLM, read trust.content.text rather than text or html.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Response

200 The message (application/json)

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

reply_to``string[]

Reply-to addresses. In format username@domain.com or Display Name username@domain.com.

text``string

Plain text body. Untrusted: agents should read trust.content.text or extracted_text.

html``string

HTML body. Untrusted.

extracted_text``string

New text content, without quoted replies.

extracted_html``string

New HTML content, without quoted replies.

received_via``"raw"

raw when the message was injected with POST /inbound/raw (authentication not verified).

held_at``string (date-time)

trust TrustReport

Trust report of an inbound message.

Each item of attachments is a Attachment:

FieldDescription

attachment_id``stringRequired

ID of the attachment.

filename``string

Filename of the attachment.

size``integerRequired

Size of the attachment in bytes.

content_type``string

Content type of the attachment.

content_disposition``string

Content disposition of the attachment (inline or attachment).

content_id``string

Content ID of the attachment.

authentication_results is a MessageAuthenticationResults:

FieldDescription

Result of one authentication mechanism, in the vocabulary of the Authentication-Results header (RFC 8601). none: there was nothing to evaluate (no SPF record for the envelope sender domain, no DKIM signature, or no DMARC record for the From domain). temperror: the check could not complete, for example a DNS timeout.

spf_domain``string

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

dkim_domain``string

Signing domain (d=) of the signature the dkim verdict is about: for pass, a signature that passed, preferring one aligned with the From domain. Present only when dkim is pass or fail. It is the domain as signed: compare it with the From domain before relying on it.

dmarc_domain``string

From domain the dmarc verdict is about (header.from).

arc_sealer``string

Domain of the forwarder whose ARC seal the verdicts were read from (for example google.com): they then describe the message as that forwarder received it. Present only on forwarded mail, and only beside at least one verdict. MachineMail does not validate ARC chains, so it reads verdicts from ARC only when its trust layer is set to believe any results header; by default it believes only its own receiving server and does not send this key.

trust is a TrustReport:

FieldDescription

level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"Required

Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.

score``numberRequired

0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)

basis``"trusted_domain"

trusted_domain: the sender is a trusted domain of the organization, pod or inbox (sender.trusted_domain) and the message carries that domain's own DKIM signature. It is verified, or known when it contains instructions to an AI agent, a phishing signal or malware (content.warnings), and never suspicious or quarantined. Agents get its text and attachments, except attachments the virus scan flags. Absent otherwise.

authentication``objectRequired

sender``objectRequired

content``objectRequired

links``object[]Required

attachments``object[]Required

classification``objectRequired

provider_verdicts``object

Spam and virus scans by the receiving mail provider. Only on messages it scanned.

reasons``string[]Required

Human-readable reasons for the verdict.

computed_at``string (date-time)Required

When the report was computed.

Errors

Status	Meaning
`401`	Missing, invalid, expired or revoked credential.
`403`	The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
`404`	Not found. Also returned for resources outside the credential scope.
`500`	Unexpected server error.

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

{
  "inbox_id": "agent@machinemail.dev",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "labels": ["UNREAD"],
  "timestamp": "2026-10-01T12:00:00.000Z",
  "from": "Support Agent <agent@machinemail.dev>",
  "to": ["customer@example.com"],
  "cc": ["team@example.com"],
  "bcc": ["audit@example.com"],
  "subject": "Order #1042",
  "preview": "Thanks for the quick reply.",
  "attachments": [\
    {\
      "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
      "filename": "invoice.pdf",\
      "size": 2048,\
      "content_type": "application/pdf",\
      "content_disposition": "string",\
      "content_id": "string"\
    }\
  ],
  "in_reply_to": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "references": ["string"],
  "headers": {
    "key": "value"
  },
  "authentication_results": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass",
    "spf_domain": "string",
    "dkim_domain": "string",
    "dmarc_domain": "string",
    "arc_sealer": "string"
  },
  "size": 2048,
  "updated_at": "2026-10-01T12:00:00.000Z",
  "created_at": "2026-10-01T12:00:00.000Z",
  "pod_id": "pod_01k6x2m9qd0001b8j4mr0w3d5f",
  "direction": "inbound",
  "delivery_status": "sent",
  "trust_level": "verified",
  "reply_to": ["agent@machinemail.dev"],
  "text": "Thanks for the quick reply.",
  "html": "<p>Thanks for the quick reply.</p>",
  "extracted_text": "Thanks for the quick reply.",
  "extracted_html": "<p>Thanks for the quick reply.</p>",
  "received_via": "raw",
  "held_at": "2026-10-01T12:00:00.000Z",
  "trust": {
    "level": "verified",
    "score": 0.8,
    "basis": "trusted_domain",
    "authentication": {
      "spf": "pass",
      "dkim": "pass",
      "dmarc": "pass",
      "aligned": false
    },
    "sender": {
      "address": "agent@machinemail.dev",
      "domain": "example.com",
      "prior_correspondence": false,
      "on_allow_list": false,
      "on_block_list": false,
      "free_mail_provider": false,
      "trusted_domain": {
        "id": "string",
        "domain": "example.com",
        "scope": "org"
      },
      "trusted_domain_shadowed_by": "block"
    },
    "content": {
      "text": "Thanks for the quick reply.",
      "html": "<p>Thanks for the quick reply.</p>",
      "segments": [\
        {\
          "kind": "body",\
          "text": "Thanks for the quick reply."\
        }\
      ],
      "hidden_text_found": false,
      "zero_width_found": false,
      "tracking_pixels": 1,
      "agent_instructions_detected": false,
      "warnings": ["string"]
    },
    "links": [\
      {\
        "href": "string",\
        "text": "Thanks for the quick reply.",\
        "final_url": "https://example.com",\
        "domain": "example.com",\
        "display_mismatch": false,\
        "shortener": false,\
        "suspicious": false,\
        "reasons": ["string"]\
      }\
    ],
    "attachments": [\
      {\
        "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",\
        "filename": "invoice.pdf",\
        "content_type": "application/pdf",\
        "risk": "low",\
        "reasons": ["string"],\
        "extracted_text": "Thanks for the quick reply."\
      }\
    ],
    "classification": {
      "is_spam": 0.8,
      "is_phishing": 0.8,
      "contains_instructions_to_agent": 0.8,
      "requests_credentials_or_payment": 0.8,
      "urgency": 0.8,
      "category": "transactional",
      "language": "string",
      "backend": "string",
      "input_hash": "string",
      "cached": false
    },
    "provider_verdicts": {
      "spam": "pass",
      "virus": "pass",
      "source": "string"
    },
    "reasons": ["string"],
    "computed_at": "2026-10-01T12:00:00.000Z"
  }
}

Update Message

http

PATCH /v0/inboxes/{inbox_id}/messages/{message_id}

Adds and removes labels. Returns the whole updated message.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_update.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Request body

Content type: application/json.

FieldDescription

add_labels``string | string[]

Label or labels to add.

remove_labels``string | string[]

Label or labels to remove.

Response

200 The updated message (application/json)

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

reply_to``string[]

Reply-to addresses. In format username@domain.com or Display Name username@domain.com.

text``string

Plain text body. Untrusted: agents should read trust.content.text or extracted_text.

html``string

HTML body. Untrusted.

extracted_text``string

New text content, without quoted replies.

extracted_html``string

New HTML content, without quoted replies.

received_via``"raw"

raw when the message was injected with POST /inbound/raw (authentication not verified).

held_at``string (date-time)

trust TrustReport

Trust report of an inbound message.

Each item of attachments is a Attachment:

FieldDescription

attachment_id``stringRequired

ID of the attachment.

filename``string

Filename of the attachment.

size``integerRequired

Size of the attachment in bytes.

content_type``string

Content type of the attachment.

content_disposition``string

Content disposition of the attachment (inline or attachment).

content_id``string

Content ID of the attachment.

authentication_results is a MessageAuthenticationResults:

FieldDescription

spf_domain``string

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

dkim_domain``string

dmarc_domain``string

From domain the dmarc verdict is about (header.from).

arc_sealer``string

trust is a TrustReport:

FieldDescription

level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"Required

Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.

score``numberRequired

0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)

basis``"trusted_domain"

authentication``objectRequired

sender``objectRequired

content``objectRequired

links``object[]Required

attachments``object[]Required

classification``objectRequired

provider_verdicts``object

Spam and virus scans by the receiving mail provider. Only on messages it scanned.

reasons``string[]Required

Human-readable reasons for the verdict.

computed_at``string (date-time)Required

When the report was computed.

Errors

Error bodies use the error envelope.

Example

Request

curl -X PATCH "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add_labels": "string"
}'

Response 200

Delete Message

http

DELETE /v0/inboxes/{inbox_id}/messages/{message_id}

Permanently deletes the message, its raw copy and attachments. The thread is updated (or deleted with its last message).

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_delete.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Response

200 Deleted (application/json)

FieldDescription

ok``trueRequired

Errors

Status	Meaning
`401`	Missing, invalid, expired or revoked credential.
`403`	The credential lacks the permission or scope for this request (error.type forbidden), or MachineMail suspended the organization or its sending (account_suspended: error.message says what still works; do not retry or re-register).
`404`	Not found. Also returned for resources outside the credential scope.
`409`	Conflicts with an existing resource.
`500`	Unexpected server error.

Error bodies use the error envelope.

Example

Request

curl -X DELETE "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

{
  "ok": true
}

Get Attachment

http

GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

attachment_id``stringRequired

ID of the attachment.

Response

200 The attachment with a download URL (application/json)

FieldDescription

attachment_id``stringRequired

ID of the attachment.

filename``string

Filename of the attachment.

size``integerRequired

Size of the attachment in bytes.

content_type``string

Content type of the attachment.

content_disposition``string

Content disposition of the attachment (inline or attachment).

content_id``string

Content ID of the attachment.

download_url``stringRequired

URL of the attachment bytes. Depending on the storage backend: a signed storage URL, the API URL GET .../attachments/{attachment_id}/download (send your API key), or a data: URI.

expires_at``string (date-time)Required

When download_url expires: one hour from the request unless the signed URL sets its own expiry.

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

{
  "attachment_id": "att_01k6x3h7qv0000m7v3xb9f2p4r",
  "filename": "invoice.pdf",
  "size": 2048,
  "content_type": "application/pdf",
  "content_disposition": "string",
  "content_id": "string",
  "download_url": "https://example.com",
  "expires_at": "2026-10-01T12:00:00.000Z"
}

Download Attachment

http

GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download

The attachment bytes, with X-Content-Type-Options: nosniff. By default Content-Disposition: attachment (RFC 6266: an ASCII filename plus the exact name in RFC 5987 filename* when it is not plain ASCII). With disposition=inline, raster images, PDF and plain text are served inline for previews, under a locked-down Content-Security-Policy; every other type (HTML, SVG, XML, scripts, archives…) is still served as a download.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

attachment_id``stringRequired

ID of the attachment.

Query parameters

FieldDescription

disposition``"attachment" | "inline"

inline previews raster images, PDF and plain text in the browser; every other type downloads regardless.

Default"attachment"

Response

200 The attachment bytes (application/octet-stream)

Headers:

FieldDescription

Content-Disposition``string

attachment; filename=""; filename*=UTF-8'' (or inline; … for a preview).

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r/download" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Forward Message

http

POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward

Sends the message to new recipients. The text body is your text followed by a “Forwarded message” header block and the original text. The original HTML and attachments are not included. subject defaults to Fwd: <original subject>. A quarantined message (trust level quarantined or the QUARANTINE label) is not forwarded: 409 conflict with param: "message_id"; a person can review it in the dashboard.

Attachments given by url are fetched by the API (public http(s) only, no redirects, at most 10 MB, 20 second timeout).

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_send.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Request body

Content type: application/json.

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

to``string | string[]

Recipient address or addresses.

cc``string | string[]

CC recipient address or addresses.

bcc``string | string[]

BCC recipient address or addresses.

subject``string

Subject of the message.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

Each item of attachments is a SendAttachment:

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

Response

201 Sent (application/json)

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/forward" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'

Response 201

{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

Get Raw Message

http

GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw

The original RFC 5322 message bytes, as received or sent. AgentMail returns a JSON object with a download URL instead.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Response

200 The raw message (message/rfc822)

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/raw" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Reply To Message

http

POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply

Sends a reply in the thread of the message, with In-Reply-To and References set.

Attachments given by url are fetched by the API (public http(s) only, no redirects, at most 10 MB, 20 second timeout).

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_reply or message_send.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Request body

Content type: application/json.

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

to``string | string[]

Recipient address or addresses. Defaults to the sender of the original (its reply-to addresses if any); for an outbound original, its recipients.

cc``string | string[]

CC recipient address or addresses.

bcc``string | string[]

BCC recipient address or addresses.

reply_all``boolean

true replies to all recipients of the original, as Reply All Message does; to and cc are then added to them.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

subject``string

Subject of the reply. Defaults to the original subject with Re: in front.

Each item of attachments is a SendAttachment:

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

Response

201 Sent (application/json)

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/reply" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "text": "Thanks for the quick reply.",
  "subject": "Order #1042"
}'

Response 201

{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

Reply All Message

http

POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all

Replies to the sender and every to and cc recipient of the message, except this inbox. to and cc add more recipients.

Attachments given by url are fetched by the API (public http(s) only, no redirects, at most 10 MB, 20 second timeout).

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_reply or message_send.

Path parameters

FieldDescription

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Request body

Content type: application/json.

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

to``string | string[]

More recipients, added to the sender and recipients of the original.

cc``string | string[]

More CC recipients, added to the CC recipients of the original.

bcc``string | string[]

BCC recipient address or addresses.

subject``string

Subject of the reply. Defaults to the original subject with Re: in front.

Each item of attachments is a SendAttachment:

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

Response

201 Sent (application/json)

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/reply-all" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Thanks for the quick reply.",
  "to": "customer@example.com",
  "subject": "Order #1042"
}'

Response 201

{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

List Messages in Pod

http

GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages

Same as List Messages (GET /v0/inboxes/{inbox_id}/messages), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Query parameters

FieldDescription

limit``integer

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

page_token``string

next_page_token from the previous page.

ascending``boolean

Sort oldest first.

labels``string[]

Only items with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them.

before``string (date-time)

Only items with a timestamp before this time.

after``string (date-time)

Only items with a timestamp after this time.

include_spam``boolean

Include spam (needs label_spam_read; ignored without it).

include_blocked``boolean

Include blocked mail (needs label_blocked_read; ignored without it).

include_unauthenticated``boolean

Include unauthenticated mail (needs label_unauthenticated_read; ignored without it).

include_trash``boolean

Include trash (needs label_trash_read; ignored without it).

include_quarantine``boolean

Include quarantined messages (trust level quarantined).

q``string

Full-text filter: the words must appear in the subject, sender, recipients, body or attachment file names. Combines with the other filters.

Response

200 A page of messages (application/json)

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

messages MessageItem[] Required

Ordered by timestamp, newest first unless ascending is set.

Each item of messages is a MessageItem:

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

Batch Get Messages in Pod

http

POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-get

Same as Batch Get Messages (POST /v0/inboxes/{inbox_id}/messages/batch-get), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Request body

Content type: application/json.

FieldDescription

message_ids``string[]Required

IDs of the messages to fetch. Only the first 100 distinct IDs are read.

Response

200 The messages found (application/json)

FieldDescription

limit``integerRequired

Number of IDs in the request.

count``integerRequired

Number of messages returned.

messages Message[] Required

Found messages, in request order. IDs not found in the inbox are omitted.

Each item of messages is a Message:

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

reply_to``string[]

Reply-to addresses. In format username@domain.com or Display Name username@domain.com.

text``string

Plain text body. Untrusted: agents should read trust.content.text or extracted_text.

html``string

HTML body. Untrusted.

extracted_text``string

New text content, without quoted replies.

extracted_html``string

New HTML content, without quoted replies.

received_via``"raw"

raw when the message was injected with POST /inbound/raw (authentication not verified).

held_at``string (date-time)

trust TrustReport

Trust report of an inbound message.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/batch-get" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_ids": [\
    "msg_01k6x3a1g00000d0m6pt2y5f7h"\
  ]
}'

Response 200

Batch Update Messages in Pod

http

POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/batch-update

Same as Batch Update Messages (POST /v0/inboxes/{inbox_id}/messages/batch-update), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_update.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Request body

Content type: application/json.

FieldDescription

message_ids``string[]Required

IDs of the messages to update. Only the first 100 distinct IDs are updated.

add_labels``string | string[]

Label or labels to add to every message.

remove_labels``string | string[]

Label or labels to remove from every message.

Response

200 The updated messages (application/json)

FieldDescription

limit``integerRequired

Number of IDs in the request.

count``integerRequired

Number of messages updated.

updates UpdateMessageResponse[] Required

Updated messages with their new labels, in request order. IDs not found are omitted.

Each item of updates is a UpdateMessageResponse:

FieldDescription

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message after the update.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/batch-update" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message_ids": [\
    "msg_01k6x3a1g00000d0m6pt2y5f7h"\
  ],
  "add_labels": "string"
}'

Response 200

{
  "limit": 50,
  "count": 1,
  "updates": [\
    {\
      "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",\
      "labels": ["UNREAD"]\
    }\
  ]
}

Search Messages in Pod

http

GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/search

Same as Search Messages (GET /v0/inboxes/{inbox_id}/messages/search), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Query parameters

FieldDescription

q``stringRequired

Words to find in the subject, sender, recipients (to and cc), body text or attachment file names. (min length 1)

limit``integer

Maximum number of items to return. Default 50, maximum 500; larger values are capped.

page_token``string

next_page_token from the previous page.

before``string (date-time)

Only messages before this time.

after``string (date-time)

Only messages after this time.

ascending``boolean

Sort oldest first.

Response

200 A page of matching messages (application/json)

FieldDescription

count``integerRequired

Number of items returned.

limit``integer

Maximum number of items per page. Default 50, maximum 500; larger values are capped.

next_page_token``string

Page token for pagination. Absent on the last page.

messages MessageItem[] Required

Matching messages, newest first unless ascending is set.

Each item of messages is a MessageItem:

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/search?q=invoice" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

Send Message in Pod

http

POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/send

Same as Send Message (POST /v0/inboxes/{inbox_id}/messages/send), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_send.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

Request body

Content type: application/json.

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

to``string | string[]

Recipient address or addresses.

cc``string | string[]

CC recipient address or addresses.

bcc``string | string[]

BCC recipient address or addresses.

subject``string

Subject of the message.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

Each item of attachments is a SendAttachment:

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

Response

201 Sent (application/json)

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/send" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'

Response 201

{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

Get Message in Pod

http

GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}

Same as Get Message (GET /v0/inboxes/{inbox_id}/messages/{message_id}), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Response

200 The message (application/json)

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

reply_to``string[]

Reply-to addresses. In format username@domain.com or Display Name username@domain.com.

text``string

Plain text body. Untrusted: agents should read trust.content.text or extracted_text.

html``string

HTML body. Untrusted.

extracted_text``string

New text content, without quoted replies.

extracted_html``string

New HTML content, without quoted replies.

received_via``"raw"

raw when the message was injected with POST /inbound/raw (authentication not verified).

held_at``string (date-time)

trust TrustReport

Trust report of an inbound message.

Each item of attachments is a Attachment:

FieldDescription

attachment_id``stringRequired

ID of the attachment.

filename``string

Filename of the attachment.

size``integerRequired

Size of the attachment in bytes.

content_type``string

Content type of the attachment.

content_disposition``string

Content disposition of the attachment (inline or attachment).

content_id``string

Content ID of the attachment.

authentication_results is a MessageAuthenticationResults:

FieldDescription

spf_domain``string

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

dkim_domain``string

dmarc_domain``string

From domain the dmarc verdict is about (header.from).

arc_sealer``string

trust is a TrustReport:

FieldDescription

level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"Required

Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.

score``numberRequired

0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)

basis``"trusted_domain"

authentication``objectRequired

sender``objectRequired

content``objectRequired

links``object[]Required

attachments``object[]Required

classification``objectRequired

provider_verdicts``object

Spam and virus scans by the receiving mail provider. Only on messages it scanned.

reasons``string[]Required

Human-readable reasons for the verdict.

computed_at``string (date-time)Required

When the report was computed.

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

Update Message in Pod

http

PATCH /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}

Same as Update Message (PATCH /v0/inboxes/{inbox_id}/messages/{message_id}), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_update.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Request body

Content type: application/json.

FieldDescription

add_labels``string | string[]

Label or labels to add.

remove_labels``string | string[]

Label or labels to remove.

Response

200 The updated message (application/json)

FieldDescription

inbox_id``stringRequired

ID of the inbox.

thread_id``stringRequired

ID of the thread.

message_id``stringRequired

ID of the message.

labels``string[]Required

Labels of the message.

timestamp``string (date-time)Required

Time at which the message was sent or received.

from``stringRequired

Address of the sender. In format username@domain.com or Display Name username@domain.com.

to``string[]Required

Addresses of the recipients. In format username@domain.com or Display Name username@domain.com.

cc``string[]

Addresses of the CC recipients. In format username@domain.com or Display Name username@domain.com.

bcc``string[]

Addresses of the BCC recipients. In format username@domain.com or Display Name username@domain.com.

subject``string

Subject of the message.

preview``string

Text preview of the message.

attachments Attachment[]

Attachments of the message.

in_reply_to``string

ID of the message being replied to.

references``string[]

IDs of previous messages in the thread.

headers``Record<string, string>

Headers of the message.

authentication_results MessageAuthenticationResults

size``integerRequired

Size of the message in bytes.

updated_at``string (date-time)Required

Time at which the message was last updated.

created_at``string (date-time)Required

Time at which the message was created.

pod_id``stringRequired

ID of the pod.

direction``"inbound" | "outbound"Required

Whether the message was received or sent.

delivery_status``"sent" | "delivered" | "bounced" | "complained"

Outbound only: last delivery state reported by the transport.

trust_level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"

Inbound only: trust.level, for list badges.

reply_to``string[]

Reply-to addresses. In format username@domain.com or Display Name username@domain.com.

text``string

Plain text body. Untrusted: agents should read trust.content.text or extracted_text.

html``string

HTML body. Untrusted.

extracted_text``string

New text content, without quoted replies.

extracted_html``string

New HTML content, without quoted replies.

received_via``"raw"

raw when the message was injected with POST /inbound/raw (authentication not verified).

held_at``string (date-time)

trust TrustReport

Trust report of an inbound message.

Each item of attachments is a Attachment:

FieldDescription

attachment_id``stringRequired

ID of the attachment.

filename``string

Filename of the attachment.

size``integerRequired

Size of the attachment in bytes.

content_type``string

Content type of the attachment.

content_disposition``string

Content disposition of the attachment (inline or attachment).

content_id``string

Content ID of the attachment.

authentication_results is a MessageAuthenticationResults:

FieldDescription

spf_domain``string

Envelope sender (MAIL FROM) domain the spf verdict is about (smtp.mailfrom, or the HELO name when the envelope sender was empty).

dkim_domain``string

dmarc_domain``string

From domain the dmarc verdict is about (header.from).

arc_sealer``string

trust is a TrustReport:

FieldDescription

level``"verified" | "known" | "unknown" | "suspicious" | "quarantined"Required

Overall verdict, safest first. quarantined messages are labelled QUARANTINE and hidden from lists unless asked for.

score``numberRequired

0 to 1, higher is safer. Ranks messages within a level. (minimum 0, maximum 1)

basis``"trusted_domain"

authentication``objectRequired

sender``objectRequired

content``objectRequired

links``object[]Required

attachments``object[]Required

classification``objectRequired

provider_verdicts``object

Spam and virus scans by the receiving mail provider. Only on messages it scanned.

reasons``string[]Required

Human-readable reasons for the verdict.

computed_at``string (date-time)Required

When the report was computed.

Errors

Error bodies use the error envelope.

Example

Request

curl -X PATCH "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "add_labels": "string"
}'

Response 200

Delete Message in Pod

http

DELETE /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}

Same as Delete Message (DELETE /v0/inboxes/{inbox_id}/messages/{message_id}), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_delete.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Response

200 Deleted (application/json)

FieldDescription

ok``trueRequired

Errors

Error bodies use the error envelope.

Example

Request

curl -X DELETE "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

{
  "ok": true
}

Get Attachment in Pod

http

GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}

Same as Get Attachment (GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

attachment_id``stringRequired

ID of the attachment.

Response

200 The attachment with a download URL (application/json)

FieldDescription

attachment_id``stringRequired

ID of the attachment.

filename``string

Filename of the attachment.

size``integerRequired

Size of the attachment in bytes.

content_type``string

Content type of the attachment.

content_disposition``string

Content disposition of the attachment (inline or attachment).

content_id``string

Content ID of the attachment.

download_url``stringRequired

expires_at``string (date-time)Required

When download_url expires: one hour from the request unless the signed URL sets its own expiry.

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Response 200

Download Attachment in Pod

http

GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download

Same as Download Attachment (GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}/download), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

attachment_id``stringRequired

ID of the attachment.

Query parameters

FieldDescription

disposition``"attachment" | "inline"

inline previews raster images, PDF and plain text in the browser; every other type downloads regardless.

Default"attachment"

Response

200 The attachment bytes (application/octet-stream)

Headers:

FieldDescription

Content-Disposition``string

attachment; filename=""; filename*=UTF-8'' (or inline; … for a preview).

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/attachments/att_01k6x3h7qv0000m7v3xb9f2p4r/download" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Forward Message in Pod

http

POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/forward

Same as Forward Message (POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_send.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Request body

Content type: application/json.

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

to``string | string[]

Recipient address or addresses.

cc``string | string[]

CC recipient address or addresses.

bcc``string | string[]

BCC recipient address or addresses.

subject``string

Subject of the message.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

Each item of attachments is a SendAttachment:

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

Response

201 Sent (application/json)

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/forward" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "subject": "Order #1042",
  "text": "Thanks for the quick reply."
}'

Response 201

{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

Get Raw Message in Pod

http

GET /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/raw

Same as Get Raw Message (GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_read.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Response

200 The raw message (message/rfc822)

Errors

Error bodies use the error envelope.

Example

Request

curl "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/raw" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Reply To Message in Pod

http

POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply

Same as Reply To Message (POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_reply or message_send.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Request body

Content type: application/json.

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

to``string | string[]

Recipient address or addresses. Defaults to the sender of the original (its reply-to addresses if any); for an outbound original, its recipients.

cc``string | string[]

CC recipient address or addresses.

bcc``string | string[]

BCC recipient address or addresses.

reply_all``boolean

true replies to all recipients of the original, as Reply All Message does; to and cc are then added to them.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

subject``string

Subject of the reply. Defaults to the original subject with Re: in front.

Each item of attachments is a SendAttachment:

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

Response

201 Sent (application/json)

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/reply" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "customer@example.com",
  "text": "Thanks for the quick reply.",
  "subject": "Order #1042"
}'

Response 201

{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

Reply All Message in Pod

http

POST /v0/pods/{pod_id}/inboxes/{inbox_id}/messages/{message_id}/reply-all

Same as Reply All Message (POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all), limited to the pod.

Authentication:Authorization: Bearer <api key> or the dashboard mm_session cookie. Permission: message_reply or message_send.

Path parameters

FieldDescription

pod_id``stringRequired

ID of the pod.

inbox_id``stringRequired

ID of the inbox: its email address, as in AgentMail (inbox_id == email).

message_id``stringRequired

ID of the message.

Request body

Content type: application/json.

FieldDescription

labels``string | string[]

Labels of the message. SENT is always added.

reply_to``string | string[]

Reply-to address or addresses.

text``string

Plain text body.

html``string

HTML body.

attachments SendAttachment[]

Attachments to include.

headers``Record<string, string>

Headers to include. In-Reply-To and References also thread the message.

to``string | string[]

More recipients, added to the sender and recipients of the original.

cc``string | string[]

More CC recipients, added to the CC recipients of the original.

bcc``string | string[]

BCC recipient address or addresses.

subject``string

Subject of the reply. Defaults to the original subject with Re: in front.

Each item of attachments is a SendAttachment:

FieldDescription

filename``string

Filename of the attachment. Defaults to the last segment of url.

content_type``string

Content type of the attachment. Defaults to the Content-Type of the url response.

content_disposition``"inline" | "attachment"

Content disposition of the attachment.

content_id``string

Content ID, for inline images referenced as cid: in the HTML body.

content``string

Base64 encoded content of the attachment.

url``string

URL the API downloads the attachment from: public http(s) only, no redirects, at most 10 MB, 20 second timeout.

Response

201 Sent (application/json)

FieldDescription

message_id``stringRequired

ID of the message.

thread_id``stringRequired

ID of the thread.

timestamp``string (date-time)Required

When the message was sent.

Errors

Error bodies use the error envelope.

Example

Request

curl -X POST "https://api.machinemail.dev/v0/pods/pod_01k6x2m9qd0001b8j4mr0w3d5f/inboxes/agent@machinemail.dev/messages/msg_01k6x3a1g00000d0m6pt2y5f7h/reply-all" \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Thanks for the quick reply.",
  "to": "customer@example.com",
  "subject": "Order #1042"
}'

Response 201

{
  "message_id": "msg_01k6x3a1g00000d0m6pt2y5f7h",
  "thread_id": "thd_01k6x3a1fz0000c9k5ns1x4e6g",
  "timestamp": "2026-10-01T12:00:00.000Z"
}

On this page

List Messages Batch Get Messages Batch Update Messages Search Messages Send Message Get Message Update Message Delete Message Get Attachment Download Attachment Forward Message Get Raw Message Reply To Message Reply All Message List Messages in Pod Batch Get Messages in Pod Batch Update Messages in Pod Search Messages in Pod Send Message in Pod Get Message in Pod Update Message in Pod Delete Message in Pod Get Attachment in Pod Download Attachment in Pod Forward Message in Pod Get Raw Message in Pod Reply To Message in Pod Reply All Message in Pod

100% readTop