Why Email Drafts Deserve a Better Developer Experience
Not every email should fire the moment your code runs. Sometimes a human needs to review an outgoing message before it reaches a customer. Sometimes a user wants to compose an email now and send it hours later. And increasingly, AI agents are proposing replies that require a human checkpoint before they ship. In all three scenarios, the solution is the same: a draft.
The problem is that building draft management directly against individual email providers is surprisingly painful. Gmail has its own draft resource with its own API shape. Microsoft Graph has another. IMAP requires you to manually APPEND a message to a Drafts folder and handle the raw MIME yourself. Each provider has its own quirks, its own authentication flow, and its own error surface. If you're building a product that works across multiple email providers — which most real-world applications do — you're looking at writing and maintaining three separate codebases just to handle drafts.
The Nylas Email API solves this by collapsing every provider's draft implementation into a single, unified draft resource. One API shape. One authentication model. The same behavior whether the user is on Gmail, Microsoft 365, Yahoo, iCloud, IMAP, or Exchange.
How the Nylas Draft Model Works
A key insight in the Nylas draft model is that a draft is a real object in the user's mailbox, not a staging area sitting off to the side in some intermediary database. When you create a draft through the Nylas API, it is saved directly to the user's Drafts folder on their actual email provider. That means it shows up in their normal mail client — Outlook, Gmail, Apple Mail — exactly like a draft they started themselves.
This property is what makes drafts genuinely useful for review workflows. A manager or compliance officer can open their own inbox, navigate to Drafts, and inspect a pending message before it ever goes out. There's no separate interface to log into, no custom dashboard to build. The draft lives where the user already works.
Because drafts are real provider objects, edits flow in both directions. A draft you create through the API will appear in the user's mail client within the provider's standard sync window. And if the user makes changes to that draft inside their mail client, those changes will be reflected when you fetch the draft back through the API. The draft stays in sync regardless of where it was last edited.
The Draft Lifecycle: Create, Update, and Send
The full draft lifecycle in Nylas is clean and predictable. Operations are split across two endpoint paths. Creating a new draft and listing existing drafts both live on /v3/grants/{grant_id}/drafts. Fetching a specific draft, updating it, deleting it, and sending it are performed against /v3/grants/{grant_id}/drafts/{draft_id}.
Creating a Draft
To create a draft, you send a POST request to the drafts collection endpoint with a JSON body that describes the message. You can set the subject, body, recipients, CC, BCC, and reply-to fields. The response returns a draft object that includes a unique id, which you'll use for all subsequent operations on that draft. At this point, the draft exists in the user's mailbox and is visible in their mail client.
Updating a Draft
Updating a draft is a PUT request to the individual draft endpoint. You pass the fields you want to change — perhaps the body has been revised after a reviewer left feedback, or the recipient list has been updated. Nylas applies the change and syncs it back to the provider. Because the draft is a live provider object, the updated version will appear in the user's mail client on their next sync.
Sending a Draft
When the draft is ready to go, sending it is a single additional request. Nylas handles the provider-specific send mechanism under the hood, so you don't have to think about whether you're calling Gmail's send endpoint, triggering a Microsoft Graph send action, or constructing an SMTP transaction. The behavior is identical from your code's perspective regardless of the underlying provider.
Working with Drafts from the Terminal Using the Nylas CLI
For developers who prefer working from the terminal — or who want to explore and test the API without writing code first — the Nylas CLI provides a direct interface to every draft operation. The CLI mirrors the HTTP API closely, making it a natural companion to backend development. You can create, list, fetch, update, delete, and send drafts entirely from the command line.
The CLI is especially useful during development and debugging. Rather than constructing curl commands by hand or reaching for a GUI tool like Postman, you can interact with real grant data quickly using concise terminal commands. This makes it easy to verify that a draft was created correctly, check its current state after an update, or confirm that a send operation completed as expected.
Building Review Workflows with Drafts
The draft lifecycle described above maps cleanly onto a number of real-world product patterns. Consider an AI-assisted email tool where an agent composes a suggested reply based on a conversation thread. Rather than sending that reply immediately, your application creates it as a draft. The user sees it in their Drafts folder, reviews it, makes any edits they want in their normal mail client, and then either sends it themselves or triggers a send through your application. The entire flow requires no custom UI for the review step — the user's existing mail client serves that role.
The same pattern applies to approval workflows in business contexts. A sales rep drafts an email, and a manager must approve it before it goes to a prospect. The draft is created via the API, the manager is notified, they review it in their own mail client or through a lightweight interface your application provides, and once approved, the send request is made. All of this runs on real provider objects, so there's no synchronization problem to solve.
Why a Unified Draft API Changes the Equation
The practical benefit of the Nylas unified draft resource is that you write your draft management logic once. You don't branch on provider type. You don't maintain separate integrations for Gmail and Microsoft 365 and IMAP. You don't track down provider-specific edge cases when a draft fails to save correctly on one platform but not another.
For product teams building email features, this translates directly into faster development cycles and a smaller surface area for bugs. For platform teams managing integrations at scale, it means fewer provider-specific incidents and a single abstraction to reason about. The Nylas API and CLI together give you the full draft lifecycle — create, update, send, delete — across every major email provider, with a consistent interface at every layer of the stack.
If you're building any workflow where an email needs to pause before it sends — whether that's human review, AI approval, or simple scheduled delivery — the Nylas draft resource is the most direct path to a provider-agnostic implementation.