Read a message

GET/api/v1/mailbox/messages/{message_id}
Requires amailbox token— it acts as one mailbox holder, not as the organization.

One message in full: headers, text and HTML bodies, attachments, and how it was authenticated. Reading it does not mark it read; call mark-read for that.

Errors

Status When
401 No token, or the session expired or was signed out. Sign in again with POST /mailbox-auth/login.
403 The account has a temporary password: until POST /security/password succeeds, every other call answers this with error_code: password_change_required.
404 No message with that id (it may have been moved; ids change when a message moves).

Parameters

NameInTypeDescription
message_idrequiredpathstring

Request

GET/api/v1/mailbox/messages/{message_id}
curl -X GET 'https://courier.mailyte.com/api/v1/mailbox/messages/01JBT8XQ2M9WYC3K4F6R7S8T9V' \
  -H 'Authorization: Bearer MAILBOX_TOKEN'

Response

Successful Response

  • dataobject
    • idstring

      This message's id: folder:uid, e.g. INBOX:4821. Use it in every per-message call.

    • folderstring
    • subjectstring
    • fromarray<object>
      • namestring or null
      • emailstringrequired
    • toarray<object>
      • namestring or null
      • emailstringrequired
    • ccarray<object>
      • namestring or null
      • emailstringrequired
    • received_atstring or null

      ISO 8601 with offset.

    • sizeinteger

      Bytes.

    • has_attachmentboolean
    • is_readboolean
    • is_starredboolean
    • is_answeredboolean
    • is_draftboolean
    • keywordsarray<string>

      Labels on this message.

    • previewstring or null

      The first line or two of text.

    • thread_idstring or null
    • message_idstring or null

      The RFC 5322 Message-ID header.

    • body_textstring or null

      The plain-text body.

    • body_htmlstring or null

      The HTML body, sanitised. Remote images are not loaded.

    • referencesstring or null
    • in_reply_tostring or null
    • attachmentsarray<object>
      • indexinteger

        Position in the message; pass it to the attachment download.

      • namestring
      • typestring

        MIME type, e.g. application/pdf.

      • sizeinteger

        Bytes.

      • is_inlineboolean

        An image shown inside the body (a cid: reference) rather than a file.

      • content_idstring or null

        The cid: the body refers to, for inline images.

    • mailed_bystring or null

      The sending server's domain.

    • signed_bystring or null

      The DKIM signing domain.

    • authenticationobject

      What the receiving server recorded.

      • spfstring or null
      • dkimstring or null
      • dmarcstring or null
    • list_unsubscribeobject

      Present for mailing-list mail.

      • mailtostring or null
      • urlstring or null
      • one_clickboolean
200application/json
{
  "type": "success",
  "msg": "Message retrieved successfully",
  "data": {
    "id": "INBOX:4821",
    "folder": "INBOX",
    "subject": "Re: the quarterly numbers",
    "from": [
      {
        "name": "Tunde Bello",
        "email": "tunde@example.com"
      }
    ],
    "to": [
      {
        "name": "Ada Obi",
        "email": "ada@yourdomain.com"
      }
    ],
    "cc": [],
    "received_at": "2026-10-11T09:14:02+00:00",
    "size": 18432,
    "has_attachment": true,
    "is_read": false,
    "is_starred": false,
    "is_answered": false,
    "is_draft": false,
    "keywords": [],
    "preview": "Attached are the Q3 figures we discussed.",
    "thread_id": "1a2b3c",
    "message_id": "<CAJ9x2Q@mail.example.com>",
    "body_text": "Hi Ada,\n\nAttached are the Q3 figures we discussed.\n\nTunde",
    "body_html": "<p>Hi Ada,</p><p>Attached are the Q3 figures we discussed.</p><p>Tunde</p>",
    "references": null,
    "in_reply_to": null,
    "attachments": [
      {
        "index": 1,
        "name": "q3-figures.pdf",
        "type": "application/pdf",
        "size": 248311,
        "is_inline": false,
        "content_id": null
      }
    ],
    "mailed_by": "mail.example.com",
    "signed_by": "example.com",
    "authentication": {
      "spf": "pass",
      "dkim": "pass",
      "dmarc": "pass"
    },
    "list_unsubscribe": null
  }
}

Returned inside the standard envelope.

Errors

StatusWhen
401No token, or the session expired or was signed out. Sign in again with `POST /mailbox-auth/login`.
403The account has a temporary password: until `POST /security/password` succeeds, every other call answers this with `error_code: password_change_required`.
404No message with that id (it may have been moved; ids change when a message moves).
422Validation Error

Every status, with what causes it and what to do, is on the error reference.