# Create and send email drafts

Source: https://developer.nylas.com/docs/cookbook/email/manage-drafts/

You want your app to save an email for the user to review before it goes out, or to compose now and send on a click. Building that against each provider means Gmail's draft resource, Microsoft Graph's, and an IMAP `APPEND` to the Drafts folder, each with its own shape.

The Nylas Email API gives you one draft resource. You create a draft through the user's account, it shows up in their real Drafts folder, and you send it later with a single request, across all 6 providers.

## How do I create a draft?

Send a `POST /v3/grants/{grant_id}/drafts` request with the message fields you'd use for a send: `to`, `cc`, `bcc`, `subject`, `body`, and optional `reply_to` and `tracking_options`. Nylas saves the draft to the user's own Drafts folder on their provider, so it's visible in their mail client too. The draft works the same across all 6 providers.

The request below creates a draft with recipients, a body, and open and click tracking enabled.

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/drafts' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "subject": "With Love, From Nylas",
    "to": [{
      "email": "leyah@example.com",
      "name": "Leyah Miller"
    }],
    "cc": [{
      "email": "nyla@example.com",
      "name": "Nyla"
    }],
    "bcc": [{
      "email": "nylas-devrel@example.com",
      "name": "Nylas DevRel"
    }],
    "reply_to": [{
      "email": "nylas@example.com",
      "name": "Nylas"
    }],
    "body": "This email was sent using the Nylas Email API. Visit https://nylas.com for details.",
    "tracking_options": {
      "opens": true,
      "links": true,
      "thread_replies": true,
      "label": "Just testing"
    }
  }'

```

## How do I send a draft?

Send the draft with a `POST /v3/grants/{grant_id}/drafts/{draft_id}` request. Nylas dispatches it through the user's provider, removes it from the Drafts folder, and files the sent copy in their Sent folder, exactly as if the user clicked send. Sending a draft works across all 6 providers, and the `tracking_options` you set on the draft still apply.

To schedule a draft for the future instead of sending it now, see [Schedule an email to send later](/docs/cookbook/email/schedule-send/).

## Manage drafts from the terminal

Drafting before sending is the right pattern when a human or an approval step reviews mail first. The [Nylas CLI](https://cli.nylas.com/docs/commands) manages drafts directly: `nylas email drafts create` writes a draft to the mailbox, `drafts list` shows them, and `drafts send` dispatches one by ID.

```bash
# Create a draft
nylas email drafts create --to user@example.com --subject "WIP" --body "Draft body"

# List drafts, then send one by ID
nylas email drafts list
nylas email drafts send <draft-id>
```

Drafts persist server-side and sync to the provider's Drafts folder across all 6 providers, so they appear in the user's normal mail client too. This is also the pattern for an AI agent: generate a draft, route it through human approval, then send the approved draft by ID. See the [`email drafts create`](https://cli.nylas.com/docs/commands/email-drafts-create) and [`email drafts send`](https://cli.nylas.com/docs/commands/email-drafts-send) command reference.

## How do I update or delete a draft?

Update a draft with `PUT /v3/grants/{grant_id}/drafts/{draft_id}` and delete it with `DELETE` on the same path. These 2 operations round out the draft lifecycle, and both work across all 6 providers. Updating replaces the draft's fields, so send the full set of recipients and body each time rather than a partial change.

Use delete to discard a draft the user abandons, which also removes it from their provider's Drafts folder so the two stay in sync.

## Things to know about drafts

Drafts are real provider objects, not a Nylas-side staging area, so a few provider behaviors carry through. A draft created this way appears in the user's mail client within the provider's sync window, and edits the user makes there change the same draft you'd fetch back. Attachments passed inline as Base64 in the JSON request are limited to a 3 MB total request payload; larger files use the separate attachments flow.

Because the draft sends from the user's own mailbox, the recipient sees it as a normal message from that person, with no Nylas branding. For the full field reference and the direct-send alternative, see [Send email](/docs/v3/email/send-email/).

## What's next

- [Send email](/docs/v3/email/send-email/) for direct send and the full message field reference
- [Schedule an email to send later](/docs/cookbook/email/schedule-send/) to send a message at a future time
- [Track email opens and replies](/docs/v3/email/message-tracking/) for the tracking options drafts support
- [Send email with attachments](/docs/cookbook/email/attachments/send-attachments/) to attach files to a draft