Use the Cloud REST API
Make your first request, choose a mailbox, and look up operation arguments.
Call POST https://cloud.fluxmail.ai/api/mail/{operation} with JSON arguments and an Authorization: Bearer header. REST and MCP use the same operations, mailbox grants, and scopes.
Mail operations need a connected mailbox and a Cloud agent key. The examples below use mail.read. Complete the quickstart if you haven't created a key yet.
Verify a read-only connection
Make your key available privately as FLUXMAIL_CLOUD_AGENT_KEY in your terminal's environment. Keep its value out of shell history, source files, and logs.
1. List your mailboxes
curl --fail-with-body https://cloud.fluxmail.ai/api/mail/list_accounts \
--header "Authorization: Bearer $FLUXMAIL_CLOUD_AGENT_KEY" \
--header 'Content-Type: application/json' \
--data '{}'The response contains only mailboxes available to the key. An example response:
{
"data": [
{
"id": "11111111-1111-4111-8111-111111111111",
"email": "you@example.com",
"provider": "gmail",
"shared": false,
"enabled": true
}
]
}2. List your 5 most recent emails
Copy the intended mailbox's id into this request, replacing MAILBOX_ID:
curl --fail-with-body https://cloud.fluxmail.ai/api/mail/list_emails \
--header "Authorization: Bearer $FLUXMAIL_CLOUD_AGENT_KEY" \
--header 'Content-Type: application/json' \
--data '{"accountId":"MAILBOX_ID","pageSize":5,"includeSnippet":false}'A successful response contains up to 5 email summaries. These two calls verify the key, its mailbox access, and the provider connection without opening message bodies or changing mail. A mailbox with fewer than 5 emails returns fewer results.
Operations and arguments
| Operation | Scope | Arguments |
|---|---|---|
get_connection_status | Any scope | {} |
send_feedback | None | message (1 to 4,000 characters), optional category (bug, feature, or other; defaults to other), requestId, toolName, errorCode, expectedBehavior, actualBehavior, contactEmail |
list_accounts | mail.read | {} |
list_emails | mail.read | accountId, optional query in the search syntax, folder, rawProviderQuery, pageSize (1 to 100), pageToken, includeSnippet, and includeSearchContext |
list_emails_batch | mail.read | accounts (1 to 20 objects with accountId and optional pageToken), optional query, a folder role, pageSize, includeSnippet, and includeSearchContext |
search_emails, search_emails_batch | mail.read | Other names for list_emails and list_emails_batch, with the same arguments |
get_email | mail.read | accountId, messageId, optional includeHeaders |
get_email_body | mail.read | accountId, messageId, bodyFormat (text or html), optional offset and maxChars (1 to 50,000) |
get_thread | mail.read | accountId, threadId |
list_folders, list_labels, list_send_as | mail.read | accountId |
download_attachment | mail.read | accountId, messageId, attachmentId |
get_draft | mail.drafts | accountId, draftId |
create_draft | mail.drafts | accountId, message fields |
update_draft | mail.drafts | accountId, draftId, message fields |
delete_draft | mail.drafts | accountId, draftId |
preview_send | mail.send, plus mail.drafts with draftId | accountId, message fields or draftId |
send_email | mail.send, plus mail.drafts with draftId | accountId, idempotencyKey, message fields or draftId, optional sendAt |
forward_email | mail.send and mail.read | accountId, idempotencyKey, messageId, to, optional cc, bcc, from, comment, includeAttachments, and sendAt |
get_delivery_operation | mail.send | accountId, operationId (the send's idempotency key) |
list_scheduled_emails | mail.read | optional accountId |
cancel_scheduled_email | mail.drafts | scheduleId, optional accountId |
modify_emails | mail.organize, mail.trash, or mail.delete, depending on action | accountId, messageIds, action, and folder or labels when required |
Modification actions require mail.organize for flags, labels, archive, and move; mail.trash for trash and untrash; or mail.delete for permanent deletion. Generic moves cannot target Trash or Archive or restore messages from Trash. Cloud returns succeededIds, failed (each with a messageId and error code), and uncertainIds. If the provider stops partway through, for example because of a rate limit or a network error, Cloud can't tell which messages changed and lists them all in uncertainIds. Check uncertain messages before you retry them. A move to a folder the mailbox doesn't have changes nothing and fails the whole call with not_found; use a folder ID from list_folders.
get_connection_status returns workspace, connection (its kind, name, scopes, mailbox mode and expiration), mailboxes with their IDs, subscription (whether the plan is active, with its status and end dates, including graceEndsAt when a failed payment has a deadline), and dashboard links. It doesn't contact a mail provider.
For mailbox operations, use IDs returned by Cloud and include accountId to select a mailbox. list_emails filters through a query string such as from:ann@example.com is:unread after:2026-01-01 invoice. Use folder for a custom folder or label; if the query also sets in:, the two must name the same folder. Search words can't be combined with rawProviderQuery. list_emails_batch returns one group per mailbox, each with a page of results or an error, and fails only when every mailbox fails. Dates use YYYY-MM-DD. Follow returned pagination tokens; the default page size is 25. A page token expires after an hour and works only with the same mailbox, filters, and page size.
Message fields include to, cc, and bcc as arrays of address strings, subject, bodyText, bodyHtml, optional from, attachments, replyToMessageId, and replyAll. Attachments use filename, mimeType, and base64 content, with optional inline-image fields. A new message or draft needs at least one recipient. Replying to a message requires mail.read as well as the operation's scope so Cloud can read the original.
Modification actions are markRead, markUnread, star, unstar, archive, trash, untrash, delete, move, addLabels, and removeLabels. move requires folder; label actions require labels. Permanent deletion is unavailable for Gmail OAuth connections. MCP lists each action as a separate tool with the same arguments minus action: mark_emails_read, mark_emails_unread, star_emails, unstar_emails, archive_emails, trash_emails, restore_emails, delete_emails, move_emails, add_labels, and remove_labels.
Send feedback
Call send_feedback with a message the user has reviewed and approved, along with any approved diagnostics. It needs an active agent key, no mail scope or mailbox access, and works after the plan ends. Submit only at the user's request; do not retry automatically.
| Field | Constraint |
|---|---|
message | Required; 1 to 4,000 characters |
category | Optional; bug, feature, or other (default) |
requestId | Optional; the related failed call's UUID |
toolName, errorCode | Optional; 1 to 64 lowercase letters or underscores each |
expectedBehavior, actualBehavior | Optional; 1 to 1,000 characters each |
contactEmail | Optional; one valid email address, at most 320 characters, confirmed by the user |
The text in message, expectedBehavior and actualBehavior must not be blank or contain NUL characters. Omit diagnostics you do not know. Never select a connected mailbox address as contactEmail automatically. Cloud includes the signed-in account email separately and uses it for replies if contactEmail is omitted. Reports also include account and workspace IDs, the product version, submission request ID and transport. Keep email contents, attachments, raw tool arguments, provider responses, logs, conversation history and credentials out of feedback. See the privacy policy for recipients and retention.
The response contains feedbackId, the exact message, category, product, optional version and the submitted diagnostics. It echoes a caller-provided reply address without exposing the automatically resolved account email.
Each user can submit five reports per hour across keys and workspaces; further submissions return rate_limited. Feedback doesn't count toward mail usage. Cloud keeps reports for 90 days, or until the account or workspace is deleted; downstream copies have separate retention.
Download an attachment
Unlike the other operations, download_attachment returns the file's bytes as the response body. Content-Type carries the attachment's MIME type and Content-Disposition carries its filename, so you can save the body as is. Use the message ID and the attachment's id from get_email:
curl --fail-with-body https://cloud.fluxmail.ai/api/mail/download_attachment \
--header "Authorization: Bearer $FLUXMAIL_CLOUD_AGENT_KEY" \
--header 'Content-Type: application/json' \
--data '{"accountId":"MAILBOX_ID","messageId":"MESSAGE_ID","attachmentId":"ATTACHMENT_ID"}' \
--output report.pdfIf the provider reports an invalid MIME type, Cloud sends application/octet-stream. Errors use the usual JSON error body. With --output, curl writes that error body to the file and exits with code 22, so check the exit code before opening the file.
Search example
Send this body to /api/mail/list_emails with a read-scoped key:
{
"accountId": "MAILBOX_ID",
"query": "subject:invoice after:2026-10-01",
"pageSize": 10
}Call from Node.js
Save this helper in an .mjs file and run it with a Node.js release that includes fetch. Supply your key and the mailbox ID from list_accounts as environment variables before running it.
const token = process.env.FLUXMAIL_CLOUD_AGENT_KEY;
const accountId = process.env.FLUXMAIL_CLOUD_ACCOUNT_ID;
if (!token || !accountId) {
throw new Error('Set FLUXMAIL_CLOUD_AGENT_KEY and FLUXMAIL_CLOUD_ACCOUNT_ID.');
}
async function call(operation, args) {
const response = await fetch(
`https://cloud.fluxmail.ai/api/mail/${operation}`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(args),
}
);
const result = await response.json();
if (!response.ok) {
const code = result.error?.code ?? response.status;
const requestId = result.requestId ?? response.headers.get('x-request-id');
throw new Error(`${operation}: ${code}; request ${requestId}`);
}
return result.data;
}
await call('list_emails', { accountId, pageSize: 5, includeSnippet: false });
console.log('Fluxmail Cloud mailbox access verified.');The helper makes one request per call and leaves retries to your application. It parses every response as JSON, so read download_attachment responses with response.arrayBuffer() instead. It prints neither message contents nor the key.
Send status and duplicate protection
Every send requires an idempotencyKey. See sending and retries for message examples and the steps to take after a timeout. Never retry an uncertain send with a fresh key.
Errors and retries
Failures return an error with a code and message. Keep the requestId or x-request-id response header for troubleshooting. See errors and retries for status codes and limits for quotas and attachment sizes.
Cloud uses /api/mail/{operation} paths, separate from the self-hosted package's versioned API. Agent keys cannot manage mailbox connections or create keys; use the dashboard for those actions.
Last updated