Skip to navigation
API ReferenceToolsEmail

Get one email message

Beta

Read one message from the caller’s connected Gmail or Outlook mailbox.

Returns its headers and its body as plain text, so an agent can keep the whole email (in a CRM timeline, for example) rather than the search snippet. Read-only; attachments are not returned.

Authentication

X-API-KEYstring
API Key authentication via header

Path parameters

message_idstringRequired>=1 character

Provider message id, as GET /tools/email/search returns it in results[].id.

Headers

X-Athena-Session-CredentialstringOptional

Query parameters

catalog_idstring or nullOptional
Connected email account to use, as the catalog asset id returned by the Athena UI or the assets API. Defaults to the caller's default email account. An id that is not one of the caller's own connected accounts in the current workspace is a 404.

Response

Successful Response
catalog_idstring
The connected account the message was read from.
idstring

Provider message id, as GET /tools/email/search returns it and reply_to_message_id accepts.

providerstring

Account provider as Athena reports it: gmail or outlook for accounts connected through the Integrations page; google or microsoft365 for directly-connected accounts.

body_textstringOptionalDefaults to

The message body as plain text, HTML converted. At most 50,000 characters; see truncated.

ccstringOptionalDefaults to

Cc recipients, comma-separated as the provider reports them.

conversation_idstring or nullOptional
Microsoft Graph conversation id. Outlook accounts only.
datestringOptionalDefaults to
Sent or received timestamp, in the provider's format.
draft_idstring or nullOptional
Provider draft id, when the provider exposes one for a draft.
fromstringOptionalDefaults to
Sender, as the provider reports it.
is_draftbooleanOptionalDefaults to false
True when the message is an unsent draft sitting in the mailbox.
subjectstringOptionalDefaults to
Subject line.
thread_idstring or nullOptional
Gmail thread id. Gmail accounts only.
tostringOptionalDefaults to

Recipients, comma-separated as the provider reports them.

truncatedbooleanOptionalDefaults to false

True when body_text was cut to its maximum length.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
502
Bad Gateway Error