Write an email with AI
The body of an email from a prompt, in the style of the mail you send.
Runs the real call on your workspace.
POST /emails/compose
The body of an email from a prompt, in the style of the mail you send.
Example
Needs emails:send. prompt is an instruction, a rough draft or a few notes. subject, to and cc help the greeting and the tone fit, and threadId writes a reply, reading that thread as context, which also needs threads:read.
curl -X POST "$OE/emails/compose" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "prompt": "Thank Ada for the signed contract and ask for the invoice by Friday.", "to": ["[email protected]"] }'{ "object": "composition", "body": "Hi Ada,\n\nThank you for sending the signed contract. Could you send the invoice by Friday?\n\nBest,\nGrace"}Nothing is saved or sent. Send the body with POST /emails, or save it with POST /drafts.
Each call spends one AI action. A workspace that has used them all for the day gets a 429 ai_quota_exceeded.
Change a draft and its send options
Give draft, the body so far, and prompt says what to change in it. withSubject adds a subject, and send, the send options as they stand, lets prompt change the recipients, the send time, tracking, the signature and the language. Times are read in timeZone, or the time zone of your account. With from and send.fromOptions, prompt can move the email to another of your addresses. With send.encrypt, given when every recipient can receive encrypted mail, it can turn end-to-end encryption on or off. With templates: true, prompt can switch the email to one of your published templates, and with files: true it can attach files your workspace holds: they come back in attach, ready to send as { "fileId": id }.
curl -X POST "$OE/emails/compose" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "prompt": "Make it shorter, cc [email protected] and send it tomorrow at 9", "draft": "Hi Ada,\n\nThank you so much for sending the signed contract over. Could you send the invoice by Friday?\n\nBest,\nGrace", "to": ["[email protected]"], "withSubject": true, "send": {}, "timeZone": "Europe/Berlin" }'{ "object": "composition", "body": "Hi Ada,\n\nThanks for the signed contract. Could you send the invoice by Friday?\n\nBest,\nGrace", "subject": "Invoice for the signed contract", "send": { "cc": ["[email protected]"], "scheduledAt": "2026-10-09T07:00:00.000Z" }}send holds only what changed, in the shape POST /emails takes, and null takes an option away, such as "scheduledAt": null to send right away.
note comes back when part of prompt cannot be done this way, such as attaching a file.