Drafts
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
GET/drafts
List drafts
Requires the drafts:read scope.
Query parameters
querystringThe same search syntax as
GET /threads, read against each draft's subject, sender and the first 4,000 characters of its body. Plain words match loosely and a quoted phrase has to appear as written, filler words are dropped when something else is left to search for, and a value the search cannot use is ignored rather than narrowing. Recipients are not searched, soto:,cc:andbcc:match nothing here. The drafts folder always applies, soin:and folderis:operators cannot widen the search beyond drafts,in:anywhereincluded. A draft saved with no subject is stored as(no subject), sosubject:"no subject"finds it.limitintegerDrafts per page, a whole number from 1 to 100. Defaults to 25.
At least 1At most 100pageTokenstringOpaque. Pass back what you were given, never construct one.
Returns
A page of drafts.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.drafts.list()nextmail.drafts.listAll()nextmail.drafts.iterate()- Python
drafts.list()drafts.list_all()drafts.iterate()- Ruby
drafts.listdrafts.list_alldrafts.iterate- PHP
drafts->listdrafts->listAlldrafts->iterate- Go
Drafts.ListDrafts.ListAllDrafts.Iterate- Java
drafts().listdrafts().listAlldrafts().iterate- C#
Drafts.ListAsyncDrafts.ListAllAsyncDrafts.IterateAsync- CLI
nextmail drafts list- MCP
listDrafts
POST/drafts
Create a draft
Saves a draft without sending it, as the composer does when you close it. Every field is optional, and html wins over text when both are given.
To forward an email, pass threadId and forwardOf, the id of a message in that thread from GET /threads/{id}. The draft takes the names of that message's files and, unless you give a subject, the message's subject with Fwd: in front. Sending it with draftId on POST /emails quotes the message below the body, attaches its files and threads it the way forwarding in the app does. forwardOf without threadId, or naming no message of that thread, is a 422 invalid_parameter.
Requires the drafts:write scope.
Request body
tostring[]Recipient addresses, bare or with a display name.
Default[]ccstring[]Copy recipients, bare or with a display name.
Default[]bccstring[]Blind copy recipients, bare or with a display name.
Default[]subjectstringAt most 998 characters. Empty is stored as
(no subject).Up to 998 charactersDefault""htmlstringBody markup, at most 1,000,000 characters. Kept over
textwhen both are set.Up to 1000000 characterstextstringBody used only when
htmlis absent, at most 1,000,000 characters. Stored as is and read back inhtml.Up to 1000000 charactersfromstringThe address it will be sent from. A key or an app limited to particular addresses has to name one of them, and one it may send as.
threadIdstringThe conversation it replies to, when it is a reply, or the one holding the message
forwardOfnames.forwardOfstringThe id of the message in
threadIdto forward. Sending the draft quotes it below the body and attaches its files.1 to 998 characters
Returns
Created.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
GET/drafts/{id}
Retrieve a draft
Requires the drafts:read scope.
Path parameters
idstringRequiredDraft id, which starts with
draft-.
Returns
The draft.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.drafts.get()- Python
drafts.get()- Ruby
drafts.get- PHP
drafts->get- Go
Drafts.Get- Java
drafts().get- C#
Drafts.GetAsync- CLI
nextmail drafts get- MCP
getDraft
PATCH/drafts/{id}
Update a draft
A partial update, not an upsert. An unknown id, or the id of a thread that is not a draft, is a 404. The draft keeps the id you passed, and the response echoes it. Its attachments stay as they are, and a draft that forwards a message keeps forwarding it unless threadId moves it to another conversation.
Requires the drafts:write scope.
Path parameters
idstringRequiredDraft id, which starts with
draft-.
Request body
tostring[]Replacement recipients. An empty array clears them.
ccstring[]Replacement copy recipients.
bccstring[]Replacement blind copy recipients.
subjectstringReplacement subject, at most 998 characters.
Up to 998 charactershtmlstringReplacement body markup, at most 1,000,000 characters.
Up to 1000000 characterstextstringReplacement body used only when
htmlis absent.Up to 1000000 charactersfromstringThe address it will be sent from, or null to clear it. A key or an app limited to particular addresses has to name one of them.
Can be nullthreadIdstringThe conversation it replies to.
Returns
Saved.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
DELETE/drafts/{id}
Delete a draft
Requires the drafts:write scope.
Path parameters
idstringRequiredDraft id, which starts with
draft-.
Returns
Deleted.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.drafts.delete()- Python
drafts.delete()- Ruby
drafts.delete- PHP
drafts->delete- Go
Drafts.Delete- Java
drafts().delete- C#
Drafts.DeleteAsync- CLI
nextmail drafts delete- MCP
deleteDraft
Objects
DeletedDraftobject
objectstringRequired- One of
"draft" idstringRequireddeletedbooleanRequired- One of
true
Draftobject
objectstringRequired- One of
"draft" idstringRequiredtostring[]Requiredccstring[]Requiredbccstring[]RequiredsubjectstringRequiredhtmlstringRequiredThe body as saved.
threadIdstringRequiredThe conversation it replies to, when it is a reply.
Can be nullforwardOfstringRequiredThe message in
threadIdthis draft forwards, or null. Sending the draft quotes that message below the body and attaches its files, one for each file the draft lists.Can be nullfromstringRequiredThe sending address. Null when none is set or it is not one this workspace can send as.
Can be nullattachmentsobject[]RequiredfilenamestringRequired- Can be null
contentTypestringRequired- Can be null
sizeintegerRequiredSize in bytes, when known.
Can be null
DraftListobject
objectstringRequired- One of
"list" dataDraftReference[]RequirednextPageTokenstringRequiredPass it back as
pageTokenfor the next page. Null on the last page.Can be null
DraftReferenceobject
objectstringRequired- One of
"draft" idstringRequired
Google Workspace
Fastmail