DEV Community

Qasim
Qasim

Posted on

Manage email drafts with the Nylas API and CLI

#api #email #devtools #productivity

Sometimes an email shouldn't go out the instant your code runs. A human needs to review it first, or the user wants to compose now and hit send later, or an AI agent proposes a reply that a person approves before it ships. The mechanism for all three is the same: a draft. Build that against providers directly and you're juggling Gmail's draft resource, Microsoft Graph's, and an IMAP APPEND to the Drafts folder, each with its own shape and quirks.

The Nylas Email API collapses that into one draft resource. You create a draft on the user's account, it lands in their real Drafts folder, and you send it later with a single request, the same way across Gmail, Microsoft 365, Yahoo, iCloud, IMAP, and Exchange. This post walks the full draft lifecycle from two angles: the HTTP API for your backend, and the nylas CLI for the terminal. I work on the CLI, so the terminal commands below are the ones I reach for.

One draft resource across every provider

A draft in the Nylas model is a real object in the user's mailbox, not a staging area on the side. When you create one, it saves to the user's own Drafts folder on their provider, so it shows up in their normal mail client exactly like a draft they started themselves. That's the property that makes drafts useful for review workflows: a person can open the mailbox and see the pending message before it sends.

Because drafts are real provider objects, edits flow both ways. A draft you create through the API appears in the user's mail client within the provider's sync window, and a change the user makes there alters the same draft you'd fetch back through the API. The operations split across two paths: create and list live on /v3/grants/{grant_id}/drafts, while fetch, update, send, and delete act on a specific draft at /v3/grants/{grant_id}/drafts/{draft_id}. They behave the same across all six providers, so you write the integration once.

Create a draft

Creating a draft is a POST /v3/grants/{grant_id}/drafts with the same message fields you'd use for a send: to, cc, bcc, subject, body, and optional reply_to and tracking_options. Nylas saves it to the user's Drafts folder and returns a draft object with an id you use to update, send, or delete it later. The request below creates a draft with recipients and a body:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Proposal for next quarter",
    "body": "Hi, here is the draft proposal for your review.",
    "to": [{ "email": "client@example.com" }]
  }'
Enter fullscreen mode Exit fullscreen mode

The CLI wraps this in nylas email drafts create, which takes the message as flags. --to (-t), --subject (-s), and --body (-b) are the core ones, with --cc, --reply-to, --attach (-a) for a file, and --signature-id for a stored signature available on top. It's the quickest way to drop a draft into a mailbox and confirm it appears in the user's client:

nylas email drafts create \
  --to client@example.com \
  --subject "Proposal for next quarter" \
  --body "Hi, here is the draft proposal for your review."
Enter fullscreen mode Exit fullscreen mode

The create command accepts a grant ID as an optional argument and otherwise uses your default account, so a quick nylas email drafts create -t client@example.com -s "Hi" -b "Draft body" drops a draft into the connected mailbox in one line.

List and fetch saved drafts

Before sending or editing, you often need to see what's already saved. GET /v3/grants/{grant_id}/drafts lists every draft on the account, and GET /v3/grants/{grant_id}/drafts/{draft_id} returns a single one with its full body and recipients. This is how an approval UI loads pending messages for a reviewer, or how your app confirms a draft was created before showing a send button.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
Enter fullscreen mode Exit fullscreen mode

From the terminal, nylas email drafts list prints the saved drafts and nylas email drafts list --json returns the raw objects for scripting. Fetch one with nylas email drafts show <draft-id>. Because drafts are real provider objects, the list includes drafts the user started in their own mail client, not only the ones your app created.

Update a draft before it sends

A draft isn't frozen once created. PUT /v3/grants/{grant_id}/drafts/{draft_id} updates it, which is what you'd call when a reviewer edits the message or your app revises a proposed reply. There's one behavior to internalize: the update replaces the draft's fields rather than patching them, so you send the full set of recipients and the complete body each time, not just the parts that changed.

curl --request PUT \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts/<DRAFT_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "Proposal for next quarter (revised)",
    "body": "Hi, here is the revised proposal with the updated numbers.",
    "to": [{ "email": "client@example.com" }]
  }'
Enter fullscreen mode Exit fullscreen mode

Because the update is a full replace, treat the draft in your application as the source of truth and re-send its entire state on every change. Updating is API-only: the nylas email drafts command group covers create, list, show, send, and delete, but not update, so revisions go through PUT from your backend. This replace-not-patch behavior is the single most common mistake with the drafts API: send only the changed field and you'll wipe the recipients or body you left out.

Send a draft

Sending is a POST /v3/grants/{grant_id}/drafts/{draft_id} against the draft's own path. Nylas dispatches it through the user's provider, removes it from the Drafts folder, and files the sent copy in the Sent folder, exactly as if the user had clicked send in their mail client. There's no separate send endpoint that needs the message fields again; the POST to the draft's own path is the send.

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts/<DRAFT_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
Enter fullscreen mode Exit fullscreen mode

