---
title: "openemail.subscriptions"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://openemail.uk/docs/python/reference/subscriptions"
area: "Python"
category: "Reference"
---

# openemail.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

```python
def list(
    *,
    status: SubscriptionStatus | None = None,
    q: str | None = None,
    sort: SubscriptionSort | None = None,
    limit: int | None = None,
    offset: int | None = None,
    address: str | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SubscriptionListResource
```

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

`status` is `active`, the default, or `unsubscribed`. `q` searches the sender, and `sort` is `recent`, `most`, `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`.

**Parameters**

- `status` (`SubscriptionStatus`): `active` or `unsubscribed`. Defaults to `active`.
- `q` (`str`): Searches the sender name and address.
- `sort` (`SubscriptionSort`): `recent`, `most`, `unread` or `name`. Defaults to `recent`.
- `limit` (`int`): Rows per page, 1 to 200, defaulting to 50.
- `offset` (`int`): How many rows to skip.
- `address` (`str`): Only the subscriptions delivered to this address.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns 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` and `unsubscribed`.

**Example**

```python
from openemail import openemail

page = openemail.subscriptions.list(sort='most', limit=20)

for row in page['data']:
    print(row['senderEmail'], row['total'], row['method'])
```

**Notes**

- Read only, so the SDK retries it after a network failure like any other read.

Also available in: API [`GET /subscriptions`](https://openemail.uk/docs/api/reference/subscriptions#get-subscriptions); TypeScript [`subscriptions.list()`](https://openemail.uk/docs/sdk/reference/subscriptions#list); Ruby [`subscriptions.list`](https://openemail.uk/docs/ruby/reference/subscriptions#list); CLI [`openemail subscriptions list`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-list).

### `subscriptions.list_domains()`

List subscriptions by domain

```python
def list_domains(
    *,
    status: SubscriptionStatus | None = None,
    q: str | None = None,
    sort: SubscriptionSort | None = None,
    limit: int | None = None,
    offset: int | None = None,
    address: str | None = None,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SubscriptionDomainListResource
```

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

It takes the same filters as `list`.

Scopes: `threads:read`.

**Parameters**

- `status` (`SubscriptionStatus`): `active` or `unsubscribed`. Defaults to `active`.
- `q` (`str`): Searches the sender name and address.
- `sort` (`SubscriptionSort`): `recent`, `most`, `unread` or `name`. Defaults to `recent`.
- `limit` (`int`): Rows per page, 1 to 200, defaulting to 50.
- `offset` (`int`): How many rows to skip.
- `address` (`str`): Only the subscriptions delivered to this address.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SubscriptionDomainListResource` with `object` set to `'list'`, the domains in `data`, `total`, `counts` and `hasMore`.

**Example**

```python
from openemail import openemail

page = openemail.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: API [`GET /subscriptions/domains`](https://openemail.uk/docs/api/reference/subscriptions#get-subscriptions-domains); TypeScript [`subscriptions.listDomains()`](https://openemail.uk/docs/sdk/reference/subscriptions#listDomains); Ruby [`subscriptions.list_domains`](https://openemail.uk/docs/ruby/reference/subscriptions#listDomains); CLI [`openemail subscriptions list-domains`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-list-domains).

### `subscriptions.unsubscribe()`

Unsubscribe from a sender

```python
def unsubscribe(
    id: str,
    body: SubscriptionUnsubscribe | None = None,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> UnsubscribeResultResource
```

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.

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

**Parameters**

- `id` (`str`, required): The subscription, from `list`.
- `body['bin']` (`bool`): `True` also moves every conversation from the sender to the Bin. Defaults to `False`.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`UnsubscribeResultResource` with `object` set to `'unsubscribe'`, `subscriptionId`, `method`, `url`, and `binned`, the number of conversations moved to the Bin.

**Example**

```python
from openemail import openemail

result = openemail.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: API [`POST /subscriptions/{id}/unsubscribe`](https://openemail.uk/docs/api/reference/subscriptions#post-subscriptions-id-unsubscribe); TypeScript [`subscriptions.unsubscribe()`](https://openemail.uk/docs/sdk/reference/subscriptions#unsubscribe); Ruby [`subscriptions.unsubscribe`](https://openemail.uk/docs/ruby/reference/subscriptions#unsubscribe); CLI [`openemail subscriptions unsubscribe`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-unsubscribe).

### `subscriptions.unsubscribe_domain()`

Unsubscribe from a whole domain

```python
def unsubscribe_domain(
    domain: str,
    body: SubscriptionDomainUnsubscribe | None = None,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> DomainUnsubscribeResultResource
```

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.

`bin` also moves their conversations to the Bin, 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`.

**Parameters**

- `domain` (`str`, required): The sender domain, from `list_domains`.
- `body['bin']` (`bool`): `True` also moves the conversations to the Bin. Defaults to `False`.
- `body['address']` (`str`): Only the subscriptions delivered to this address.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`DomainUnsubscribeResultResource` with `object` set to `'domain_unsubscribe'`, `domain`, `unsubscribed`, `skipped`, `failed` and `binned`.

**Example**

```python
from openemail import openemail

result = openemail.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`](https://openemail.uk/docs/api/reference/subscriptions#post-subscriptions-domains-domain-unsubscribe); TypeScript [`subscriptions.unsubscribeDomain()`](https://openemail.uk/docs/sdk/reference/subscriptions#unsubscribeDomain); Ruby [`subscriptions.unsubscribe_domain`](https://openemail.uk/docs/ruby/reference/subscriptions#unsubscribeDomain); CLI [`openemail subscriptions unsubscribe-domain`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-unsubscribe-domain).

### `subscriptions.move()`

Move what a sender sent

```python
def move(
    id: str,
    body: SubscriptionMove,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SubscriptionMoveResultResource
```

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

Scopes: `threads:write`.

**Parameters**

- `id` (`str`, required): The subscription, from `list`.
- `body['destination']` (`SubscriptionDestination`, required): `archive`, `bin` or `label`.
- `body['labelId']` (`str | None`): The label to file under, for `label`.
- `body['future']` (`bool`): Keep doing it to new mail with a rule. Defaults to `True`.
- `body['ruleName']` (`str | None`): A name for that rule.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `OpenEmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SubscriptionMoveResultResource` with `object` set to `'subscription_move'`, `subscriptionId`, `moved` and `ruleId`.

**Example**

```python
from openemail import openemail

result = openemail.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: API [`POST /subscriptions/{id}/move`](https://openemail.uk/docs/api/reference/subscriptions#post-subscriptions-id-move); TypeScript [`subscriptions.move()`](https://openemail.uk/docs/sdk/reference/subscriptions#move); Ruby [`subscriptions.move`](https://openemail.uk/docs/ruby/reference/subscriptions#move); CLI [`openemail subscriptions move`](https://openemail.uk/docs/cli/reference/subscriptions#subscriptions-move).