---
title: "Subscriptions"
description: "The newsletters and mailing lists the mailbox receives."
url: "https://nextmail.sh/docs/mcp/tools/subscriptions"
area: "MCP server"
category: "Tools"
---

# Subscriptions

The newsletters and mailing lists the mailbox receives.

## Subscriptions tools

| Tool | What it does |
| --- | --- |
| listSubscriptions | The senders of newsletters and mailing lists, one row per sender and the address it writes to, with how much mail each sent, how much of it was read and how it lets you unsubscribe. `suggested` lists only the rarely read ones. |
| listSubscriptionDomains | The same, one row per sender domain, with how many of its senders can be unsubscribed without a person opening a page. |
| unsubscribeSubscription | Unsubscribe from one sender the way it asks for. A sender that only offers a page returns its link for a person to open. |
| unsubscribeSubscriptionDomain | Unsubscribe from every sender on a domain that takes a one-click request or an email, and count the rest. |
| unsubscribeThread | Unsubscribe from the sender of a thread, as the Unsubscribe button of the reading pane does. |
| moveSubscription | Move everything a sender sent to the archive, the Bin or a label, and with `future` keep moving its new mail with a rule. |
| keepSubscriptions | Keep the subscriptions you want, so they are never suggested again, or put them back to active. |
| unsubscribeSubscriptions | Unsubscribe from up to 100 senders at once, and list the ones that only unsubscribe on their own page. |
| moveSubscriptions | Move everything up to 100 senders sent to the archive, the Bin or a label, as `moveSubscription` does for one. |

> Reading needs “Read threads and messages” (`threads:read`), and keeping, unsubscribing and moving need “Label, read and archive threads” (`threads:write`). Keeping new mail moving makes a rule, which also needs “Create, edit and reorder mail rules” (`rules:write`). A client limited to some addresses reaches only the subscriptions delivered to them.

> Unsubscribing sends a request or an email to the sender, and nothing here takes it back. In the app’s chat, `unsubscribeSubscriptionDomain`, `unsubscribeSubscriptions` and `moveSubscriptions` always ask first, and the other changes ask unless you asked for them.

## Reference

### `listSubscriptions`

The newsletters and mailing lists the mailbox receives, as the Subscriptions page shows them: one row per sender and the address it writes to, with how much mail it sent, how much is unread, what share of it was read and how it lets you unsubscribe. A row marked Suggested is an active sender that is rarely read and still writing, worth unsubscribing from; suggested: true lists only those. status is active (the default), kept (ones the person chose to keep) or unsubscribed. query searches the sender, sort is recent, most, emails, read (least read first), unread or name, and offset pages on.

- Scopes: `threads:read`.
- The app's assistant runs it without asking.
- Toolkit: `subscriptions`.

**Inputs**

- `status` (`string`, one of `"active"`, `"kept"`, `"unsubscribed"`)
- `query` (`string`, up to 200 characters)
- `sort` (`string`, one of `"recent"`, `"most"`, `"emails"`, `"read"`, `"unread"`, `"name"`)
- `suggested` (`boolean`)
- `limit` (`integer`, at least 1, at most 200)
- `offset` (`integer`, at least 0)
- `address` (`string`, 3 to 320 characters)

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).

### `listSubscriptionDomains`

The same subscriptions grouped by sender domain, so a company that writes from several addresses is one row, with how many of its senders can be unsubscribed without a person opening a page. Takes the same filters as listSubscriptions.

- Scopes: `threads:read`.
- The app's assistant runs it without asking.
- Toolkit: `subscriptions`.

**Inputs**

- `status` (`string`, one of `"active"`, `"kept"`, `"unsubscribed"`)
- `query` (`string`, up to 200 characters)
- `sort` (`string`, one of `"recent"`, `"most"`, `"emails"`, `"read"`, `"unread"`, `"name"`)
- `suggested` (`boolean`)
- `limit` (`integer`, at least 1, at most 200)
- `offset` (`integer`, at least 0)
- `address` (`string`, 3 to 320 characters)

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).

### `unsubscribeSubscription`

Unsubscribe from one sender the way it asks for: a one-click request when it offers one, otherwise an unsubscribe email from the address the mail arrived at. A sender that only offers a page returns its link, which a person has to open. bin also moves every conversation from the sender to the Bin, and archive archives them instead. Take the id from listSubscriptions.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `subscriptions`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `bin` (`boolean`)
- `archive` (`boolean`)

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).

