Create and send email 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.

Request

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": "[email protected]",
      "name": "Leyah Miller"
    }],
    "cc": [{
      "email": "[email protected]",
      "name": "Nyla"
    }],
    "bcc": [{
      "email": "[email protected]",
      "name": "Nylas DevRel"
    }],
    "reply_to": [{
      "email": "[email protected]",
      "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.

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.

What’s next

• Send email for direct send and the full message field reference
• Schedule an email to send later to send a message at a future time
• Track email opens and replies for the tracking options drafts support
• Send email with attachments to attach files to a draft