title: "Messages" description: "Send, reply to, forward, list, search, read and update messages in a MachineMail inbox, one at a time or in batches, and download attachments and raw MIME." canonical: "https://machinemail.dev/docs/reference/api/messages"

Messages

Send, reply to, forward, list, search, read and update messages in a MachineMail inbox, one at a time or in batches, and download attachments and raw MIME.

Source: https://machinemail.dev/docs/reference/api/messages

List Messages

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

Query parameters

Response

200 A page of messages (application/json)

Each item of messages is a MessageItem:

Errors

Error bodies use the error envelope.

Example

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

{
  "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

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

Request body

Content type: application/json.

Response

200 The messages found (application/json)

Each item of messages is a Message:

Errors

Error bodies use the error envelope.

Example

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"
  ]
}'

{
  "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

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

Request body

Content type: application/json.

Response

200 The updated messages (application/json)

Each item of updates is a UpdateMessageResponse:

Errors

Error bodies use the error envelope.

Example

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"
}'

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

Search Messages

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

Query parameters

Response

200 A page of matching messages (application/json)

Each item of messages is a MessageItem:

Errors

Error bodies use the error envelope.

Example

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

Send Message

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

Request body

Content type: application/json.

Each item of attachments is a SendAttachment:

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

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."
}'

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

Get Message

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

Response

200 The message (application/json)

Each item of attachments is a Attachment:

authentication_results is a MessageAuthenticationResults:

trust is a TrustReport:

Errors

Error bodies use the error envelope.

Example

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

{
  "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

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

Request body

Content type: application/json.

Response

200 The updated message (application/json)

Each item of attachments is a Attachment:

authentication_results is a MessageAuthenticationResults:

trust is a TrustReport:

Errors

Error bodies use the error envelope.

Example

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"
}'

Delete Message

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

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

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

{
  "ok": true
}

Get Attachment

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

Response

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

Errors

Error bodies use the error envelope.

Example

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

{
  "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

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

Query parameters

Response

200 The attachment bytes (application/octet-stream)

Headers:

Errors

Error bodies use the error envelope.

Example

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

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

Request body

Content type: application/json.

Each item of attachments is a SendAttachment:

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

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."
}'

Get Raw Message

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

Response

200 The raw message (message/rfc822)

Errors

Error bodies use the error envelope.

Example

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

Reply To Message

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

Request body

Content type: application/json.

Each item of attachments is a SendAttachment:

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

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"
}'

Reply All Message

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

Request body

Content type: application/json.

Each item of attachments is a SendAttachment:

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

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"
}'

List Messages in Pod

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

Query parameters

Response

200 A page of messages (application/json)

Each item of messages is a MessageItem:

Errors

Error bodies use the error envelope.

Example

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

Batch Get Messages in Pod

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

Request body

Content type: application/json.

Response

200 The messages found (application/json)

Each item of messages is a Message:

Errors

Error bodies use the error envelope.

Example

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"
  ]
}'

Batch Update Messages in Pod

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

Request body

Content type: application/json.

Response

200 The updated messages (application/json)

Each item of updates is a UpdateMessageResponse:

Errors

Error bodies use the error envelope.

Example

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"
}'

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

Search Messages in Pod

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

Query parameters

Response

200 A page of matching messages (application/json)

Each item of messages is a MessageItem:

Errors

Error bodies use the error envelope.

Example

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

Send Message in Pod

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

Request body

Content type: application/json.

Each item of attachments is a SendAttachment:

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

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."
}'

Get Message in Pod

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

Response

200 The message (application/json)

Each item of attachments is a Attachment:

authentication_results is a MessageAuthenticationResults:

trust is a TrustReport:

Errors

Error bodies use the error envelope.

Example

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

Update Message in Pod

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

Request body

Content type: application/json.

Response

200 The updated message (application/json)

Each item of attachments is a Attachment:

authentication_results is a MessageAuthenticationResults:

trust is a TrustReport:

Errors

Error bodies use the error envelope.

Example

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"
}'

Delete Message in Pod

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

Response

200 Deleted (application/json)

Errors

Error bodies use the error envelope.

Example

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

{
  "ok": true
}

Get Attachment in Pod

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

Response

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

Errors

Error bodies use the error envelope.

Example

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"

Download Attachment in Pod

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

Query parameters

Response

200 The attachment bytes (application/octet-stream)

Headers:

Errors

Error bodies use the error envelope.

Example

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

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

Request body

Content type: application/json.

Each item of attachments is a SendAttachment:

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

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."
}'

Get Raw Message in Pod

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

Response

200 The raw message (message/rfc822)

Errors

Error bodies use the error envelope.

Example

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

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

Request body

Content type: application/json.

Each item of attachments is a SendAttachment:

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

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"
}'

Reply All Message in Pod

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

Request body

Content type: application/json.

Each item of attachments is a SendAttachment:

Response

201 Sent (application/json)

Errors

Error bodies use the error envelope.

Example

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"
}'