---
title: "Write an email with AI"
description: "The body of an email from a prompt, in the style of the mail you send."
url: "https://nextmail.sh/docs/api/emails/compose"
area: "API"
category: "Emails"
---

# Write an email with AI

The body of an email from a prompt, in the style of the mail you send.

`POST /emails/compose`

## 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**

```
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": ["ada@example.com"] }'
```

**Response**

```
{
  "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**

```
curl -X POST "$OE/emails/compose" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "prompt": "Make it shorter, cc bob@example.com 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": ["ada@example.com"], "withSubject": true, "send": {}, "timeZone": "Europe/Berlin" }'
```

**Response**

```
{
  "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": ["bob@example.com"],
    "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.

## Reference

- [`POST /emails/compose`](https://nextmail.sh/docs/api/reference/emails#post-emails-compose): full reference