Overview
These actions manage a connected email mailbox. They run on the samePOST /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
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:
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.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.
Returns the raw file with its Content-Type, or the standard JSON error envelope.