### `unsubscribeSubscriptionDomain`

Unsubscribe from every sender on one domain that can be unsubscribed without a person opening a page, as the domain view of the Subscriptions page does. Senders that only offer a page, and the ones the person kept, are skipped. bin also moves their conversations to the Bin, archive archives them instead, and address keeps it to the subscriptions delivered to one address.

- Scopes: `threads:write`.
- The app's assistant always asks first.
- Toolkit: `subscriptions`.

**Inputs**

- `domain` (`string`, required, 1 to 253 characters)
- `address` (`string`, 3 to 320 characters)
- `bin` (`boolean`)
- `archive` (`boolean`)

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).

### `unsubscribeThread`

Unsubscribe from the sender of an email thread, as the Unsubscribe button of the reading pane does, from the newest message in it that carries an unsubscribe header.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `subscriptions`.

**Inputs**

- `threadId` (`string`, required, 1 to 200 characters)

Also available in: API [`POST /threads/{id}/unsubscribe`](https://nextmail.sh/docs/api/reference/subscriptions#post-threads-id-unsubscribe); TypeScript [`nextmail.threads.unsubscribe()`](https://nextmail.sh/docs/sdk/reference/threads#unsubscribe); Python [`threads.unsubscribe()`](https://nextmail.sh/docs/python/reference/threads#unsubscribe); Ruby [`threads.unsubscribe`](https://nextmail.sh/docs/ruby/reference/threads#unsubscribe); PHP [`threads->unsubscribe`](https://nextmail.sh/docs/php/reference/threads#unsubscribe); Go [`Threads.Unsubscribe`](https://nextmail.sh/docs/go/reference/threads#unsubscribe); Java [`threads().unsubscribe`](https://nextmail.sh/docs/java/reference/threads#unsubscribe); C# [`Threads.UnsubscribeAsync`](https://nextmail.sh/docs/csharp/reference/threads#unsubscribe).

### `moveSubscription`

Move every conversation from one sender to the archive, the Bin or a label. future, true by default, also makes a rule that keeps doing it to new mail from the sender, which needs permission to change rules, and false drops such a rule. labelId is the label for destination label, from getUserLabels.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `subscriptions`.

**Inputs**

- `id` (`string`, required, 1 to 64 characters)
- `destination` (`string`, required, one of `"archive"`, `"bin"`, `"label"`)
- `labelId` (`string`, 1 to 200 characters)
- `future` (`boolean`)
- `ruleName` (`string`, up to 100 characters)

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).

### `keepSubscriptions`

Keep subscriptions the person wants, as Keep on the Subscriptions page does: they move from active to kept and are never suggested for unsubscribing again. kept: false puts kept ones back to active. ids come from listSubscriptions.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `subscriptions`.

**Inputs**

- `ids` (`string[]`, required, 1 to 100 items)
- `kept` (`boolean`)

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).

### `unsubscribeSubscriptions`

Unsubscribe from several senders at once, as Unsubscribe on a selection of the Subscriptions page does: each one by one-click request or an unsubscribe email. Senders that only offer a page are listed with the link a person has to open, and stay active. archive also archives every conversation from the senders, bin moves them to the Bin instead. ids come from listSubscriptions, for example the rows marked Suggested.

- Scopes: `threads:write`.
- The app's assistant always asks first.
- Toolkit: `subscriptions`.

**Inputs**

- `ids` (`string[]`, required, 1 to 100 items)
- `archive` (`boolean`)
- `bin` (`boolean`)

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).

### `moveSubscriptions`

Move every conversation from several senders to the archive, the Bin or a label, as Archive on a selection of the Subscriptions page does. future, true by default, also makes a rule per sender that keeps doing it to new mail, which needs permission to change rules. labelId is the label for destination label, from getUserLabels. ids come from listSubscriptions.

- Scopes: `threads:write`.
- The app's assistant always asks first.
- Toolkit: `subscriptions`.

**Inputs**

- `ids` (`string[]`, required, 1 to 100 items)
- `destination` (`string`, required, one of `"archive"`, `"bin"`, `"label"`)
- `labelId` (`string`, 1 to 200 characters)
- `future` (`boolean`)

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).