Sending and retries

Sending requires mail.send and access to the selected mailbox. Give your agent an explicit instruction to send; onboarding checks should only verify the connection.

Every send_email call needs an idempotencyKey. Generate a unique key for the intended send and save it with the request before submitting. If the response is lost, that key lets you look up what happened.

Send a message

Pass a body like this to the MCP send_email tool or POST /api/mail/send_email. Replace the example mailbox, recipient, and key with values for your intended message:

{
  "accountId": "MAILBOX_ID",
  "idempotencyKey": "UNIQUE_KEY_FOR_THIS_SEND",
  "to": ["recipient@example.com"],
  "subject": "Meeting notes",
  "bodyText": "Here are the notes we discussed."
}

The key must contain 1 to 255 printable ASCII characters without spaces. A UUID works. Save the exact arguments alongside it.

Message fields and attachment formats are listed in the REST reference. To validate recipients, the sender, and attachment sizes before sending, call preview_send with the message fields and a connection with mail.send. Omit idempotencyKey from the preview.

Send a saved draft

Use the draft's ID instead of message fields:

{
  "accountId": "MAILBOX_ID",
  "idempotencyKey": "UNIQUE_KEY_FOR_THIS_SEND",
  "draftId": "DRAFT_ID"
}

Supply either draftId or message fields in a send request. Submitting a saved draft needs mail.send and mail.drafts; reading a draft with get_draft needs mail.drafts.

Send status and duplicate protection

A successful send returns an operationId equal to your idempotency key, a status of succeeded, and the provider's result. REST wraps these fields in data; MCP puts them in structuredContent.data.

Reusing the same key with identical arguments retrieves the saved successful result. Changing the arguments under that key returns idempotency_conflict.

After a timeout or uncertain failure, call get_delivery_operation through MCP or POST /api/mail/get_delivery_operation:

{
  "accountId": "MAILBOX_ID",
  "operationId": "THE_ORIGINAL_IDEMPOTENCY_KEY"
}

Use the returned status to decide what to do next:

Cloud does not automatically retry uncertain sends. A missing send record is not proof that retrying with a new key is safe. Follow the saved send status even when an HTTP error suggests a temporary failure.

Disconnecting a mailbox deletes its send-operation records. Check uncertain sends before disconnecting; reconnecting won't restore duplicate-send protection for those records.