Manage Emails

Overview

These actions manage a connected email mailbox. They run on the same POST /v2/messages endpoint (except attachment download, a GET). Each action costs 1 credit. Availability: all actions work on Gmail, Outlook and IMAP/SMTP mailboxes. Outlook’s write actions (mark_as_read/mark_as_unread, archive, trash, create_draft) require a mailbox connected with the Mail.ReadWrite scope — reconnect mailboxes added earlier. On IMAP, archive/trash move the message to the mailbox’s Archive/Trash folder (best-effort per server). The id used below is the provider message id returned by List Inbox (conversations[].id) and Get Conversation (messages[].id).

Read state, archive, trash

`action`	Effect
`mark_as_read`	Marks the message read.
`mark_as_unread`	Marks it unread.
`archive`	Removes it from the inbox (keeps it in All Mail / Archive).
`trash`	Moves it to Trash.

string

required

The email account.

string

required

One of mark_as_read, mark_as_unread, archive, trash.

object

required

Show params properties

string

required

The provider message id (from list_inbox / get_conversation).

Request

{ "account_id": "your-email-account-id", "action": "mark_as_read", "params": { "id": "1a09b5fe5c04c6d6" } }

200

{
  "success": true,
  "data": { "status": "success", "message_id": "1a09b5fe5c04c6d6", "unread": false },
  "metadata": { "action": "mark_as_read", "account_id": "your-email-account-id", "credits_consumed": 1, "timestamp": "2026-09-14T12:00:00Z" }
}

List labels

action: "list_labels" returns the mailbox’s folders/labels (id, name, type) — use a label id in list_inbox’s label_ids to read another folder.

200

{
  "success": true,
  "data": { "labels": [ { "id": "INBOX", "name": "INBOX", "type": "system" }, { "id": "Label_12", "name": "Clients", "type": "user" } ] },
  "metadata": { "action": "list_labels", "account_id": "your-email-account-id", "credits_consumed": 1, "timestamp": "2026-09-14T12:00:00Z" }
}

Create a draft

action: "create_draft" saves a draft (not sent). Same body params as Send (to, subject, message_text / html, plus attachments via media_*).

Request

{ "account_id": "your-email-account-id", "action": "create_draft", "params": { "to": "[email protected]", "subject": "Draft", "message_text": "..." } }

200

{
  "success": true,
  "data": { "status": "success", "draft_id": "r-5596439384536493289", "message_id": "<[email protected]>" },
  "metadata": { "action": "create_draft", "account_id": "your-email-account-id", "credits_consumed": 1, "timestamp": "2026-09-14T12:00:00Z" }
}

Download attachment

GET /v2/messages/attachment streams an attachment’s bytes. For email, pass the message_id and attachment_id from a message’s attachments[] (via Get Conversation), plus an optional filename. Gmail and Outlook. Costs 1 credit.

string

required

The email account.

string

required

The provider message id carrying the attachment (attachments[].message_id).

string

required

The attachment id (attachments[].attachment_id).

string

Optional filename for the download.

Returns the raw file with its Content-Type, or the standard JSON error envelope.

Getting Started

Accounts

Profiles

Messaging

Network

Content

Recruiting

Credits

Logs

Email Enrichment

Webhooks (Real-Time)

Overview

Read state, archive, trash

List labels

Create a draft

Download attachment

​Overview

​Read state, archive, trash

​List labels

​Create a draft

​Download attachment

Overview

Read state, archive, trash

List labels

Create a draft

Download attachment