# Draft email with Smart Compose

Source: https://developer.nylas.com/docs/cookbook/email/smart-compose/

You want an "AI draft" button that turns a short instruction into a written email, or a one-click reply that already understands the thread. Wiring your own model means prompt plumbing, thread context handling, and a tone that matches email.

Nylas Smart Compose does the generation for you. You send a prompt, it returns a written suggestion, and a message-scoped variant drafts a reply that already has the original message as context.

## How do I generate an email with Smart Compose?

Send a `POST /v3/grants/{grant_id}/messages/smart-compose` request with a single `prompt` field describing what you want. Nylas returns a `suggestion` string with the generated message body, which you drop into a draft or your compose box. The request needs just 1 field, the `prompt`, and a missing prompt returns a `400` `prompt_required_error`.

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "Write a friendly note following up on the proposal I sent last week"
  }'
```

The generated text is a starting point, not a sent message, so you stay in control of the final copy.

## How do I generate a reply to a message?

Send a `POST /v3/grants/{grant_id}/messages/{message_id}/smart-compose` request to draft a reply to a specific message. This message-scoped endpoint takes the same 1 `prompt` field and uses the original message as context, so the prompt can be as short as "decline politely" and the `suggestion` still reflects the thread. It's the difference between composing in a vacuum and replying with context.

Pair it with the [drafts API](/docs/cookbook/email/manage-drafts/) to save the generated reply for the user to review and edit before it sends.

## Things to know about Smart Compose

A couple of points shape how you use the 2 endpoints. Smart Compose requires a Google or Microsoft grant, so it isn't available on every provider. The `prompt` is required on both endpoints, and the API returns 1 message per request, so generate again with a refined prompt rather than expecting multiple variants at once. The output is plain generated text: review it before sending, since it can get facts or names wrong like any generated copy.

Smart Compose runs on the Nylas side and doesn't send anything itself. Treat the suggestion as draft content and send it through the normal send or draft flow once a human approves it.

## What's next

- [Create and send email drafts](/docs/cookbook/email/manage-drafts/) to save a generated message for review
- [Send email](/docs/v3/email/send-email/) to send the approved copy
- [Smart Compose reference](/docs/reference/api/smart-compose/) for the request and response schema
- [Build an AI email triage agent](/docs/cookbook/agents/email-triage-agent/) for a fuller AI email workflow