Python

openemail.audiences

Каждый метод этого пространства имён: его сигнатура, параметры, что он возвращает, и пример.

Методы

Named lists of contacts. Every contact is in the default audience, and you make the rest.

`audiences.list()`

List one page of the workspace audiences

audiences:readПостранично перебирает результаты

Сигнатура

def list(    *,    limit: int | None = None,    cursor: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Page[AudienceResource]

Returns one page of the audiences in the workspace, with the default audience first and the rest newest first. Paging is keyset: limit= takes 1 to 100 and defaults to 25, and nextCursor goes back as cursor= while hasMore is True, so every audience is reachable. list_all and iterate do that walk for you.

builtin tells the default audience apart from the ones you made. It is default on exactly one row per workspace, the audience that holds every contact, and None on everything else. Branch on builtin rather than on the name, which anybody can change.

contactCount is counted at the moment of the read, so two reads either side of a contacts.create disagree by one.

Параметры

limitint: Rows per page, a whole number from 1 to 100. The server defaults to 25.
cursorstr: The nextCursor from the previous page, an audience id. One that names no audience in the workspace is a 400 invalid_cursor.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

Page[AudienceResource], a dict with items, hasMore and nextCursor. Each item has id, name, description, builtin, contactCount, lastContactAt, createdAt and updatedAt.

Пример

from openemail import openemail page = openemail.audiences.list() for audience in page['items']:    if audience['builtin'] == 'default':        print(audience['contactCount'], 'contacts in', audience['name'])

Примечания

The default audience is resolved on the first read of the workspace, so a workspace that has never had an audience made still lists it.
Names are not unique. Two audiences can both be called Newsletter, so match on id in stored configuration.

Также доступно в

API: GET /audiences
TypeScript: audiences.list()
Ruby: audiences.list
CLI: openemail audiences list

`audiences.list_all()`

Collect every audience in the workspace into one list

audiences:readПостранично перебирает результаты

Сигнатура

def list_all(    *,    limit: int | None = None,    cursor: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[AudienceResource]

Follows nextCursor from page to page and returns every audience in the workspace in one list, the default audience first and the rest newest first. limit= sets the page size of each request, not the total.

Параметры

limitint: Page size per request, from 1 to 100, defaulting to 25 on the server.
cursorstr: An audience id to start after.
api_keystr: Overrides the client's API key for every page of this walk.
timeoutfloat: 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.

Возвращает

list[AudienceResource] holding every audience across all pages.

Пример

from openemail import openemail audiences = openemail.audiences.list_all(limit=100)counts = {audience['name']: audience['contactCount'] for audience in audiences} print(len(audiences), counts.get('Newsletter'))

Примечания

A failure on any page raises, and the audiences already fetched are discarded.

Также доступно в

API: GET /audiences
TypeScript: audiences.listAll()
Ruby: audiences.list_all

`audiences.iterate()`

Stream the workspace audiences one at a time

audiences:readПостранично перебирает результаты

Сигнатура

def iterate(    *,    limit: int | None = None,    cursor: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Iterator[AudienceResource]

Returns a generator that yields audiences one at a time, the default audience first, and requests the next page only once the current one is drained. Breaking out of the loop stops the requests.

Параметры

limitint: Page size per request, from 1 to 100, defaulting to 25 on the server.
cursorstr: An audience id to start after.
api_keystr: Overrides the client's API key for every page of this walk.
timeoutfloat: 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.

Возвращает

Iterator[AudienceResource], a generator that yields one audience per step.

Пример

from openemail import openemail for audience in openemail.audiences.iterate():    if audience['contactCount'] == 0:        print('Empty:', audience['name'], audience['id'])

Примечания

The generator is lazy, so an abandoned loop costs only the pages you consumed.

Также доступно в

API: GET /audiences
TypeScript: audiences.iterate()
Ruby: audiences.iterate

`audiences.growth()`

Read how audiences grew over a time window

audiences:read

Сигнатура

def growth(    *,    audience_ids: Sequence[str] | None = None,    days: int | None = None,    minutes: int | None = None,    grain: TrackingGrain | None = None,    offset_minutes: int | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> AudienceGrowthResource

Returns the numbers behind the growth chart on the Audiences page in one request. For each audience it reports total, the contacts in it now, before, how many of those joined before the window, added, how many joined inside it, subscribed, how many of them are still subscribed, unsubscribed, how many unsubscribed inside the window through a broadcast link, and buckets, when they joined and unsubscribed, cut to the grain. totals sums the audiences read.

An audience records the date each contact joined it and never the date one left. A series therefore counts the contacts still in the list today by the date they joined, and it never falls: a contact who joined inside the window and was removed since is not in it at all. Read it as the growth of the list as it stands, not as a history of every change.

In totals, contacts counts each person once, however many of the audiences they are in. memberships adds the lists up, and the default audience holds every contact, so a person in two other audiences counts three times there. subscribed counts each person still subscribed to at least one of the audiences read, which is who a broadcast to them would reach, and unsubscribed adds up the unsubscribes inside the window. busiest is the bucket with the most joins, or None.

buckets is sparse and oldest first: a bucket in which nobody joined or unsubscribed has no entry, so a chart must fill the gaps. grain= sets the bucket width and the key shape, YYYY-MM-DD, YYYY-MM-DDTHH or YYYY-MM-DDTHH:MM, and offset_minutes= shifts the boundaries so days break where the reader's day does. The window starts at the beginning of its oldest bucket, reported as since, and ends now, reported as until.

Параметры

audience_idsSequence[str]: Up to 50 audience ids to read, sent comma separated. Leave it out, or pass an empty list, to read every audience in the workspace, the default one included. An id that is not an audience of this workspace is a 404 audience_not_found on audienceIds, and more than 50 is a 422.
daysint: Window length in days, from 1 to 1095, defaulting to 30.
minutesint: Window length in minutes, from 1 to 1576800. Takes precedence over days, and only useful below a day with a finer grain.
grainTrackingGrain: Bucket width: minute, hour or day, defaulting to day.
offset_minutesint: Minutes east of UTC to cut the buckets in, from -840 to 840, defaulting to 0. Pass time.localtime().tm_gmtoff // 60 for the zone the code runs in.
api_keystr: Reads with this key instead of the client's.
timeoutfloat: 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.

Возвращает

AudienceGrowthResource, a dict with object set to audience_growth, since, until, grain, offsetMinutes, totals and series. totals has contacts, subscribed, memberships, added, unsubscribed, lists and busiest. Each entry of series has id, name, builtin as a bool, total, subscribed, before, added, unsubscribed and buckets, each a dict with bucket, added and unsubscribed. The series come largest first, then by name.

Пример

import time from openemail import openemail growth = openemail.audiences.growth(    days=90, grain='day', offset_minutes=time.localtime().tm_gmtoff // 60)totals = growth['totals'] print(totals['added'], 'joined since', growth['since'], 'busiest', totals['busiest']) for series in growth['series']:    print(series['name'], series['before'], '->', series['total'])

Примечания

Read only, so the SDK retries it after a network failure like any other read.
builtin on a series is a bool, True on the default audience. On AudienceResource the same fact is the string default.
A running total per bucket is before plus the added of every bucket up to it.

Также доступно в

API: GET /audiences/growth
TypeScript: audiences.growth()
Ruby: audiences.growth
CLI: openemail audiences growth

`audiences.get()`

Read one audience by id

audiences:read

Сигнатура

def get(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> AudienceResource

Returns a single audience in the same shape as list, with a fresh contactCount. This is the cheap way to watch a count move without pulling the contacts behind it.

The id is the one from list or create, such as aud_9f2c4b7e1a0d63d84c5f2e7b. An id from another workspace is a 404 rather than a 403, since the API never tells you that something exists somewhere you cannot see.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

AudienceResource with id, name, description, builtin, contactCount, lastContactAt, the moment the most recent contact joined or None while it is empty, createdAt and updatedAt.

Пример

from openemail import OpenEmailApiError, openemail try:    audience = openemail.audiences.get('aud_9f2c4b7e1a0d63d84c5f2e7b')except OpenEmailApiError as error:    if error.is_not_found:        print('No such audience in this workspace')    else:        raiseelse:    print(audience['name'], audience['contactCount'])

Примечания

A missing audience raises OpenEmailApiError with is_not_found set to True and code audience_not_found.
The default audience can be read here like any other, and builtin is default on it.

Также доступно в

API: GET /audiences/{id}
TypeScript: audiences.get()
Ruby: audiences.get
CLI: openemail audiences get

`audiences.create()`

Create an audience

audiences:write

Сигнатура

def create(    body: AudienceCreate,    *,    api_key: str | None = None,    timeout: float | None = None,) -> AudienceResource

Makes a new, empty audience in the workspace and returns it with its id. name is trimmed and must then be 1 to 120 characters. description is optional free text for whoever reads the list later.

The audience comes back with builtin set to None and contactCount zero. Only the default audience carries a builtin, and it cannot be made or copied here.

Names are not checked for duplicates, so two calls with the same name make two audiences. Fill it with audiences.add_contact, one contact at a time, and the contacts must already be in the book.

Параметры

body['name']strОбязательно: Display name, trimmed, 1 to 120 characters. Not unique.
body['description']str | None: What the audience is for. Leave it out to create the audience without one.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

AudienceResource with the new id, builtin set to None and contactCount zero.

Пример

from openemail import openemail audience = openemail.audiences.create(    {'name': 'Product updates', 'description': 'Customers who asked to hear about releases'}) openemail.audiences.add_contact(audience['id'], {'email': '[email protected]'}) print(audience['id'], audience['name'])

Примечания

The SDK does not retry a create after a network failure, and nothing here deduplicates by name, so a retry after a lost response can leave two audiences. List them and delete the spare.
A workspace holds at most 100 audiences. The 101st is refused with 422 audience_limit_reached on name.
Audiences belong to the workspace, not to the key or the person who made them.

Также доступно в

API: POST /audiences
TypeScript: audiences.create()
Ruby: audiences.create
CLI: openemail audiences create

`audiences.update()`

Rename an audience or change its description

audiences:write

Сигнатура

def update(    id: str,    patch: AudiencePatch,    *,    api_key: str | None = None,    timeout: float | None = None,) -> AudienceResource

Changes the keys you send and leaves the rest alone. A key you leave out keeps its stored value and an explicit None clears it, so {'description': None} empties the description while {} changes nothing.

The default audience can be renamed like any other, and renaming it does not change builtin or what it holds. builtin itself cannot be set, moved or cleared from here.

The id never changes, and membership is untouched.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b.
patch['name']str: New display name, trimmed, 1 to 120 characters.
patch['description']str | None: New description. None clears it.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

AudienceResource as it stands after the change, with the unchanged id and builtin.

Пример

from openemail import openemail audience = openemail.audiences.update('aud_9f2c4b7e1a0d63d84c5f2e7b', {'name': 'Release notes'}) print(audience['name'], audience['updatedAt'])

Примечания

The SDK retries this call after a network failure, since the same patch sent twice leaves the same audience.
Renaming does not move anybody. Contacts stay in the audience under its new name.

Также доступно в

API: PATCH /audiences/{id}
TypeScript: audiences.update()
Ruby: audiences.update
CLI: openemail audiences update

`audiences.delete()`

Delete an audience and keep its contacts

audiences:write

Сигнатура

def delete(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> DeletedAudienceResource

Deletes the audience and drops every membership it held, in one transaction. The contacts themselves are not touched: they stay in the address book, in the default audience, and in any other audience they were in.

The default audience cannot be deleted. The call is refused with 409 audience_immutable on id, because it is what makes the book readable as a list. Delete the contacts instead if you mean to empty it.

There is no undo, and a new audience with the same name comes back empty.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b. Not the default audience.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

DeletedAudienceResource, a dict with object set to audience, the id and deleted set to True.

Пример

from openemail import OpenEmailApiError, openemail try:    removed = openemail.audiences.delete('aud_9f2c4b7e1a0d63d84c5f2e7b')except OpenEmailApiError as error:    if error.code == 'audience_immutable':        print('The default audience cannot be deleted')    else:        raiseelse:    print(removed['id'], removed['deleted'])

Примечания

The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
An OAuth access token needs a verification code for this call, and is refused with 403 step_up_required until the app has verified one in the last 60 minutes. is_step_up_required on the error says so. An API key is never asked for a code.
An audience from another workspace is a 404, never a 403.
To keep the audience and take its contacts out, use empty.

Также доступно в

API: DELETE /audiences/{id}
TypeScript: audiences.delete()
Ruby: audiences.delete
CLI: openemail audiences delete

`audiences.empty()`

Take every contact out of an audience and keep the audience

audiences:write

Сигнатура

def empty(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> EmptiedAudienceResource

Removes every membership of the audience in one transaction and returns the audience as it now stands, with contactCount 0, plus removed, the number of contacts taken out. The audience keeps its id, name and description, so anything that points at it still works. The contacts are not touched: each one stays in the address book, in the default audience and in every other audience it is in.

The default audience cannot be emptied. The call is refused with 409 audience_immutable on id, because that audience holds every contact for as long as it is a contact.

There is no undo. The app asks the person to confirm before it empties a list, but this call asks nothing: it needs no verification code, whether it is made with an API key or with the OAuth access token of an app the person connected. Check the id before you call it.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b. Not the default audience.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

EmptiedAudienceResource, the AudienceResource with contactCount 0, plus removed, the number of contacts taken out.

Пример

from openemail import openemail emptied = openemail.audiences.empty('aud_9f2c4b7e1a0d63d84c5f2e7b') print(emptied['removed'], 'removed from', emptied['name'])

Примечания

The SDK does not retry this call after a network failure. Emptying twice leaves the same empty audience, but the second call reports 0 in removed, so read the audience with get if a response was lost.
Emptying an audience that is already empty succeeds with 0 in removed.
To take out only some contacts, use remove_contacts. To delete the audience as well, use delete, which also leaves the contacts alone.

Также доступно в

API: POST /audiences/{id}/empty
TypeScript: audiences.empty()
Ruby: audiences.empty
CLI: openemail audiences empty

`audiences.list_contacts()`

List one page of the contacts in one audience

audiences:readПостранично перебирает результаты

Сигнатура

def list_contacts(    id: str,    *,    limit: int | None = None,    cursor: str | None = None,    q: str | None = None,    source: ContactSource | None = None,    sort: AudienceMemberSort | None = None,    statuses: Sequence[AudienceMemberStatus] | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Page[AudienceContactResource]

Returns one page of the contacts in the audience. The rows are the contacts themselves, not membership records, so they carry email, name, source, notes, lastSeenAt, createdAt and updatedAt, plus addedAt, the date the contact joined this audience, and unsubscribedAt, when it unsubscribed from a broadcast sent to this audience, or None while it is subscribed. An unsubscribed contact stays in the audience and broadcasts to it skip it.

By default the order is the one contacts.list uses: the contacts most recently written to first, and those never written to last. sort= picks another order, q= searches names and addresses, source= keeps only contacts saved by hand or only those recorded from the composer, and statuses= keeps only the subscribed or only the unsubscribed. These are the controls on the audience page in the app.

Paging is keyset: limit= takes 1 to 200 and defaults to 50, and nextCursor goes back as cursor= while hasMore is True, so every contact in the audience is reachable however large it grows. Send the same q=, source=, sort= and statuses= with every page. list_all_contacts and iterate_contacts do that walk for you, which is also how to export an audience.

Reading the default audience here returns the whole address book.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b.
limitint: Rows per page, a whole number from 1 to 200. The server defaults to 50.
cursorstr: The nextCursor from the previous page. Never build one yourself: one that names no contact in this audience is a 400 invalid_cursor.
qstr: Narrows to contacts whose name or address matches, up to 200 characters. When nothing matches exactly the search allows for a typo instead.
sourceContactSource: Narrows to contacts recorded that way: manual for one somebody saved, auto for one recorded by a send from the app composer.
sortAudienceMemberSort: How the page is ordered. last-heard-newest, the default, puts the contacts most recently written to first and those never written to last, last-heard-oldest reverses it, added-newest and added-oldest order by addedAt, and name is alphabetical without case, with a contact that has no name sorting by its address.
statusesSequence[AudienceMemberStatus]: Keeps only subscribed members, only unsubscribed ones, or both. Leave it out, or name both, for everyone in the audience. AUDIENCE_MEMBER_STATUSES holds the values.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

Page[AudienceContactResource], a dict with items, hasMore and nextCursor. Each item is a ContactResource plus addedAt, when the contact joined this audience, and unsubscribedAt, None unless it unsubscribed from a broadcast.

Пример

from openemail import openemail page = openemail.audiences.list_contacts(    'aud_9f2c4b7e1a0d63d84c5f2e7b', limit=200, sort='added-newest') for contact in page['items']:    print(contact['email'], 'joined', contact['addedAt'])

Примечания

Only audiences:read is needed. A key with that scope reads the contacts in an audience without holding contacts:read.
A contact in no audience of your own is still in the default one, so nothing is invisible to this route.
An audience from another workspace is a 404.
An unknown sort, source or status is a 422 invalid_parameter.

Также доступно в

API: GET /audiences/{id}/contacts
TypeScript: audiences.listContacts()
Ruby: audiences.list_contacts
CLI: openemail audiences list-contacts

`audiences.list_all_contacts()`

Collect every contact in one audience into one list

audiences:readПостранично перебирает результаты

Сигнатура

def list_all_contacts(    id: str,    *,    limit: int | None = None,    cursor: str | None = None,    q: str | None = None,    source: ContactSource | None = None,    sort: AudienceMemberSort | None = None,    statuses: Sequence[AudienceMemberStatus] | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[AudienceContactResource]

Walks every page of one audience and returns all of its contacts in one list, each with addedAt, in the order list_contacts returns them. q=, source=, sort= and statuses= are sent with every page, so the walk returns the filtered list in the order you asked for. This is the way to export an audience. On the default audience that is the whole address book, so prefer iterate_contacts when you can stop early. limit= sets the page size of each request, not the total.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b.
limitint: Page size per request, from 1 to 200, defaulting to 50 on the server.
cursorstr: A cursor from an earlier page to start after.
qstr: Narrows to contacts whose name or address matches, up to 200 characters. When nothing matches exactly the search allows for a typo instead.
sourceContactSource: Narrows to contacts recorded that way: manual for one somebody saved, auto for one recorded by a send from the app composer.
sortAudienceMemberSort: The order of the walk, as for list_contacts. Defaults to last-heard-newest.
statusesSequence[AudienceMemberStatus]: Keeps only subscribed members, only unsubscribed ones, or both. Leave it out, or name both, for everyone in the audience. AUDIENCE_MEMBER_STATUSES holds the values.
api_keystr: Overrides the client's API key for every page of this walk.
timeoutfloat: 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.

Возвращает

list[AudienceContactResource] holding every contact in the audience that matches, each a ContactResource plus addedAt and unsubscribedAt.

Пример

from openemail import openemail contacts = openemail.audiences.list_all_contacts('aud_9f2c4b7e1a0d63d84c5f2e7b', limit=200)recipients = [contact['email'] for contact in contacts] print(len(recipients), 'recipients')

Примечания

A failure on any page raises, and the contacts already fetched are discarded.
An audience from another workspace is a 404 on the first page.

Также доступно в

API: GET /audiences/{id}/contacts
TypeScript: audiences.listAllContacts()
Ruby: audiences.list_all_contacts

`audiences.iterate_contacts()`

Stream the contacts in one audience one at a time

audiences:readПостранично перебирает результаты

Сигнатура

def iterate_contacts(    id: str,    *,    limit: int | None = None,    cursor: str | None = None,    q: str | None = None,    source: ContactSource | None = None,    sort: AudienceMemberSort | None = None,    statuses: Sequence[AudienceMemberStatus] | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Iterator[AudienceContactResource]

Returns a generator over one audience that yields contacts one at a time, each with addedAt, and fetches the next page only when the current one is drained. q=, source=, sort= and statuses= are sent with every page. Nothing is requested until you consume it, and breaking out of the loop stops further requests, which suits a send loop or an export that works through a large audience.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b.
limitint: Page size per request, from 1 to 200, defaulting to 50 on the server.
cursorstr: A cursor from an earlier page to start after.
qstr: Narrows to contacts whose name or address matches, up to 200 characters. When nothing matches exactly the search allows for a typo instead.
sourceContactSource: Narrows to contacts recorded that way: manual for one somebody saved, auto for one recorded by a send from the app composer.
sortAudienceMemberSort: The order of the walk, as for list_contacts. Defaults to last-heard-newest.
statusesSequence[AudienceMemberStatus]: Keeps only subscribed members, only unsubscribed ones, or both. Leave it out, or name both, for everyone in the audience. AUDIENCE_MEMBER_STATUSES holds the values.
api_keystr: Overrides the client's API key for every page of this walk.
timeoutfloat: 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.

Возвращает

Iterator[AudienceContactResource], a generator that yields one contact per step, each a ContactResource plus addedAt and unsubscribedAt.

Пример

from openemail import openemail for contact in openemail.audiences.iterate_contacts('aud_9f2c4b7e1a0d63d84c5f2e7b'):    sent = openemail.templates.send(        'welcome', {'from': '[email protected]', 'to': contact['email']}    )     print(contact['email'], sent['status'])

Примечания

The generator is lazy, so an abandoned loop costs only the pages you consumed.

Также доступно в

API: GET /audiences/{id}/contacts
TypeScript: audiences.iterateContacts()
Ruby: audiences.iterate_contacts

`audiences.add_contact()`

Put a contact in an audience

audiences:write

Сигнатура

def add_contact(    id: str,    body: AudienceContactAdd,    *,    api_key: str | None = None,    timeout: float | None = None,) -> AudienceMemberResource

Adds one contact to one audience and returns the membership, with the contact it points at. The address is trimmed and lower cased before the lookup, and it has to be a contact in this workspace already: an address that is not in the book is refused with 422 contact_not_found on email. Save it with contacts.create first.

There is one membership per audience and contact, so adding somebody who is already in the audience returns the membership that is there, with its original addedAt, rather than adding a second one or failing. That makes the call safe to replay, and the SDK retries it after a network failure.

Adding to the default audience is accepted and changes nothing, since every contact is already in it.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b.
body['email']strОбязательно: The address of a contact already in the workspace book, matched case insensitively.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

AudienceMemberResource, a dict with object set to audience_member, audienceId, addedAt and contact, the ContactResource it points at.

Пример

from openemail import openemail openemail.contacts.create({'email': '[email protected]', 'name': 'Grace Hopper'}) membership = openemail.audiences.add_contact(    'aud_9f2c4b7e1a0d63d84c5f2e7b', {'email': '[email protected]'}) print(membership['audienceId'], membership['addedAt'])

Примечания

To add up to 200 contacts in one call, use add_contacts. To create contacts as you add them, use import_contacts.
audiences:write is the only scope checked. Adding a contact to an audience is not a write to the contact.
Deleting the contact later drops this membership with it.

Также доступно в

API: POST /audiences/{id}/contacts
TypeScript: audiences.addContact()
Ruby: audiences.add_contact
CLI: openemail audiences add-contact

`audiences.remove_contact()`

Take a contact out of an audience

audiences:write

Сигнатура

def remove_contact(    id: str,    email: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> RemovedAudienceContactResource

Drops one membership and leaves everything else alone. The contact stays in the address book, in the default audience and in every other audience it was in. The address is trimmed and lower cased, and the SDK URL encodes it for the path.

A contact that is not in this audience is a 404, so a typo cannot report a removal that never happened.

The default audience cannot be thinned. Removing a contact from it is refused with 409 audience_immutable, because it holds every contact by definition. Use contacts.delete when you mean the contact to go.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b. Not the default audience.
emailstrОбязательно: The contact's address, matched case insensitively.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

RemovedAudienceContactResource, a dict with object set to audience_member, audienceId, email and deleted set to True.

Пример

from openemail import openemail removed = openemail.audiences.remove_contact(    'aud_9f2c4b7e1a0d63d84c5f2e7b', '[email protected]') print(removed['email'], removed['deleted'])

Примечания

The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
Removing the last contact leaves the audience in place and empty.

Также доступно в

API: DELETE /audiences/{id}/contacts/{email}
TypeScript: audiences.removeContact()
Ruby: audiences.remove_contact
CLI: openemail audiences remove-contact

`audiences.add_contacts()`

Put up to 200 existing contacts in an audience in one call

audiences:write

Сигнатура

def add_contacts(    id: str,    body: AudienceContactsBatch,    *,    api_key: str | None = None,    timeout: float | None = None,) -> AudienceBatchAddResource

Adds many contacts to one audience in one transaction and reports what happened to each address. Each address is trimmed and lower cased, a repeat counts once, and each has to be a contact in this workspace already.

Nothing is refused for one address. An address that is not a contact is returned in missing and the others are still added, and a contact that is in the audience already is counted in unchanged and keeps its original addedAt. added counts the contacts that joined in this call.

This never creates a contact. To save new addresses and put them in the audience in the same call, use import_contacts. Adding to the default audience succeeds with 0 in added, since every contact is already in it.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b.
body['emails']list[str]Обязательно: A list of 1 to 200 addresses of contacts already in the workspace book, matched case insensitively. An empty list or more than 200 is a 422 invalid_parameter on emails, and an empty or overlong address is the same error on that entry, such as emails.2.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

AudienceBatchAddResource, a dict with object set to audience_batch, audienceId, added, unchanged and missing. missing lists the addresses that are not contacts, trimmed, lower cased and once each.

Пример

from openemail import openemail result = openemail.audiences.add_contacts(    'aud_9f2c4b7e1a0d63d84c5f2e7b',    {'emails': ['[email protected]', '[email protected]', '[email protected]']},) print(result['added'], result['unchanged']) if result['missing']:    print('Not contacts yet:', result['missing'])

Примечания

Safe to replay: a second call with the same addresses adds nothing and reports them as unchanged. The SDK retries it after a network failure.
Send a longer list in chunks of 200.
audiences:write is the only scope checked. Adding contacts to an audience is not a write to the contacts.
An audience from another workspace is a 404 audience_not_found.

Также доступно в

API: POST /audiences/{id}/contacts/batch
TypeScript: audiences.addContacts()
Ruby: audiences.add_contacts
CLI: openemail audiences add-contacts

`audiences.remove_contacts()`

Take up to 200 contacts out of an audience in one call

audiences:write

Сигнатура

def remove_contacts(    id: str,    body: AudienceContactsBatch,    *,    api_key: str | None = None,    timeout: float | None = None,) -> AudienceBatchRemoveResource

Removes many contacts from one audience in one transaction and reports what happened to each address. Each address is trimmed and lower cased and a repeat counts once. The contacts stay in the address book, in the default audience and in every other audience they are in.

Nothing is refused for one address, which is where this differs from remove_contact. A contact that is not in this audience is returned in notInAudience, an address that is not a contact at all in missing, and the rest are still removed. removed counts the contacts taken out in this call.

The default audience cannot be thinned. The call is refused with 409 audience_immutable on id, because that audience holds every contact by definition. Use contacts.delete when you mean a contact to go.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b. Not the default audience.
body['emails']list[str]Обязательно: A list of 1 to 200 addresses, matched case insensitively. An empty list or more than 200 is a 422 invalid_parameter on emails, and an empty or overlong address is the same error on that entry, such as emails.2.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

AudienceBatchRemoveResource, a dict with object set to audience_batch, audienceId, removed, notInAudience and missing.

Пример

from openemail import openemail result = openemail.audiences.remove_contacts(    'aud_9f2c4b7e1a0d63d84c5f2e7b', {'emails': ['[email protected]', '[email protected]']}) print(result['removed'], 'removed,', len(result['notInAudience']), 'were not in it')

Примечания

Safe to replay, and the SDK retries it after a network failure. A replay after a lost response succeeds and reports the contacts the first call removed under notInAudience, so removed on the retry can read 0.
Send a longer list in chunks of 200. To take everyone out, use empty.
Removing the last contacts leaves the audience in place and empty.

Также доступно в

API: POST /audiences/{id}/contacts/batch-remove
TypeScript: audiences.removeContacts()
Ruby: audiences.remove_contacts
CLI: openemail audiences remove-contacts

`audiences.import_contacts()`

Import up to 500 addresses into an audience, creating contacts as needed

audiences:writecontacts:write

Сигнатура

def import_contacts(    id: str,    body: AudienceImport,    *,    api_key: str | None = None,    timeout: float | None = None,) -> AudienceImportResource

Does what the CSV import on an audience page does, without the file. Each row is an address and an optional name, and the whole call runs in one transaction.

An address that is not a contact yet is saved as one, with source set to manual, and joins the default audience as every new contact does. An address that is a contact already is reused as it stands: its name is kept, and a name sent here only fills one that is empty. Every imported contact ends up in this audience. Importing an address whose contact was deleted brings it back.

A row whose address is not well formed is skipped rather than failing the call. It is counted in skipped and its address is returned in invalid exactly as you sent it, and every other row is still imported. Rows with the same address count once.

Параметры

idstrОбязательно: Audience id such as aud_9f2c4b7e1a0d63d84c5f2e7b. The default audience is accepted and saves the contacts without putting them in any other list.
body['contacts']list[AudienceImportRow]Обязательно: A list of 1 to 500 rows, each a dict such as {'email': '[email protected]', 'name': 'Grace Hopper'}. email is required, at most 320 characters, and trimmed and lower cased. name is optional, at most 200 characters, and used for a new contact or for an existing one whose name is empty. An empty list, more than 500 rows, an empty email or any other key in a row is a 422.
api_keystr: Overrides the client's API key for this call only.
timeoutfloat: 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.

Возвращает

AudienceImportResource, a dict with object set to audience_import, audienceId, created, added, skipped and invalid. created counts new contacts, added the contacts that joined this audience in this call, new and existing together.

Пример

from openemail import openemail result = openemail.audiences.import_contacts(    'aud_9f2c4b7e1a0d63d84c5f2e7b',    {        'contacts': [            {'email': '[email protected]', 'name': 'Grace Hopper'},            {'email': '[email protected]'},            {'email': 'not an address'},        ]    },) print(result['created'], result['added'], result['invalid'])

Примечания

Needs both audiences:write and contacts:write, because it creates contacts as well as memberships. A key without either is refused with 403 insufficient_scope before anything is saved.
Safe to replay: running the same rows again creates nothing twice and adds nothing twice. The SDK retries it after a network failure.
Send a longer list in chunks of 500.
To add contacts that already exist without creating any, use add_contacts, which reports the addresses that are not contacts instead of saving them.

Также доступно в

API: POST /audiences/{id}/import
TypeScript: audiences.importContacts()
Ruby: audiences.import_contacts
CLI: openemail audiences import-contacts