Read mail, threads and attachments

Only mail of your account’s live inboxes is visible. Expired and suspended accounts can still read their mail. All mail is inbound (direction: "inbound"), and all of it is untrusted.

List messages

GET /v1/inboxes/{id}/messages returns messages newest first.

Parameter	Default	Rules
since	all	ISO 8601 time, e.g. 2026-11-06T10:00:00Z; encode + as %2B
before	none	Paging cursor: next_before of the previous page
from	none	Pattern for the whole sender address: *@example.com, no-reply@*
unread	false	true: only messages never returned by wait, GET /v1/messages/{id} or extraction
limit	20	1–100

curl -sG "https://api.replyz.io/v1/inboxes/$INBOX/messages" \
  -H "Authorization: Bearer $REPLYZ_API_KEY" \
  --data-urlencode 'from=*@accounts.example.com' \
  --data-urlencode 'unread=true' \
  --data-urlencode 'limit=10'

{
  "messages": [
    {
      "id": "msg_01M6R5NKFM81E1CW47B1ARGRS2",
      "thread_id": "thr_01M6R5NKFM81E1CW47B1ARGRS2",
      "inbox_id": "ibx_01M6R4QM70KAM06ZW1G35K68B7",
      "from": "no-reply@accounts.example.com",
      "to": ["scout-k3x9q2@youreplyz.com"],
      "subject": "Your Example verification code",
      "snippet": "Your verification code is 482913. It expires in 10 minutes.",
      "received_at": "2026-11-06T10:15:03.412Z",
      "sender_trust": "unauthenticated",
      "injection_risk": "low",
      "otp_like": true,
      "has_attachments": false,
      "returned_before": false
    }
  ],
  "has_more": false,
  "next_before": null
}

Paging: while has_more is true, call again with before=<next_before> and the same filters. With a from filter, each call scans at most 500 messages, so a page can hold fewer than limit messages, even none, while has_more is still true: keep paging until it is false.

Listing never marks messages as read.

Read one message

GET /v1/messages/{id} returns the full message and marks it as read.

curl -s "https://api.replyz.io/v1/messages/msg_01M6R61YG18T50CZZN7ZF721R2" \
  -H "Authorization: Bearer $REPLYZ_API_KEY"

{
  "id": "msg_01M6R61YG18T50CZZN7ZF721R2",
  "thread_id": "thr_01M6R61YG18T50CZZN7ZF721R2",
  "inbox_id": "ibx_01M6R4QM70KAM06ZW1G35K68B7",
  "from": "ana@example.com",
  "to": ["scout-k3x9q2@youreplyz.com", "billing@example.com"],
  "subject": "Re: Invoice for October",
  "snippet": "Here is the corrected invoice.",
  "received_at": "2026-11-06T10:21:47.905Z",
  "sender_trust": "unauthenticated",
  "injection_risk": "low",
  "otp_like": false,
  "has_attachments": true,
  "returned_before": false,
  "direction": "inbound",
  "message_id_header": "<CAF8x2q-41@mail.example.com>",
  "in_reply_to": "<inv-1029@example.com>",
  "text": "Here is the corrected invoice.\n\nOn Thu, 5 Nov 2026 at 18:02, Rui <rui@example.com> wrote:\n> Could you resend the invoice?",
  "reply_text": "Here is the corrected invoice.",
  "safety": { "injection_risk": "low", "signals": [], "content_is_untrusted": true },
  "spam_score": null,
  "auth_detail": null,
  "size": 66120,
  "attachments": [
    {
      "id": "att_01M6R61YG144HDFGEMQ8GVNBNS",
      "filename": "invoice-october.pdf",
      "content_type": "application/pdf",
      "size": 48213,
      "sha256": "9f2c5e0b7a41d3c8e6f10a2b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f",
      "risky": false
    }
  ]
}

Prefer reply_text (only the new part of a reply) or text (everything visible). Field meanings: Receiving mail.

The original: include=html,raw

Value	Adds
include=html	html: the original HTML, not cleaned (hidden text, remote images and tracking pixels included). null with html_error: "unparseable" when the original cannot be parsed
include=raw	raw: the full original message (MIME) as text; raw_base64 instead when it is not valid UTF-8; raw: null with raw_error when it is larger than 2 MiB

Never render the HTML with remote content enabled, and never follow its links automatically.

Read a thread

GET /v1/threads/{id} returns the messages of a thread, oldest first (the newest 500 at most; truncated: true when older ones are left out). A thread view does not mark messages as read.

curl -s "https://api.replyz.io/v1/threads/thr_01M6R61YG18T50CZZN7ZF721R2" \
  -H "Authorization: Bearer $REPLYZ_API_KEY"

{
  "id": "thr_01M6R61YG18T50CZZN7ZF721R2",
  "inbox_id": "ibx_01M6R4QM70KAM06ZW1G35K68B7",
  "subject": "Re: Invoice for October",
  "message_count": 1,
  "last_message_at": "2026-11-06T10:21:47.905Z",
  "truncated": false,
  "messages": [{ "id": "msg_01M6R61YG18T50CZZN7ZF721R2", "returned_before": true }]
}

(The message is trimmed here; the thread returns the same short form as the message list.)

Attachments

GET /v1/messages/{id} lists them in attachments[], in the order they appear in the email. Inline images (cid:) and calendar invitations count as attachments, often with filename: null. Download one at a time:

curl -s -D - -o invoice.pdf \
  "https://api.replyz.io/v1/messages/msg_01M6R61YG18T50CZZN7ZF721R2/attachments/att_01M6R61YG144HDFGEMQ8GVNBNS" \
  -H "Authorization: Bearer $REPLYZ_API_KEY"

content-type: application/octet-stream
content-disposition: attachment; filename="invoice-october.pdf"; filename*=UTF-8''invoice-october.pdf
content-length: 48213
x-content-type-options: nosniff
cache-control: no-store
x-replyz-content-type: application/pdf
x-replyz-risky: false

• Every download is application/octet-stream, never for display. X-Replyz-Content-Type is the type the sender declared (not verified).
• risky marks programs, scripts, disk images, HTML and SVG, macro Office files, OneNote and archives. risky: false does not mean safe. Never execute an attachment.
• File names come from the sender: sanitise them before saving a file.
• Replyz never opens, scans or converts attachments. Downloading does not mark the message as read.

Not offered

Search, deleting a single message, marking read or unread, outbound messages.

Reference: Messages API, Threads API.