--- title: "nextmail subscriptions" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://nextmail.sh/docs/cli/reference/subscriptions" area: "CLI" category: "Reference" --- # nextmail subscriptions Every command in this namespace, with its arguments, flags and examples. ## Commands ### `nextmail subscriptions list` List subscriptions ```bash nextmail subscriptions list [flags] ``` Resolves 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: 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. - Scopes: `threads:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--status ` (default `"active"`): `active`, `kept` or `unsubscribed`. Defaults to `active`. - `--q `: Searches the sender name and address. - `--sort ` (default `"recent"`): `recent`, `most`, `emails`, `read`, `unread` or `name`. Defaults to `recent`. - `--suggested`: Only the senders worth unsubscribing from, the rows whose `suggested` is true. - `--limit ` (default `50`): Rows per page, 1 to 200, defaulting to 50. - `--offset ` (default `0`): How many rows to skip. - `--address `: Only the subscriptions delivered to this address. **Examples** ```bash nextmail subscriptions list ``` With optional flags ```bash nextmail subscriptions list --sort emails --limit 20 ``` Print the raw JSON ```bash nextmail subscriptions list --json ``` Also available in: API [`GET /subscriptions`](https://nextmail.sh/docs/api/reference/subscriptions#get-subscriptions); TypeScript [`nextmail.subscriptions.list()`](https://nextmail.sh/docs/sdk/reference/subscriptions#list); Python [`subscriptions.list()`](https://nextmail.sh/docs/python/reference/subscriptions#list); Ruby [`subscriptions.list`](https://nextmail.sh/docs/ruby/reference/subscriptions#list); PHP [`subscriptions->list`](https://nextmail.sh/docs/php/reference/subscriptions#list); Go [`Subscriptions.List`](https://nextmail.sh/docs/go/reference/subscriptions#list); Java [`subscriptions().list`](https://nextmail.sh/docs/java/reference/subscriptions#list); C# [`Subscriptions.ListAsync`](https://nextmail.sh/docs/csharp/reference/subscriptions#list). ### `nextmail subscriptions list-domains` List subscriptions by domain ```bash nextmail subscriptions list-domains [flags] ``` Resolves 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 `unsubscribeDomain` acts on, and `readPercent` is the share of the domain's mail you read. It takes the same filters as `list`, and `suggested: true` lists the domains of the suggested senders. - Scopes: `threads:read`. - Needs a sign-in. **Flags** - `--status ` (default `"active"`): `active`, `kept` or `unsubscribed`. Defaults to `active`. - `--q `: Searches the sender name and address. - `--sort ` (default `"recent"`): `recent`, `most`, `emails`, `read`, `unread` or `name`. Defaults to `recent`. - `--suggested`: Only the senders worth unsubscribing from, the rows whose `suggested` is true. - `--limit ` (default `50`): Rows per page, 1 to 200, defaulting to 50. - `--offset ` (default `0`): How many rows to skip. - `--address `: Only the subscriptions delivered to this address. **Examples** ```bash nextmail subscriptions list-domains ``` With optional flags ```bash nextmail subscriptions list-domains --sort most ``` Print the raw JSON ```bash nextmail subscriptions list-domains --json ``` Also available in: API [`GET /subscriptions/domains`](https://nextmail.sh/docs/api/reference/subscriptions#get-subscriptions-domains); TypeScript [`nextmail.subscriptions.listDomains()`](https://nextmail.sh/docs/sdk/reference/subscriptions#listDomains); Python [`subscriptions.list_domains()`](https://nextmail.sh/docs/python/reference/subscriptions#listDomains); Ruby [`subscriptions.list_domains`](https://nextmail.sh/docs/ruby/reference/subscriptions#listDomains); PHP [`subscriptions->listDomains`](https://nextmail.sh/docs/php/reference/subscriptions#listDomains); Go [`Subscriptions.ListDomains`](https://nextmail.sh/docs/go/reference/subscriptions#listDomains); Java [`subscriptions().listDomains`](https://nextmail.sh/docs/java/reference/subscriptions#listDomains); C# [`Subscriptions.ListDomainsAsync`](https://nextmail.sh/docs/csharp/reference/subscriptions#listDomains). ### `nextmail subscriptions keep` Keep subscriptions you want ```bash nextmail subscriptions keep [flags] ``` Marks 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 `unsubscribeDomain`. `kept: 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`. - Scopes: `threads:write`. - Needs a sign-in. **Arguments** - `` (required): 1 to 100 subscription ids from `list`. A repeated id counts once. **Flags** - `--kept` (default `true`): `true` keeps them, `false` puts them back to active. Defaults to true. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash nextmail subscriptions keep sub_7d2c1f0a9b3e4c5d6e7f8a9b ``` Print the raw JSON ```bash nextmail subscriptions keep sub_7d2c1f0a9b3e4c5d6e7f8a9b --json ``` Also available in: API [`POST /subscriptions/batch-keep`](https://nextmail.sh/docs/api/reference/subscriptions#post-subscriptions-batch-keep); TypeScript [`nextmail.subscriptions.keep()`](https://nextmail.sh/docs/sdk/reference/subscriptions#keep); Python [`subscriptions.keep()`](https://nextmail.sh/docs/python/reference/subscriptions#keep); Ruby [`subscriptions.keep`](https://nextmail.sh/docs/ruby/reference/subscriptions#keep); PHP [`subscriptions->keep`](https://nextmail.sh/docs/php/reference/subscriptions#keep); Go [`Subscriptions.Keep`](https://nextmail.sh/docs/go/reference/subscriptions#keep); Java [`subscriptions().keep`](https://nextmail.sh/docs/java/reference/subscriptions#keep); C# [`Subscriptions.KeepAsync`](https://nextmail.sh/docs/csharp/reference/subscriptions#keep). ### `nextmail subscriptions unsubscribe` Unsubscribe from a sender ```bash nextmail subscriptions unsubscribe [flags] ``` Unsubscribes 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. - Scopes: `threads:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): The subscription, from `list`. **Flags** - `--bin` (default `false`): Also move every conversation from the sender to the Bin. Defaults to false. - `--archive` (default `false`): Also archive every conversation from the sender. Defaults to false. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail subscriptions unsubscribe sub_7d2c1f0a9b3e4c5d6e7f8a9b ``` With optional flags ```bash nextmail subscriptions unsubscribe sub_7d2c1f0a9b3e4c5d6e7f8a9b --bin ``` Skip the confirmation, for scripts ```bash nextmail subscriptions unsubscribe sub_7d2c1f0a9b3e4c5d6e7f8a9b --yes ``` Also available in: API [`POST /subscriptions/{id}/unsubscribe`](https://nextmail.sh/docs/api/reference/subscriptions#post-subscriptions-id-unsubscribe); TypeScript [`nextmail.subscriptions.unsubscribe()`](https://nextmail.sh/docs/sdk/reference/subscriptions#unsubscribe); Python [`subscriptions.unsubscribe()`](https://nextmail.sh/docs/python/reference/subscriptions#unsubscribe); Ruby [`subscriptions.unsubscribe`](https://nextmail.sh/docs/ruby/reference/subscriptions#unsubscribe); PHP [`subscriptions->unsubscribe`](https://nextmail.sh/docs/php/reference/subscriptions#unsubscribe); Go [`Subscriptions.Unsubscribe`](https://nextmail.sh/docs/go/reference/subscriptions#unsubscribe); Java [`subscriptions().unsubscribe`](https://nextmail.sh/docs/java/reference/subscriptions#unsubscribe); C# [`Subscriptions.UnsubscribeAsync`](https://nextmail.sh/docs/csharp/reference/subscriptions#unsubscribe). ### `nextmail subscriptions unsubscribe-many` Unsubscribe from up to 100 senders in one call ```bash nextmail subscriptions unsubscribe-many [flags] ``` Unsubscribes 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. - Scopes: `threads:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): 1 to 100 subscription ids from `list`, for example the rows whose `suggested` is true. A repeated id counts once. **Flags** - `--archive` (default `false`): Also archive every conversation from the senders. Defaults to false. - `--bin` (default `false`): Also move every conversation from the senders to the Bin. Defaults to false. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail subscriptions unsubscribe-many sub_7d2c1f0a9b3e4c5d6e7f8a9b ``` With optional flags ```bash nextmail subscriptions unsubscribe-many sub_7d2c1f0a9b3e4c5d6e7f8a9b --archive ``` Skip the confirmation, for scripts ```bash nextmail subscriptions unsubscribe-many sub_7d2c1f0a9b3e4c5d6e7f8a9b --yes ``` Also available in: API [`POST /subscriptions/batch-unsubscribe`](https://nextmail.sh/docs/api/reference/subscriptions#post-subscriptions-batch-unsubscribe); TypeScript [`nextmail.subscriptions.unsubscribeMany()`](https://nextmail.sh/docs/sdk/reference/subscriptions#unsubscribeMany); Python [`subscriptions.unsubscribe_many()`](https://nextmail.sh/docs/python/reference/subscriptions#unsubscribeMany); Ruby [`subscriptions.unsubscribe_many`](https://nextmail.sh/docs/ruby/reference/subscriptions#unsubscribeMany); PHP [`subscriptions->unsubscribeMany`](https://nextmail.sh/docs/php/reference/subscriptions#unsubscribeMany); Go [`Subscriptions.UnsubscribeMany`](https://nextmail.sh/docs/go/reference/subscriptions#unsubscribeMany); Java [`subscriptions().unsubscribeMany`](https://nextmail.sh/docs/java/reference/subscriptions#unsubscribeMany); C# [`Subscriptions.UnsubscribeManyAsync`](https://nextmail.sh/docs/csharp/reference/subscriptions#unsubscribeMany). ### `nextmail subscriptions unsubscribe-domain` Unsubscribe from a whole domain ```bash nextmail subscriptions unsubscribe-domain [flags] ``` Unsubscribes 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. - Scopes: `threads:write`. - Needs a sign-in. - Asks you to confirm. **Arguments** - `` (required): The sender domain, from `listDomains`. **Flags** - `--bin` (default `false`): Also move the conversations to the Bin. Defaults to false. - `--archive` (default `false`): Also archive the conversations. Defaults to false. - `--address `: Only the subscriptions delivered to this address. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash nextmail subscriptions unsubscribe-domain news.acme.com ``` Skip the confirmation, for scripts ```bash nextmail subscriptions unsubscribe-domain news.acme.com --yes ``` Also available in: API [`POST /subscriptions/domains/{domain}/unsubscribe`](https://nextmail.sh/docs/api/reference/subscriptions#post-subscriptions-domains-domain-unsubscribe); TypeScript [`nextmail.subscriptions.unsubscribeDomain()`](https://nextmail.sh/docs/sdk/reference/subscriptions#unsubscribeDomain); Python [`subscriptions.unsubscribe_domain()`](https://nextmail.sh/docs/python/reference/subscriptions#unsubscribeDomain); Ruby [`subscriptions.unsubscribe_domain`](https://nextmail.sh/docs/ruby/reference/subscriptions#unsubscribeDomain); PHP [`subscriptions->unsubscribeDomain`](https://nextmail.sh/docs/php/reference/subscriptions#unsubscribeDomain); Go [`Subscriptions.UnsubscribeDomain`](https://nextmail.sh/docs/go/reference/subscriptions#unsubscribeDomain); Java [`subscriptions().unsubscribeDomain`](https://nextmail.sh/docs/java/reference/subscriptions#unsubscribeDomain); C# [`Subscriptions.UnsubscribeDomainAsync`](https://nextmail.sh/docs/csharp/reference/subscriptions#unsubscribeDomain). ### `nextmail subscriptions move` Move what a sender sent ```bash nextmail subscriptions move --destination [flags] nextmail subscriptions move --data [flags] ``` Moves 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 `--label-id`, or the call is a 422 `label_not_found`. With `future`, the default, a rule keeps doing it to new mail from the sender to that address, which also needs `rules:write`. `--rule-name` names that rule. `future: false` drops a rule made that way before, when the key holds `rules:write`. - Scopes: `threads:write`. - Needs a sign-in. **Arguments** - `` (required): The subscription, from `list`. **Flags** - `--destination `: `archive`, `bin` or `label`. Required, here or in `--data`. - `--label-id `: The label to file under, for `label`. - `--future` (default `true`): Keep doing it to new mail with a rule. Defaults to true. - `--rule-name `: A name for that rule. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash nextmail subscriptions move sub_7d2c1f0a9b3e4c5d6e7f8a9b --destination archive ``` Read the whole body from a JSON file ```bash nextmail subscriptions move sub_7d2c1f0a9b3e4c5d6e7f8a9b --data @subscriptions.json ``` Also available in: API [`POST /subscriptions/{id}/move`](https://nextmail.sh/docs/api/reference/subscriptions#post-subscriptions-id-move); TypeScript [`nextmail.subscriptions.move()`](https://nextmail.sh/docs/sdk/reference/subscriptions#move); Python [`subscriptions.move()`](https://nextmail.sh/docs/python/reference/subscriptions#move); Ruby [`subscriptions.move`](https://nextmail.sh/docs/ruby/reference/subscriptions#move); PHP [`subscriptions->move`](https://nextmail.sh/docs/php/reference/subscriptions#move); Go [`Subscriptions.Move`](https://nextmail.sh/docs/go/reference/subscriptions#move); Java [`subscriptions().move`](https://nextmail.sh/docs/java/reference/subscriptions#move); C# [`Subscriptions.MoveAsync`](https://nextmail.sh/docs/csharp/reference/subscriptions#move). ### `nextmail subscriptions move-many` Move what up to 100 senders sent ```bash nextmail subscriptions move-many --destination [flags] nextmail subscriptions move-many --data [flags] ``` Moves 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 `--label-id`, or the call is a 422 `label_not_found`. With `future`, 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. - Scopes: `threads:write`. - Needs a sign-in. **Arguments** - `` (required): 1 to 100 subscription ids from `list`. A repeated id counts once. **Flags** - `--destination `: `archive`, `bin` or `label`. Required, here or in `--data`. - `--label-id `: The label to file under, for `label`. - `--future` (default `true`): Keep doing it to new mail with a rule per sender. Defaults to true. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** The required values only ```bash nextmail subscriptions move-many sub_7d2c1f0a9b3e4c5d6e7f8a9b --destination archive ``` With optional flags ```bash nextmail subscriptions move-many sub_7d2c1f0a9b3e4c5d6e7f8a9b --destination archive --no-future ``` Read the whole body from a JSON file ```bash nextmail subscriptions move-many sub_7d2c1f0a9b3e4c5d6e7f8a9b --data @subscriptions.json ``` Also available in: API [`POST /subscriptions/batch-move`](https://nextmail.sh/docs/api/reference/subscriptions#post-subscriptions-batch-move); TypeScript [`nextmail.subscriptions.moveMany()`](https://nextmail.sh/docs/sdk/reference/subscriptions#moveMany); Python [`subscriptions.move_many()`](https://nextmail.sh/docs/python/reference/subscriptions#moveMany); Ruby [`subscriptions.move_many`](https://nextmail.sh/docs/ruby/reference/subscriptions#moveMany); PHP [`subscriptions->moveMany`](https://nextmail.sh/docs/php/reference/subscriptions#moveMany); Go [`Subscriptions.MoveMany`](https://nextmail.sh/docs/go/reference/subscriptions#moveMany); Java [`subscriptions().moveMany`](https://nextmail.sh/docs/java/reference/subscriptions#moveMany); C# [`Subscriptions.MoveManyAsync`](https://nextmail.sh/docs/csharp/reference/subscriptions#moveMany).