--- title: "Subscriptions" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://openemail.uk/docs/api/reference/subscriptions" area: "API" category: "Reference" --- # 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. Unsubscribe from one sender 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 and how much arrived in the last 30 days. A key or an app limited to particular addresses lists only the subscriptions delivered to them. Requires the `threads:read` scope. - Scopes: `threads:read`. **Query parameters** - `status` (`string`, one of `"active"`, `"unsubscribed"`, default `"active"`): `active` lists what still arrives, `unsubscribed` what you left. - `q` (`string`, up to 200 characters): Searches the sender name and address. - `sort` (`string`, one of `"recent"`, `"most"`, `"unread"`, `"name"`, default `"recent"`): `recent` puts the newest mail first, `most` the senders with the most mail, `unread` those with the most unread, `name` sorts by sender. - `limit` (`integer`, at least 1, at most 200, default `50`): Rows per page. - `offset` (`integer`, at least 0, default `0`): How many rows to skip, for the next page. - `address` (`string`, 3 to 320 characters): Only the subscriptions delivered to this address. One the key does not reach lists nothing. **Returns** - `200` `SubscriptionList`: A page of subscriptions. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`subscriptions.list()`](https://openemail.uk/docs/sdk/reference/subscriptions#list); CLI [`openemail subscriptions list`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-list); MCP [`listSubscriptions`](https://openemail.uk/docs/mcp/tools/subscriptions#listSubscriptions). ### `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. - Scopes: `threads:read`. **Query parameters** - `status` (`string`, one of `"active"`, `"unsubscribed"`, default `"active"`): `active` lists what still arrives, `unsubscribed` what you left. - `q` (`string`, up to 200 characters): Searches the sender name and address. - `sort` (`string`, one of `"recent"`, `"most"`, `"unread"`, `"name"`, default `"recent"`): `recent` puts the newest mail first, `most` the senders with the most mail, `unread` those with the most unread, `name` sorts by sender. - `limit` (`integer`, at least 1, at most 200, default `50`): Rows per page. - `offset` (`integer`, at least 0, default `0`): How many rows to skip, for the next page. - `address` (`string`, 3 to 320 characters): Only the subscriptions delivered to this address. One the key does not reach lists nothing. **Returns** - `200` `SubscriptionDomainList`: A page of sender domains. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`subscriptions.listDomains()`](https://openemail.uk/docs/sdk/reference/subscriptions#listDomains); CLI [`openemail subscriptions list-domains`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-list-domains); MCP [`listSubscriptionDomains`](https://openemail.uk/docs/mcp/tools/subscriptions#listSubscriptionDomains). ### `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. - Scopes: `threads:write`. **Path parameters** - `domain` (`string`, required): The sender domain, as `GET /subscriptions/domains` returns it. **Request body** - `bin` (`boolean`, default `false`): Also move every conversation from the senders to the Bin. - `address` (`string`, 3 to 320 characters): Only the subscriptions delivered to this address. **Returns** - `200` `DomainUnsubscribeResult`: What happened to each sender, counted. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`subscriptions.unsubscribeDomain()`](https://openemail.uk/docs/sdk/reference/subscriptions#unsubscribeDomain); CLI [`openemail subscriptions unsubscribe-domain`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-unsubscribe-domain); MCP [`unsubscribeSubscriptionDomain`](https://openemail.uk/docs/mcp/tools/subscriptions#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. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The subscription, as `GET /subscriptions` returns it. **Request body** - `bin` (`boolean`, default `false`): Also move every conversation from the sender to the Bin. **Returns** - `200` `UnsubscribeResult`: 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 return: `400`, `401`, `403`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`subscriptions.unsubscribe()`](https://openemail.uk/docs/sdk/reference/subscriptions#unsubscribe); CLI [`openemail subscriptions unsubscribe`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-unsubscribe); MCP [`unsubscribeSubscription`](https://openemail.uk/docs/mcp/tools/subscriptions#unsubscribeSubscription). ### `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. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The subscription, as `GET /subscriptions` returns it. **Request body** - `destination` (`string`, required, one of `"archive"`, `"bin"`, `"label"`): `archive`, `bin` or `label`. - `labelId` (`string`, nullable, 1 to 200 characters): The label to file under when `destination` is `label`. - `future` (`boolean`, default `true`): Also keep doing it to new mail from the sender, with a rule. Needs `rules:write`. - `ruleName` (`string`, nullable, up to 100 characters): A name for that rule. **Returns** - `200` `SubscriptionMoveResult`: How many conversations moved, and the rule. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`subscriptions.move()`](https://openemail.uk/docs/sdk/reference/subscriptions#move); CLI [`openemail subscriptions move`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-move); MCP [`moveSubscription`](https://openemail.uk/docs/mcp/tools/subscriptions#moveSubscription). ### `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. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. **Returns** - `200` `UnsubscribeResult`: 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 return: `400`, `401`, `403`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: SDK [`threads.unsubscribe()`](https://openemail.uk/docs/sdk/reference/threads#unsubscribe); CLI [`openemail threads unsubscribe`](https://openemail.uk/docs/cli/reference/threads#threads-unsubscribe); MCP [`unsubscribeThread`](https://openemail.uk/docs/mcp/tools/subscriptions#unsubscribeThread). ### Objects #### `DomainUnsubscribeResult` `object` - `object` (`string`, one of `"domain_unsubscribe"`) - `domain` (`string`) - `unsubscribed` (`integer`) - `skipped` (`integer`): Senders that only offer a page. - `failed` (`integer`) - `binned` (`integer`) #### `Subscription` `object` - `object` (`string`, one of `"subscription"`) - `id` (`string`) - `senderEmail` (`string`) - `senderName` (`string`, nullable) - `recipient` (`string`): The address the mail arrives at. - `status` (`string`, one of `"active"`, `"unsubscribed"`) - `method` (`string`, nullable, one of `"one-click"`, `"email"`, `"link"`): How the sender lets you unsubscribe, or null when it gives no way. - `linkUrl` (`string`, nullable): Its unsubscribe page, when it has one. - `unread` (`integer`) - `recent` (`integer`): Mail in the last 30 days. - `total` (`integer`) - `sinceUnsubscribed` (`integer`): Mail that still arrived after you unsubscribed. - `lastSeenAt` (`string`, format `date-time`) - `unsubscribedAt` (`string`, nullable, format `date-time`) - `unsubscribedWith` (`string`, nullable, one of `"one-click"`, `"email"`, `"link"`) - `future` (`object`, nullable): The rule that keeps moving its new mail, when there is one. - `ruleId` (`string`) - `destination` (`string`, one of `"archive"`, `"bin"`, `"label"`) - `labelId` (`string`, nullable) #### `SubscriptionDomain` `object` - `object` (`string`, one of `"subscription_domain"`) - `domain` (`string`) - `name` (`string`) - `sampleEmail` (`string`): One sender address on the domain. - `senders` (`integer`) - `unsubscribable` (`integer`): Senders that can be unsubscribed without a person opening a page. - `unread` (`integer`) - `recent` (`integer`) - `total` (`integer`) - `sinceUnsubscribed` (`integer`) - `lastSeenAt` (`string`, format `date-time`) #### `SubscriptionDomainList` `object` - `object` (`string`, one of `"list"`) - `data` (`SubscriptionDomain[]`) - `total` (`integer`) - `counts` (`object`) - `active` (`integer`) - `unsubscribed` (`integer`) - `hasMore` (`boolean`) #### `SubscriptionList` `object` - `object` (`string`, one of `"list"`) - `data` (`Subscription[]`) - `total` (`integer`): Rows that match, across every page. - `counts` (`object`) - `active` (`integer`) - `unsubscribed` (`integer`) - `hasMore` (`boolean`) #### `SubscriptionMoveResult` `object` - `object` (`string`, one of `"subscription_move"`) - `subscriptionId` (`string`) - `moved` (`integer`): Conversations moved. - `ruleId` (`string`, nullable): The rule that keeps moving new mail. #### `UnsubscribeResult` `object` - `object` (`string`, one of `"unsubscribe"`) - `subscriptionId` (`string`) - `threadId` (`string`): Present when it was asked for through a thread. - `method` (`string`, one of `"one-click"`, `"email"`, `"link"`) - `url` (`string`, nullable): The page to open when `method` is `link`, since that one needs a person. - `binned` (`integer`): Conversations moved to the Bin.