openemail.subscriptions
Каждый метод этого пространства имён: его сигнатура, параметры, что он возвращает, и пример.
Методы
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, 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 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.
Параметры
statusSubscriptionStatusactiveorunsubscribed. Defaults toactive.qstrSearches the sender name and address.
sortSubscriptionSortrecent,most,unreadorname. Defaults torecent.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
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
SubscriptionListResource with object set to 'list', the rows in data, total, counts and hasMore, where counts holds how many are active and unsubscribed.
Пример
from openemail import openemail page = openemail.subscriptions.list(sort='most', limit=20) for row in page['data']: print(row['senderEmail'], row['total'], row['method'])Примечания
Read only, so the SDK retries it after a network failure like any other read.
Также доступно в
subscriptions.list_domains()
List subscriptions by domain
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,) -> 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.
It takes the same filters as list.
Параметры
statusSubscriptionStatusactiveorunsubscribed. Defaults toactive.qstrSearches the sender name and address.
sortSubscriptionSortrecent,most,unreadorname. Defaults torecent.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
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
SubscriptionDomainListResource with object set to 'list', the domains in data, total, counts and hasMore.
Пример
from openemail import openemail page = openemail.subscriptions.list_domains(sort='most') for row in page['data']: print(row['domain'], row['senders'], row['unsubscribable'])Примечания
Read only, so the SDK retries it after a network failure like any other read.
Также доступно в
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.
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.
Параметры
idstrОбязательноThe subscription, from
list.body['bin']boolTruealso moves every conversation from the sender 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
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
UnsubscribeResultResource with object set to 'unsubscribe', subscriptionId, method, url, and binned, the number of conversations moved to the Bin.
Пример
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')Примечания
The SDK does not retry it, because a second call can send a second unsubscribe email.
Также доступно в
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.
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.
Параметры
domainstrОбязательноThe sender domain, from
list_domains.body['bin']boolTruealso moves the conversations to the Bin. 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
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
DomainUnsubscribeResultResource with object set to 'domain_unsubscribe', domain, unsubscribed, skipped, failed and binned.
Пример
from openemail import openemail result = openemail.subscriptions.unsubscribe_domain('news.acme.com') print(f'{result["unsubscribed"]} unsubscribed, {result["skipped"]} need a person')Примечания
The SDK does not retry it, because a second call can send unsubscribe emails again.
Также доступно в
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.
Параметры
idstrОбязательноThe subscription, from
list.body['destination']SubscriptionDestinationОбязательноarchive,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
OpenEmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Возвращает
SubscriptionMoveResultResource with object set to 'subscription_move', subscriptionId, moved and ruleId.
Пример
from openemail import openemail result = openemail.subscriptions.move( 'sub_7d2c1f0a9b3e4c5d6e7f8a9b', {'destination': 'archive', 'ruleName': 'Archive Acme news'}) print(result['moved'], result['ruleId'])Примечания
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.