nextmail.subscriptions
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
The newsletters and mailing lists the mailbox receives: list them by sender or by domain, unsubscribe, and move what they send.
subscriptions.list()
List subscriptions
def list( *, status: SubscriptionStatus | None = None, q: str | None = None, sort: SubscriptionSort | None = None, suggested: bool | None = None, limit: int | None = None, offset: int | None = None, address: str | None = None, api_key: str | None = None, timeout: float | None = None,) -> SubscriptionListResourceReturns the newsletters and mailing lists the mailbox receives, as the Subscriptions page of the app shows them: one row per sender and the address it writes to, found from the List-Unsubscribe header of the mail it sends. Each row says how much mail the sender sent, how much of it is unread, readPercent (the share of it you read, 0 to 100) and how much arrived in the last 30 days, how it lets you unsubscribe, and the rule that keeps moving its new mail when there is one.
suggested marks an active sender worth leaving: it can be unsubscribed, sent at least 5 emails, wrote in the last 30 days and has 10% or less of its mail read. suggested set to True lists only those.
status is active, the default, kept for the ones you chose to keep with keep, or unsubscribed. q searches the sender, and sort is recent, most, emails (most mail overall), read (least read first), unread or name. Paging is by offset: total counts every match and hasMore says whether another page follows.
A key limited to particular addresses lists only the subscriptions delivered to them, and address narrows the list to one address.
Parameters
statusSubscriptionStatusactive,keptorunsubscribed. Defaults toactive.qstrSearches the sender name and address.
sortSubscriptionSortrecent,most,emails,read,unreadorname. Defaults torecent.suggestedboolTruelists only the senders worth unsubscribing from, the rows whosesuggestedisTrue.limitintRows per page, 1 to 200, defaulting to 50.
offsetintHow many rows to skip.
addressstrOnly the subscriptions delivered to this address.
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SubscriptionListResource with object set to 'list', the rows in data, total, counts and hasMore, where counts holds how many are active, kept and unsubscribed.
Example
from nextmail import nextmail page = nextmail.subscriptions.list(sort='emails', limit=20) for row in page['data']: print(row['senderEmail'], row['total'], f'{row["readPercent"]}% read', row['suggested'])Notes
Read only, so the SDK retries it after a network failure like any other read.
Also available in
subscriptions.list_domains()
List subscriptions by domain
def list_domains( *, status: SubscriptionStatus | None = None, q: str | None = None, sort: SubscriptionSort | None = None, suggested: bool | None = None, limit: int | None = None, offset: int | None = None, address: str | None = None, api_key: str | None = None, timeout: float | None = None,) -> SubscriptionDomainListResourceReturns the same subscriptions as list, one row per sender domain with the counts of its senders added up, so a company that writes from several addresses is one row. unsubscribable counts the senders on the domain that can be unsubscribed without a person opening a page, which is what unsubscribe_domain acts on, and readPercent is the share of the domain's mail you read.
It takes the same filters as list, and suggested set to True lists the domains of the suggested senders.
Parameters
statusSubscriptionStatusactive,keptorunsubscribed. Defaults toactive.qstrSearches the sender name and address.
sortSubscriptionSortrecent,most,emails,read,unreadorname. Defaults torecent.suggestedboolTruelists only the senders worth unsubscribing from, the rows whosesuggestedisTrue.limitintRows per page, 1 to 200, defaulting to 50.
offsetintHow many rows to skip.
addressstrOnly the subscriptions delivered to this address.
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SubscriptionDomainListResource with object set to 'list', the domains in data, total, counts and hasMore.
Example
from nextmail import nextmail page = nextmail.subscriptions.list_domains(sort='most') for row in page['data']: print(row['domain'], row['senders'], row['unsubscribable'])Notes
Read only, so the SDK retries it after a network failure like any other read.
Also available in
subscriptions.keep()
Keep subscriptions you want
def keep( ids: Sequence[str], body: SubscriptionKeep | None = None, *, api_key: str | None = None, timeout: float | None = None,) -> SubscriptionBatchKeepResourceMarks active subscriptions as ones you want, as Keep on the Subscriptions page does: they move from active to kept, are never suggested again and are left alone by unsubscribe_domain. kept set to False puts kept subscriptions back to active.
updated holds the subscriptions that changed. A subscription already in that state, or one you unsubscribed from, comes back in skipped, and an id that is unknown or delivered to an address the key does not reach in missing.
Parameters
idsSequence[str]RequiredA list of 1 to 100 subscription ids from
list. A repeated id counts once.body['kept']boolTruekeeps them,Falseputs them back to active. Defaults toTrue.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SubscriptionBatchKeepResource with object set to 'subscription_batch_keep', kept, updated, skipped and missing, each list holding subscription ids.
Example
from nextmail import nextmail result = nextmail.subscriptions.keep(['sub_7d2c1f0a9b3e4c5d6e7f8a9b']) print(len(result['updated']), 'kept')Notes
The SDK retries it after a network failure, which is safe because keeping a kept subscription changes nothing.
Also available in
subscriptions.unsubscribe()
Unsubscribe from a sender
def unsubscribe( id: str, body: SubscriptionUnsubscribe | None = None, *, api_key: str | None = None, timeout: float | None = None,) -> UnsubscribeResultResourceUnsubscribes the way the sender asks for it: a one-click request to its unsubscribe address when it offers one, otherwise an unsubscribe email sent from the address the mail arrived at. A sender that only offers a page cannot be unsubscribed by a program, so method is link and url is the page a person has to open. bin also moves every conversation from the sender to the Bin, and archive archives them instead. bin wins when both are True.
A sender that gives no way to unsubscribe is a 422 unsubscribe_unsupported, and one whose one-click request failed with no address to write to is a 502 unsubscribe_refused. A subscription delivered to an address the key does not reach is a 404.
Parameters
idstrRequiredThe subscription, from
list.body['bin']boolTruealso moves every conversation from the sender to the Bin. Defaults toFalse.body['archive']boolTruealso archives every conversation from the sender. Defaults toFalse.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
UnsubscribeResultResource with object set to 'unsubscribe', subscriptionId, method, url, binned, the number of conversations moved to the Bin, and archived, the number archived.
Example
from nextmail import nextmail result = nextmail.subscriptions.unsubscribe('sub_7d2c1f0a9b3e4c5d6e7f8a9b', {'bin': True}) if result['method'] == 'link': print('Open', result['url'])else: print('Unsubscribed, moved', result['binned'], 'conversations to the Bin')Notes
The SDK does not retry it, because a second call can send a second unsubscribe email.
Also available in
subscriptions.unsubscribe_many()
Unsubscribe from up to 100 senders in one call
def unsubscribe_many( ids: Sequence[str], body: SubscriptionUnsubscribe | None = None, *, api_key: str | None = None, timeout: float | None = None,) -> SubscriptionBatchUnsubscribeResourceUnsubscribes from each subscription in ids the way unsubscribe does for one, as Unsubscribe on a selection of the Subscriptions page does, and reports the rest instead of failing. unsubscribed holds the ones done with a one-click request or an unsubscribe email.
A sender that only unsubscribes on its own page comes back in links with the url a person has to open, and stays active until somebody does. skipped holds the ones already unsubscribed (already_unsubscribed) or that give no way to unsubscribe (no_method), 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.
archive also archives every conversation from the senders that were unsubscribed, and bin moves them to the Bin instead.
Parameters
idsSequence[str]RequiredA list of 1 to 100 subscription ids from
list, for example the rows whosesuggestedisTrue. A repeated id counts once.body['archive']boolTruealso archives every conversation from the senders. Defaults toFalse.body['bin']boolTruealso moves every conversation from the senders to the Bin. Defaults toFalse.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SubscriptionBatchUnsubscribeResource with object set to 'subscription_batch_unsubscribe', unsubscribed, links, skipped, failed, missing, binned and archived. Each entry of links is a dict with id and url, and each entry of skipped a dict with id and reason.
Example
from nextmail import nextmail page = nextmail.subscriptions.list(suggested=True)result = nextmail.subscriptions.unsubscribe_many( [row['id'] for row in page['data']], {'archive': True}) print(f'{len(result["unsubscribed"])} unsubscribed, {result["archived"]} archived') for step in result['links']: print('Open', step['url'])Notes
A partial result returns rather than raises, so read
links,skipped,failedandmissingto see what stayed.The SDK does not retry it, because a second call can send unsubscribe emails again.
Also available in
- API
POST /subscriptions/batch-unsubscribe- TypeScript
nextmail.subscriptions.unsubscribeMany()- Ruby
subscriptions.unsubscribe_many- PHP
subscriptions->unsubscribeMany- Go
Subscriptions.UnsubscribeMany- Java
subscriptions().unsubscribeMany- C#
Subscriptions.UnsubscribeManyAsync- CLI
nextmail subscriptions unsubscribe-many
subscriptions.unsubscribe_domain()
Unsubscribe from a whole domain
def unsubscribe_domain( domain: str, body: SubscriptionDomainUnsubscribe | None = None, *, api_key: str | None = None, timeout: float | None = None,) -> DomainUnsubscribeResultResourceUnsubscribes from every sender on a domain that can be unsubscribed without a person opening a page, with a one-click request or an unsubscribe email, as the domain view of the Subscriptions page does. unsubscribed counts the senders it worked for, skipped the senders that only offer a page and failed the ones that did not accept it.
Senders you kept with keep are left alone. bin also moves their conversations to the Bin, archive archives them instead, and address keeps it to the subscriptions delivered to one address. A key limited to particular addresses acts only on the subscriptions delivered to them.
Parameters
domainstrRequiredThe sender domain, from
list_domains.body['bin']boolTruealso moves the conversations to the Bin. Defaults toFalse.body['archive']boolTruealso archives the conversations. Defaults toFalse.body['address']strOnly the subscriptions delivered to this address.
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
DomainUnsubscribeResultResource with object set to 'domain_unsubscribe', domain, unsubscribed, skipped, failed, binned and archived.
Example
from nextmail import nextmail result = nextmail.subscriptions.unsubscribe_domain('news.acme.com') print(f'{result["unsubscribed"]} unsubscribed, {result["skipped"]} need a person')Notes
The SDK does not retry it, because a second call can send unsubscribe emails again.
Also available in
- API
POST /subscriptions/domains/{domain}/unsubscribe- TypeScript
nextmail.subscriptions.unsubscribeDomain()- Ruby
subscriptions.unsubscribe_domain- PHP
subscriptions->unsubscribeDomain- Go
Subscriptions.UnsubscribeDomain- Java
subscriptions().unsubscribeDomain- C#
Subscriptions.UnsubscribeDomainAsync- CLI
nextmail subscriptions unsubscribe-domain
subscriptions.move()
Move what a sender sent
def move( id: str, body: SubscriptionMove, *, api_key: str | None = None, timeout: float | None = None,) -> SubscriptionMoveResultResourceMoves every conversation from the sender to the archive, the Bin or a label, as the Subscriptions page does. destination is archive, bin or label, and label needs labelId, or the call is a 422 label_not_found.
With future set to True, the default, a rule keeps doing it to new mail from the sender to that address, which also needs rules:write. ruleName names that rule. future set to False drops a rule made that way before, when the key holds rules:write.
Parameters
idstrRequiredThe subscription, from
list.body['destination']SubscriptionDestinationRequiredarchive,binorlabel.body['labelId']str | NoneThe label to file under, for
label.body['future']boolKeep doing it to new mail with a rule. Defaults to
True.body['ruleName']str | NoneA name for that rule.
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SubscriptionMoveResultResource with object set to 'subscription_move', subscriptionId, moved and ruleId.
Example
from nextmail import nextmail result = nextmail.subscriptions.move( 'sub_7d2c1f0a9b3e4c5d6e7f8a9b', {'destination': 'archive', 'ruleName': 'Archive Acme news'}) print(result['moved'], result['ruleId'])Notes
The SDK retries it after a network failure, which is safe because moving the same mail again changes nothing and the rule is updated rather than added twice.
Also available in
subscriptions.move_many()
Move what up to 100 senders sent
def move_many( ids: Sequence[str], body: SubscriptionMoveMany, *, api_key: str | None = None, timeout: float | None = None,) -> SubscriptionBatchMoveResourceMoves every conversation from each subscription in ids to the archive, the Bin or a label, the way move does for one, as Archive on a selection of the Subscriptions page does. destination is archive, bin or label, and label needs labelId, or the call is a 422 label_not_found.
With future set to True, the default, a rule per sender keeps doing it to new mail, which also needs rules:write. moved counts the conversations moved across every sender, updated holds the subscriptions whose mail moved, failed the ones that could not be moved and missing the ids that are unknown or delivered to an address the key does not reach.
Parameters
idsSequence[str]RequiredA list of 1 to 100 subscription ids from
list. A repeated id counts once.body['destination']SubscriptionDestinationRequiredarchive,binorlabel.body['labelId']str | NoneThe label to file under, for
label.body['future']boolKeep doing it to new mail with a rule per sender. Defaults to
True.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SubscriptionBatchMoveResource with object set to 'subscription_batch_move', moved, updated, failed and missing.
Example
from nextmail import nextmail result = nextmail.subscriptions.move_many( ['sub_7d2c1f0a9b3e4c5d6e7f8a9b', 'sub_0c3e2a91d4b7f6058e1a2b3c'], {'destination': 'archive', 'future': False},) print(result['moved'], 'conversations archived')Notes
The SDK retries it after a network failure, which is safe because moving the same mail again changes nothing and each rule is updated rather than added twice.
Google Workspace
Fastmail