From the CLI that's nylas email drafts send <draft-id>. Any tracking_options you set when creating the draft still apply when it sends on a connected account, so open and click tracking carries through from draft to delivery. One scoped exception: on Agent Accounts, sending through the drafts endpoint doesn't fire open or click tracking, so if you need tracking on an Agent Account message, send it directly with POST /messages/send and tracking_options instead of drafting it first.

Discard a draft

When a draft is abandoned, DELETE /v3/grants/{grant_id}/drafts/{draft_id} removes it. Because the draft is a real provider object, the delete also removes it from the user's Drafts folder, keeping the mailbox and your application in sync rather than leaving an orphaned draft behind in the user's client.

curl --request DELETE \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/drafts/<DRAFT_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
Enter fullscreen mode Exit fullscreen mode

The CLI command is nylas email drafts delete <draft-id>. Reach for delete when a user cancels a queued message or a review step rejects a proposed reply, so the draft doesn't linger in the mailbox suggesting an email is still pending.

The human-in-the-loop pattern

Drafts are the natural fit for any flow where a message needs approval before it goes out, and that's increasingly an AI-agent flow. The pattern is three steps: the agent generates a draft with POST /drafts, a human reviews it (in your app's UI or directly in the mailbox, since the draft is a real provider object), and on approval you send it by ID with POST /drafts/{draft_id}. Nothing leaves the mailbox until that final call.

This beats having the agent send directly for any message where a mistake is costly. A drafted reply sits in the Drafts folder where a person can catch a wrong recipient, a hallucinated detail, or an inappropriate tone before it reaches the customer. If the reviewer edits the message, you PUT the changes; if they reject it, you DELETE it; if they approve, you POST to send. The whole approval loop maps cleanly onto the four draft operations.

Draft first, or send directly?

Both drafting and a direct POST /messages/send put a message in the user's mailbox, so when is the extra step worth it? Draft when a message needs to exist before it's sent: for human review, for a compose-now-send-later experience, or to let a user open and edit it in their own mail client first. Send directly when the message is ready and nothing stands between composing it and delivering it.

There's a small cost to drafting. It's two API calls instead of one, and the draft occupies the user's Drafts folder until it sends or you delete it. For transactional mail generated and sent in the same step, that overhead buys you nothing, so send directly. For anything a person or a policy has to approve, the draft's place in the real mailbox is the entire point, and the two-call cost is what gives you a safe place to pause.

Attach files to a draft

Drafts carry attachments the same way sends do, and the encoding depends on size. For files that keep the whole request under 3 MB, pass them inline as Base64 in the JSON body, which keeps creating the draft a single call. That 3 MB ceiling covers the message body and the attachments together, so a draft with a couple of small documents is fine inline.

Above 3 MB, switch from JSON to a multipart/form-data request, which providers cap at 25 MB for the full message. The practical rule is simple: a small PDF or image goes inline as Base64, while a larger file uses multipart. From the CLI, nylas email drafts create --attach ./proposal.pdf (or -a) handles the encoding for you. For attachments beyond 25 MB there's a separate large-attachments flow, a Microsoft-only path that uploads the file first (up to 150 MB) and references it by ID.

Whichever path you use, the attachment becomes part of the draft and travels with it. When you later send the draft with POST /drafts/{draft_id}, the files go out with the message; you don't re-attach anything at send time. That's another reason the draft is a clean review primitive: a reviewer opening the draft in their mail client sees the exact attachments that will ship, not a separate list to cross-check. If a reviewer removes or swaps a file, update the draft with PUT so the saved object matches what will actually send.

Things to keep in mind

A few behaviors separate a smooth drafts integration from one that surprises you.

  • Update is a full replace, not a patch. Send the complete recipient list and body on every PUT, or you'll drop the fields you omit.
  • Sending is a POST to the draft itself. You don't re-send the message fields; the POST /drafts/{draft_id} dispatches the saved draft.
  • Drafts are real provider objects. Edits a user makes in their mail client change the same draft, and your delete removes it from their Drafts folder too.
  • Mind the 3 MB inline payload limit. Larger attachments use a multipart/form-data request, capped at 25 MB by the provider, not inline Base64.
  • Drafts are the approval primitive. For agent flows, draft then send-by-ID gives you a clean place for human review before anything ships.

Wrapping up

Drafts give you a save-and-review step that works identically across every provider Nylas connects. Create with POST /drafts, revise with a full-replace PUT, send with a POST to the draft's own path, and discard with DELETE. The CLI's nylas email drafts mirrors all of these except update, which stays on the API. Because each draft is a real object in the user's mailbox, the pattern doubles as a human-in-the-loop approval gate, which is exactly what an AI agent needs before it sends on someone's behalf.

Where to go next:

Top comments (0)