Skip to main content

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

string
required
The email account.
string
required
One of mark_as_read, mark_as_unread, archive, trash.
object
required
Request
200

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

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_*), plus two optional ones:
string
File the draft inside an existing conversation instead of as a standalone draft: the conversation_id returned by list_inbox / get_conversation. When set, to defaults to the sender of the thread’s last message and subject to Re: <its subject>; pass them to override. Gmail and Outlook thread the draft natively; on IMAP the conversation id is the thread’s Message-ID and is used as the In-Reply-To header.
string
Write the draft from a send-as alias of the mailbox instead of its primary address (optional from_name for the display name). The alias must be configured on the mailbox: Gmail replaces an unverified alias with the primary address at send time, Outlook needs Send-As rights on it.
Request
Request (reply draft in a thread, from an alias)
200
provider_message_id is the draft message’s own id (usable with trash to discard it) and thread_id its conversation: Gmail always returns both, Outlook returns them when thread_id was passed, IMAP returns draft_folder instead. from_email echoes the alias when one was used.

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.