Subscriptions
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
Newsletters and mailing lists the mailbox receives, found from the List-Unsubscribe header of the mail they send, as the Subscriptions page of the app shows them, with how much of their mail you read and which ones you rarely open. Keep the ones you want, unsubscribe from one sender, many at once or a whole domain, or move what they sent and keep moving what they send.
GET/subscriptions
List subscriptions
One row per sender and address it writes to, with how much mail it sent, how much of it is unread, what share of it you read and how much arrived in the last 30 days. suggested marks an active sender you rarely read: one that can be unsubscribed, sent at least 5 emails, wrote in the last 30 days and has 10% or less of its mail read. A key or an app limited to particular addresses lists only the subscriptions delivered to them.
Requires the threads:read scope.
Query parameters
statusstringactivelists what still arrives,keptthe ones you chose to keep,unsubscribedwhat you left.One of"active""kept""unsubscribed"Default"active"qstringSearches the sender name and address.
Up to 200 characterssortstringrecentputs the newest mail first,mostthe senders with the most mail lately,emailsthe most mail overall,readthe least read first,unreadthose with the most unread,namesorts by sender.One of"recent""most""emails""read""unread""name"Default"recent"suggestedbooleanOnly the senders worth unsubscribing from: active, rarely read and still writing.
limitintegerRows per page.
At least 1At most 200Default50offsetintegerHow many rows to skip, for the next page.
At least 0Default0addressstringOnly the subscriptions delivered to this address. One the key does not reach lists nothing.
3 to 320 characters
Returns
A page of subscriptions.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
GET/subscriptions/domains
List subscriptions by domain
The same subscriptions, one row per sender domain with the counts of its senders added up, so a company that writes from several addresses is one row.
Requires the threads:read scope.
Query parameters
statusstringactivelists what still arrives,keptthe ones you chose to keep,unsubscribedwhat you left.One of"active""kept""unsubscribed"Default"active"qstringSearches the sender name and address.
Up to 200 characterssortstringrecentputs the newest mail first,mostthe senders with the most mail lately,emailsthe most mail overall,readthe least read first,unreadthose with the most unread,namesorts by sender.One of"recent""most""emails""read""unread""name"Default"recent"suggestedbooleanOnly the senders worth unsubscribing from: active, rarely read and still writing.
limitintegerRows per page.
At least 1At most 200Default50offsetintegerHow many rows to skip, for the next page.
At least 0Default0addressstringOnly the subscriptions delivered to this address. One the key does not reach lists nothing.
3 to 320 characters
Returns
A page of sender domains.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
POST/subscriptions/domains/{domain}/unsubscribe
Unsubscribe from a whole domain
Unsubscribes from every sender on the domain that can be unsubscribed without a person opening a page, with one-click or by email. skipped counts the senders that only offer a page, and failed the ones that did not accept it. Unsubscribing works the way the sender asks for it: a one-click request to its unsubscribe address when it offers one, an unsubscribe email from the address the mail arrived at when it gives a mailto, and otherwise the sender's own unsubscribe page in url, which a person has to open. method says which.
Requires the threads:write scope.
Path parameters
domainstringRequiredThe sender domain, as
GET /subscriptions/domainsreturns it.
Request body
binbooleanAlso move every conversation from the senders to the Bin.
DefaultfalsearchivebooleanAlso archive every conversation from the senders.
binwins when both are true.DefaultfalseaddressstringOnly the subscriptions delivered to this address.
3 to 320 characters
Returns
What happened to each sender, counted.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.subscriptions.unsubscribeDomain()- Python
subscriptions.unsubscribe_domain()- Ruby
subscriptions.unsubscribe_domain- PHP
subscriptions->unsubscribeDomain- Go
Subscriptions.UnsubscribeDomain- Java
subscriptions().unsubscribeDomain- C#
Subscriptions.UnsubscribeDomainAsync- CLI
nextmail subscriptions unsubscribe-domain- MCP
unsubscribeSubscriptionDomain
POST/subscriptions/{id}/unsubscribe
Unsubscribe from a sender
Unsubscribing works the way the sender asks for it: a one-click request to its unsubscribe address when it offers one, an unsubscribe email from the address the mail arrived at when it gives a mailto, and otherwise the sender's own unsubscribe page in url, which a person has to open. method says which. With bin, every conversation from the sender also moves to the Bin, and with archive to the archive.
Requires the threads:write scope.
Path parameters
idstringRequiredThe subscription, as
GET /subscriptionsreturns it.
Request body
binbooleanAlso move every conversation from the sender to the Bin.
DefaultfalsearchivebooleanAlso archive every conversation from the sender.
binwins when both are true.Defaultfalse
Returns
How it was unsubscribed.
Errors
- 422
unsubscribe_unsupported: the sender gives no way to unsubscribe.- 502
unsubscribe_refused: the sender did not accept the one-click request and gives no address to write to.
The errors every operation can return400401403404429500Error catalog
Also available in
POST/subscriptions/batch-unsubscribe
Unsubscribe from several senders
Unsubscribes from each subscription in ids that can be unsubscribed without a person, with one-click or by email, and lists the rest. links holds the senders that only unsubscribe on their own page, with the page a person has to open; they stay active until somebody does. skipped holds the ones already unsubscribed or that give no way to unsubscribe, failed the ones whose sender did not accept it and missing the ids that are unknown or delivered to an address the key does not reach. With archive or bin, every conversation from the senders that were unsubscribed also moves. Unsubscribing works the way the sender asks for it: a one-click request to its unsubscribe address when it offers one, an unsubscribe email from the address the mail arrived at when it gives a mailto, and otherwise the sender's own unsubscribe page in url, which a person has to open. method says which.
Requires the threads:write scope.
Request body
idsstring[]Required1 to 100 subscription ids from
GET /subscriptions. A repeated id counts once.1 to 100 itemsbinbooleanAlso move every conversation from the senders to the Bin.
DefaultfalsearchivebooleanAlso archive every conversation from the senders.
binwins when both are true.Defaultfalse
Returns
What happened to each subscription.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.subscriptions.unsubscribeMany()- Python
subscriptions.unsubscribe_many()- Ruby
subscriptions.unsubscribe_many- PHP
subscriptions->unsubscribeMany- Go
Subscriptions.UnsubscribeMany- Java
subscriptions().unsubscribeMany- C#
Subscriptions.UnsubscribeManyAsync- CLI
nextmail subscriptions unsubscribe-many- MCP
unsubscribeSubscriptions
POST/subscriptions/batch-keep
Keep subscriptions
Marks active subscriptions as ones you want, so they move to kept and are never suggested again. kept: false puts kept subscriptions back to active. A subscription you unsubscribed from stays as it is and is listed in skipped.
Requires the threads:write scope.
Request body
idsstring[]Required1 to 100 subscription ids from
GET /subscriptions. A repeated id counts once.1 to 100 itemskeptbooleantruekeeps active subscriptions,falseputs kept ones back to active.Defaulttrue
Returns
Which subscriptions changed.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
POST/subscriptions/batch-move
Move what several senders sent
Moves every conversation from each subscription in ids to the archive, the Bin or a label, as POST /subscriptions/{id}/move does for one. With future, the default, a rule per sender keeps doing it to new mail, which also needs rules:write.
Requires the threads:write scope.
Request body
idsstring[]Required1 to 100 subscription ids from
GET /subscriptions. A repeated id counts once.1 to 100 itemsdestinationstringRequiredarchive,binorlabel.One of"archive""bin""label"labelIdstringThe label to file under when
destinationislabel.Can be null1 to 200 charactersfuturebooleanAlso keep doing it to new mail from each sender, with a rule. Needs
rules:write.Defaulttrue
Returns
How many conversations moved, and for which subscriptions.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
POST/subscriptions/{id}/move
Move what a sender sent
Moves every conversation from the sender to the archive, the Bin or a label. With future, the default, a rule keeps doing it to new mail from the sender to that address, which also needs rules:write. future: false drops a rule made that way before.
Requires the threads:write scope.
Path parameters
idstringRequiredThe subscription, as
GET /subscriptionsreturns it.
Request body
destinationstringRequiredarchive,binorlabel.One of"archive""bin""label"labelIdstringThe label to file under when
destinationislabel.Can be null1 to 200 charactersfuturebooleanAlso keep doing it to new mail from the sender, with a rule. Needs
rules:write.DefaulttrueruleNamestringA name for that rule.
Can be nullUp to 100 characters
Returns
How many conversations moved, and the rule.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
POST/threads/{id}/unsubscribe
Unsubscribe from the sender of a thread
The Unsubscribe button of the reading pane: finds the subscription behind the newest message of the thread that carries a List-Unsubscribe header and unsubscribes from it. Unsubscribing works the way the sender asks for it: a one-click request to its unsubscribe address when it offers one, an unsubscribe email from the address the mail arrived at when it gives a mailto, and otherwise the sender's own unsubscribe page in url, which a person has to open. method says which.
Requires the threads:write scope.
Path parameters
idstringRequiredThe thread, as
GET /threadsreturns it.
Returns
How it was unsubscribed.
Errors
- 422
unsubscribe_unsupported: the sender gives no way to unsubscribe.- 502
unsubscribe_refused: the sender did not accept the one-click request and gives no address to write to.
The errors every operation can return400401403404429500Error catalog
Also available in
Objects
DomainUnsubscribeResultobject
objectstring- One of
"domain_unsubscribe" domainstringunsubscribedintegerskippedintegerSenders that only offer a page.
failedintegerbinnedintegerarchivedinteger
Subscriptionobject
objectstring- One of
"subscription" idstringsenderEmailstringsenderNamestring- Can be null
recipientstringThe address the mail arrives at.
statusstring- One of
"active""kept""unsubscribed" methodstringHow the sender lets you unsubscribe, or null when it gives no way.
Can be nullOne of"one-click""email""link"linkUrlstringIts unsubscribe page, when it has one.
Can be nullunreadintegerrecentintegerMail in the last 30 days.
totalintegerreadPercentintegerThe share of its mail you read, from 0 to 100.
suggestedbooleanAn active sender you rarely read, worth unsubscribing from.
sinceUnsubscribedintegerMail that still arrived after you unsubscribed.
lastSeenAtstring- Format
date-time unsubscribedAtstring- Can be nullFormat
date-time unsubscribedWithstring- Can be nullOne of
"one-click""email""link" futureobjectThe rule that keeps moving its new mail, when there is one.
Can be nullruleIdstringdestinationstring- One of
"archive""bin""label" labelIdstring- Can be null
SubscriptionBatchKeepResultobject
objectstring- One of
"subscription_batch_keep" keptbooleanWhat was asked: keep, or put back to active.
updatedstring[]Subscriptions that changed.
skippedstring[]Subscriptions already in that state, or unsubscribed.
missingstring[]Ids that are unknown or delivered to an address the key does not reach.
SubscriptionBatchMoveResultobject
objectstring- One of
"subscription_batch_move" movedintegerConversations moved, across every sender.
updatedstring[]Subscriptions whose mail moved.
failedstring[]Subscriptions that could not be moved.
missingstring[]Ids that are unknown or delivered to an address the key does not reach.
SubscriptionBatchUnsubscribeResultobject
objectstring- One of
"subscription_batch_unsubscribe" unsubscribedstring[]Subscriptions unsubscribed with one-click or by email.
linksobject[]Senders that only unsubscribe on their own page, which a person has to open.
idstringurlstring
skippedobject[]Subscriptions left as they were, and why.
idstringreasonstring- One of
"already_unsubscribed""no_method"
failedstring[]Subscriptions whose sender did not accept the request.
missingstring[]Ids that are unknown or delivered to an address the key does not reach.
binnedintegerConversations moved to the Bin.
archivedintegerConversations archived.
SubscriptionDomainobject
objectstring- One of
"subscription_domain" domainstringnamestringsampleEmailstringOne sender address on the domain.
sendersintegerunsubscribableintegerSenders that can be unsubscribed without a person opening a page.
unreadintegerrecentintegertotalintegerreadPercentintegerThe share of its mail you read, from 0 to 100.
sinceUnsubscribedintegerlastSeenAtstring- Format
date-time
SubscriptionDomainListobject
objectstring- One of
"list" totalintegercountsobjectactiveintegerkeptintegerunsubscribedinteger
hasMoreboolean
SubscriptionListobject
objectstring- One of
"list" dataSubscription[]totalintegerRows that match, across every page.
countsobjectactiveintegerkeptintegerunsubscribedinteger
hasMoreboolean
SubscriptionMoveResultobject
objectstring- One of
"subscription_move" subscriptionIdstringmovedintegerConversations moved.
ruleIdstringThe rule that keeps moving new mail.
Can be null
UnsubscribeResultobject
objectstring- One of
"unsubscribe" subscriptionIdstringthreadIdstringPresent when it was asked for through a thread.
methodstring- One of
"one-click""email""link" urlstringThe page to open when
methodislink, since that one needs a person.Can be nullbinnedintegerConversations moved to the Bin.
archivedintegerConversations archived.
Google Workspace
Fastmail