API ReferenceToolsEmail

Create an email draft

Beta

Save a draft in the caller’s connected Gmail or Outlook account.

Nothing is sent. The draft appears in the account’s Drafts folder, where it is reviewed, edited and sent from the mail client — that review step is why drafting is available here while sending is not. Set reply_to_message_id to thread the draft as a reply.

Authentication

X-API-KEYstring
API Key authentication via header

Request

This endpoint expects an object.
bodystringRequired

Body content. HTML is supported; plain-text newlines become line breaks. Do not write a signature into it — the account’s signature is appended automatically (see include_signature).

subjectstringRequired
Subject line.
tolist of stringsRequired
Recipient email addresses.
bcclist of strings or nullOptional
BCC recipients.
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.
cclist of strings or nullOptional
CC recipients.
include_signatureboolean or nullOptional

Optional: Whether to append the sending account’s own signature at the end of the body. Leave unset to follow the user’s saved preference for this account (which distinguishes new messages from replies) — that is almost always the right choice. Set false only when the user asks for no signature. Never write a signature into the body yourself: the real one is read from the account and appended automatically.

reply_to_message_idstring or nullOptional

Provider message id (from GET /tools/email/search) to reply to, so the draft is threaded under that message. Outlook rejects an id it cannot find (404). Gmail saves the draft unthreaded when the referenced message cannot be read, and reply_to_message_id in the response tells you which happened.

Response

Successful Response
catalog_idstring
The connected account the draft is in.
providerstring

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

successboolean
Whether the draft was saved.
draft_idstring or nullOptional
Provider draft id. Open, edit, or send it in the mail client.
email_addressstring or nullOptional
The address the draft will be sent from.
messagestring or nullOptional

Human-readable outcome, when the provider reports one.

message_idstring or nullOptional
Provider message id backing the draft. Gmail accounts only.
reply_to_message_idstring or nullOptional
The message this draft replies to, when it is a reply.
tracking_idstring or nullOptional

Athena email-tracking id, when tracking is enabled on the account.

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