import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.messages.get(
  "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.get_message(
    "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl 'https://api.mails.ai/v1/messages/msg_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails emails get msg_01JABC

{
  "name": "mails_emails_get",
  "arguments": {
    "message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "agent_id": "agt_01JZ9F8H7KQ2M3N4P5R6S7T8U9",
  "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC11",
  "to": ["jordan@example.com"],
  "cc": [],
  "subject": "Your order #10473 has shipped",
  "body_text": "Your order #10473 is on its way.",
  "body_html": "<p>Hi Jordan,</p><p>…",
  "classifier_score": 0.02,
  "status": "sent",
  "cost_usd": 0.0004,
  "ses_message_id": "0100018f9c2a7b3d-2a1c4e6f-8b0d-4f2a-9c3e-1d5a7b9c0e2f-000000",
  "attachments": [],
  "references": [],
  "metadata": {},
  "tags": [{ "name": "category", "value": "shipping" }],
  "sent_at": "2026-06-24T17:32:09.002Z",
  "delivered_at": "2026-06-24T17:32:11.880Z",
  "created_at": "2026-06-24T17:32:08.421Z",
  "test_mode": false
}

200  The message, including full body and delivery
     timestamps.
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
500  Internal server error.

Retrieve a sent message

GET/v1/messages/{id}scope · read

import { createClient } from "@mailsai/sdk";

const client = createClient(); // reads MAILS_API_KEY

const result = await client.messages.get(
  "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
);
console.log(result);

from mailsai import create_client

client = create_client()  # reads MAILS_API_KEY

result = client.get_message(
    "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
)
print(result)

curl 'https://api.mails.ai/v1/messages/msg_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
  -H "Authorization: Bearer $MAILS_API_KEY"

mails emails get msg_01JABC

{
  "name": "mails_emails_get",
  "arguments": {
    "message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E"
  }
}

{
  "id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
  "agent_id": "agt_01JZ9F8H7KQ2M3N4P5R6S7T8U9",
  "thread_id": "thrd_01JZX8K3M9Q4P7VN2YB6RTDC11",
  "to": ["jordan@example.com"],
  "cc": [],
  "subject": "Your order #10473 has shipped",
  "body_text": "Your order #10473 is on its way.",
  "body_html": "<p>Hi Jordan,</p><p>…",
  "classifier_score": 0.02,
  "status": "sent",
  "cost_usd": 0.0004,
  "ses_message_id": "0100018f9c2a7b3d-2a1c4e6f-8b0d-4f2a-9c3e-1d5a7b9c0e2f-000000",
  "attachments": [],
  "references": [],
  "metadata": {},
  "tags": [{ "name": "category", "value": "shipping" }],
  "sent_at": "2026-06-24T17:32:09.002Z",
  "delivered_at": "2026-06-24T17:32:11.880Z",
  "created_at": "2026-06-24T17:32:08.421Z",
  "test_mode": false
}

200  The message, including full body and delivery
     timestamps.
401  Missing or invalid API key.
403  The API key lacks the required scope
     (insufficient_scope), or the token belongs to an
     app connected by sign-in and this operation is
     closed to connected apps
     (connected_app_not_allowed).
404  Resource not found in this workspace, or the agent
     a send names is archived (agent_archived).
500  Internal server error.

Path Parameters

idstringrequired

Sent message id (msg_…).

Response

idstring

Message id (msg_…), the {id} in /v1/messages/{id}.

agent_idstring

Id of the agent that sent the message (agt_…).

fromstring

The agent address this was sent as — the resolved from. Read it back when you pass from as a naming hint instead of an explicit agent: it is the receipt for which identity the API picked. On a verified custom domain the message goes out from this exact address. On the shared mails.ai domain it goes out from <name>.<workspace>@send.mails.ai, and replies come back through <name>.<workspace>@in.mails.ai.

thread_idstring

The thread the message belongs to (thrd_…).

in_reply_to_message_idstring

The message this one answers: the message replied to or forwarded, or the in_reply_to_message_id the send set. Present on reply responses and on the single-message GET, when set.

tostring[]

The To recipients, always a list. On a reply they come from the original: its Reply-To or sender for a received message, its to for one of your sent messages.

ccstring[]

Cc recipients. Always present on reply responses ([] when none); on the list and the single-message GET, present when there are any.

bccstring[]

Bcc recipients. Present only on the list and the single-message GET, when there are any.

subjectstring

The subject as sent. On a reply, Re: and the original's subject, unless that already starts with Re:; on a forward, the subject you gave or Fwd: and the original's.

body_textstring

The plain-text body as sent; on a forward it includes the quoted original. Present only on the single-message GET, when there is one.

body_htmlstring

The HTML body as sent. Present only on the single-message GET, when there is one.

classifier_scorenumber

The cold-email firewall's score for the message, from 0 (clean) to 1 (cold or spam). Present on the send response, the list and the single-message GET.

statusstring

sent once handed off; delivered, bounced or complained when the receiving side reports it (with several recipients the latest report wins). delayed when a transient (soft) bounce came back: the receiving server has not taken the message yet; it is not a bounce, does not count toward the bounce rate, raises message.delayed (sent only to endpoints that list it) and may still become delivered; with no delivery confirmed within 5 days of sending, it becomes bounced. sending only while a scheduled send is going out; rejected when the send failed, or a scheduled send was refused when it came due; canceled when a scheduled send was stopped. A live send only to the reserved test address reply@test.mails.ai is delivered at once, with a message.delivered event, since it is never transmitted; with a test key it stays sent, as every test-mode send does. Either way its automatic reply arrives as reply.received (at most 3 replies in one thread; a 4th message there gets none).

One of: scheduled, sending, sent, delivered, delayed, bounced, complained, rejected, canceled

refused_recipientsstring[]

The recipients the email service refused when the message was sent, while it took the message for the others: it went to everyone else, and not to these. The message is still a send, so sending it again with the same Idempotency-Key gives this answer back and sends nothing; to reach them, check the addresses and send them a new message. Present only when there were any: on the send, batch, reply and forward responses, the list, the single-message GET and the message's message.sent event. When every recipient is refused, nothing is sent and the send fails instead.

cost_usdnumber

USD cost of the send. 0 for scheduled or test-mode sends.

ses_message_idstring

The sending provider's id for the message, which its delivery, bounce and complaint reports refer to; test-<message id> for a test-mode send. Present only on the list and the single-message GET, once the message has been handed off.

attachmentsobject[]

Name, type and size of each file the send carried; the files themselves are not kept. Present when there were any, on the send response, the list and the single-message GET.

Show propertiesHide properties

filenamestring

The file name, as given in the send's attachments.

content_typestring

The MIME type given in the send's attachments. A file fetched from its path without one takes the type the URL answered with, or application/octet-stream when it named none.

size_bytesinteger

Size of the file in bytes: content_base64 decoded, or the bytes fetched from path.

content_idstring

Only on a file shown inside the HTML body: the id its cid: names.

referencesstring[]

The References chain kept with the message: the references the send passed, or on a reply the ids of the earlier messages it answers. Present only on the single-message GET, when there is one.

metadataobject

The metadata the send passed; a scheduled send refused when it came due also carries rejected_reason and rejected_at. Present only on the single-message GET, when there is any.

tagsobject[]

The tags the message was sent with. Present when there are any, on send, batch and reply responses, the list and the single-message GET.

Show propertiesHide properties

namestring

The tag's name, as given on the send, reply or draft.

valuestring

The tag's value, as given; it may be an empty string.

sent_atstring

When the message was handed off for sending: at once for an immediate send, when it came due for a scheduled one. Present only on the list and the single-message GET, once that has happened.

delivered_atstring

When delivery was confirmed; with several recipients, the time of the latest report. Present only on the list and the single-message GET, once a delivery is confirmed.

scheduled_atstring

The time a scheduled send was set for. On send, batch and reply responses it is present only when that time was in the future; the list and the single-message GET keep it after the message has gone out or been canceled.

canceled_atstring

When the scheduled send was canceled. Present only on the list and the single-message GET, for a canceled message.

bounced_atstring

When a bounce was last reported for the message; a soft bounce, which marks it delayed, does not set it. Present only on the single-message GET.

complained_atstring

When a recipient's complaint about the message was last reported. Present only on the single-message GET.

forwarded_fromstring

Source message id (forward responses only).

test_modeboolean

True for a message sent with a test key (mk_test_…): nothing was transmitted and nothing was billed.

classifier_warningobject

Present only on a test-mode send that a live key would refuse: the cold-email firewall's verdict, reported instead of thrown. Nothing was transmitted.

Show propertiesHide properties

codestring

Always cold_email_prohibited, the error code a live key would get.

One of: cold_email_prohibited

messagestring

The verdict in words: why a live key would refuse the message, what would pass instead, and that nothing was transmitted.

scorenumber

The firewall's score for the message, from 0 (clean) to 1 (cold or spam).

reasonstring

What the message was classified as, such as cold_outreach, spam_pattern or phishing_lure.

created_atstring

When the message was created; for a scheduled send, when it was scheduled, not when it went out.

Was this page helpful?