Skip to content
calternal docs

Get a Message

GET
/api/v1/mail/messages/{id}
curl --request GET \
  --url https://example.com/api/v1/mail/messages/example \
  --header 'Authorization: Bearer <token>'

Requires a signed-in User. It returns the Message, its text and HTML body, external links and attachments. Remote images and sender fonts follow the User’s saved Load remote content preference. It returns 404 when the Message is missing. Route: /api/v1/mail/messages/{id}. Inputs: id. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
attachments
required
Array<object>
object
content_type
required
string
filename
required
string
section_id
required
string
size_bytes
required
integer format: int32
body_html

Sanitized content. Clients must render it in a sandboxed frame with a CSP that denies scripts, forms, navigation, and all network resources.

string | null
body_links
required

Explicit links are opened by the client outside the isolated frame.

Array<string>
body_text
required
string
content_pending
required

Internal loading state; no reader prompt or spinner (#726).

boolean
message
required
object
account_id
required
string
attachment_count
required
integer format: int32
bcc
required
Array
body_truncated
required
boolean
category
required
string
cc
required
Array
flags
required
Array<string>
folder_id
required
string
from
required
Array
id
required
string
labels
required
Array<string>
preview
required
string
received_ms
required
integer format: int64
sent_date_ms
integer | null format: int64
subject
required
string
thread_id
required
string
to
required
Array
remote_content_allowed
required

The User’s Load remote content preference when this body was read. Readers drop retained bodies that disagree with the current value (#736).

boolean
Examplegenerated
{
  "attachments": [
    {
      "content_type": "example",
      "filename": "example",
      "section_id": "example",
      "size_bytes": 1
    }
  ],
  "body_html": "example",
  "body_links": [
    "example"
  ],
  "body_text": "example",
  "content_pending": true,
  "message": {
    "account_id": "example",
    "attachment_count": 1,
    "bcc": [
      "example"
    ],
    "body_truncated": true,
    "category": "example",
    "cc": [
      "example"
    ],
    "flags": [
      "example"
    ],
    "folder_id": "example",
    "from": [
      "example"
    ],
    "id": "example",
    "labels": [
      "example"
    ],
    "preview": "example",
    "received_ms": 1,
    "sent_date_ms": 1,
    "subject": "example",
    "thread_id": "example",
    "to": [
      "example"
    ]
  },
  "remote_content_allowed": true
}

404

Section titled “404”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}