Audiences
Every operation in this group: what it accepts, what it returns and the errors it can answer with.
Operations
A named list of contacts in this workspace. Every contact is in the built-in default audience from the moment it exists, and builtin is what names that row; the rest are yours to make, fill and delete.
Send to one or more audiences with POST /broadcasts. A contact who unsubscribes stays in its audiences with unsubscribedAt set, and later broadcasts skip them. The built-in audience cannot receive a broadcast, because it holds everyone this workspace has ever written to. Deleting an audience drops its memberships and leaves every contact in the book.
GET/audiences
List audiences
The built-in default audience comes first, then the rest newest first, one page at a time. contactCount on each row is counted at the moment of the read, so two reads either side of a create disagree by one.
The default audience is resolved on the first read, so a workspace that has never made an audience still lists exactly one row.
Requires the audiences:read scope.
Query parameters
limitintegerRows per page, 1 to 100.
At least 1At most 100Default25cursorstringAn audience id. Keyset, not offset: pass the previous page's
nextCursor. One that names nothing in this list is a 400invalid_cursor.
Returns
A page of the audiences in this workspace.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.audiences.list()nextmail.audiences.listAll()nextmail.audiences.iterate()- Python
audiences.list()audiences.list_all()audiences.iterate()- Ruby
audiences.listaudiences.list_allaudiences.iterate- PHP
audiences->listaudiences->listAllaudiences->iterate- Go
Audiences.ListAudiences.ListAllAudiences.Iterate- Java
audiences().listaudiences().listAllaudiences().iterate- C#
Audiences.ListAsyncAudiences.ListAllAsyncAudiences.IterateAsync- CLI
openemail audiences list- MCP
listAudiences
POST/audiences
Create an audience
Makes an empty audience. name is trimmed and names are not checked for duplicates, because an audience is addressed by its id.
builtin is never accepted from the body: exactly one row per workspace carries it and the server owns that row.
Requires the audiences:write scope.
Request body
namestringRequiredDisplay name, trimmed, 1 to 120 characters. Not unique.
1 to 120 charactersdescriptionstringWhat the audience is for. Leave it out to create the audience without one.
Can be nullUp to 1000 charactersshowOnPreferencesbooleanWhether the audience is listed, by its name, on the email preferences page the unsubscribe link opens. A member sees there the listed audiences they are in and can leave or rejoin each one. An audience left out of the page stays private, and leaving every listed audience unsubscribes the person from all marketing mail. False unless set.
Defaultfalse
Returns
Created.
Errors
- 422
workspace_limit_reachedwhen the workspace already holds the most audiences it may have.
The errors every operation can return400401403404429500Error catalog
Also available in
GET/audiences/growth
How audiences grew over a window
The numbers behind the growth chart on the Audiences page, in one request: for each audience, how many contacts it holds now, how many of those joined before the window, and when the rest joined, bucketed by grain.
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 later removed does not appear in it at all.
totals.contacts counts each person once. totals.memberships adds the lists up, and the default audience holds every contact, so a person counts once for every list they are in.
Requires the audiences:read scope.
Query parameters
audienceIdsstringComma separated audience ids, at most 50. Leave it out to read every audience in the workspace, the default one included. A repeated id counts once.
Up to 4000 charactersdaysintegerHow far back to look. The window starts at the beginning of its first bucket in the offset you asked for, so the oldest bucket is a whole one, and ends now, so the newest is partial.
At least 1At most 1095Default30minutesintegerThe window in minutes, which wins over
dayswhen both are sent. Use it with anhourorminutegrain to watch an import land.At least 1At most 1576800grainstringHow wide one bucket is, and the shape of its key:
YYYY-MM-DDfor a day,YYYY-MM-DDTHHfor an hour,YYYY-MM-DDTHH:MMfor a minute.One of"minute""hour""day"Default"day"offsetMinutesintegerMinutes east of UTC to cut the buckets in, so a day breaks where the reader's day does rather than at midnight UTC.
At least -840At most 840Default0
Returns
The window and one series per audience. Buckets are sparse.
Errors
- 404
audience_not_foundonaudienceIdswhen an id names no audience in this workspace. Nothing is read.- 422
invalid_parameteronaudienceIdsfor more than 50 ids, ondays,minutesoroffsetMinutesout of range, or on an unknowngrain.
The errors every operation can return400401403429500Error catalog
Also available in
GET/audiences/{id}
Retrieve an audience
The same shape as the list row, with a fresh contactCount. This is the cheap way to watch a count move without pulling the contacts behind it. An audience in another workspace is a 404, never a 403.
Requires the audiences:read scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b.
Returns
The audience.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.audiences.get()- Python
audiences.get()- Ruby
audiences.get- PHP
audiences->get- Go
Audiences.Get- Java
audiences().get- C#
Audiences.GetAsync- CLI
openemail audiences get- MCP
getAudience
PATCH/audiences/{id}
Update an audience
A partial update. The built-in default audience can be renamed and described like any other, and renaming it changes neither builtin nor what it holds. Membership is untouched here.
Requires the audiences:write scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b.
Request body
namestringNew display name, trimmed, 1 to 120 characters.
1 to 120 charactersdescriptionstringNew description. Null clears it.
Can be nullUp to 1000 charactersshowOnPreferencesbooleanWhether the audience is listed, by its name, on the email preferences page the unsubscribe link opens. A member sees there the listed audiences they are in and can leave or rejoin each one. An audience left out of the page stays private, and leaving every listed audience unsubscribes the person from all marketing mail. False unless set.
Returns
Saved.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
DELETE/audiences/{id}
Delete an audience
Deletes the audience and its memberships. The contacts themselves stay in the book, in the default audience, and in any other audience they were in.
Requires the audiences:write scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b. Not the default audience.
Returns
Deleted.
Errors
- 403
The key lacks the scope, or may not send as that address.
step_up_required: the call was made with an OAuth access token that has not been verified in the last 60 minutes. Ask for a code withPOST /security/step-up, send it toPOST /security/step-up/verify, then repeat the call. The person can also choose Allow changes for 60 minutes on the app in Account settings, Connected apps, on the Nextmail website. An API key is never asked for a code.- 409
audience_immutable: the built-in default audience cannot be deleted.
The errors every operation can return400401404422429500Error catalog
Also available in
GET/audiences/{id}/contacts
List an audience's contacts
The contacts themselves rather than membership records, one page at a time, each with addedAt, the date it joined this audience. Every contact in the audience is reachable by following nextCursor, which makes this the way to export an audience. Reading the built-in default audience here returns the whole address book.
audiences:read is the only scope checked, so a key with it reads the addresses in an audience without holding contacts:read.
Requires the audiences:read scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b.
Query parameters
limitintegerRows per page, 1 to 200.
At least 1At most 200Default50cursorstringThe previous page's
nextCursor, never built by hand. Send the sameq,sourceandsortwith it. Keyset, not offset: pass the previous page'snextCursor. One that names nothing in this list is a 400invalid_cursor.qstringNarrows the page to contacts whose name or address matches. When nothing in the audience matches exactly, the search allows for a typo instead, and later pages of the same query keep to the same kind of match.
Up to 200 characterssourcestringNarrows the page to contacts recorded that way.
One of"manual""auto""form"sortstringlast-heard-newestputs the contacts most recently written to first and those never written to last, the order ofGET /contacts.last-heard-oldestreverses it.added-newestandadded-oldestorder byaddedAt, the date each contact joined this audience.nameis alphabetical without case, and a contact with no name sorts by its address.One of"last-heard-newest""last-heard-oldest""added-newest""added-oldest""name"Default"last-heard-newest"statusstring[]Comma-separated.
subscribedkeeps the members who have not unsubscribed,unsubscribedkeeps the ones who have. Leave it out, or name both, for everyone in the audience.One of"subscribed""unsubscribed"
Returns
A page of the contacts in this audience.
Errors
- 400
invalid_cursorwhencursornames no contact in this audience.- 404
audience_not_foundwhen the id names no audience in this workspace.- 422
invalid_parameteron an unknownsort,sourceorstatus, alimitout of range or aqover 200 characters.
The errors every operation can return401403429500Error catalog
Also available in
- TypeScript
nextmail.audiences.listContacts()nextmail.audiences.listAllContacts()nextmail.audiences.iterateContacts()- Python
audiences.list_contacts()audiences.list_all_contacts()audiences.iterate_contacts()- Ruby
audiences.list_contactsaudiences.list_all_contactsaudiences.iterate_contacts- PHP
audiences->listContactsaudiences->listAllContactsaudiences->iterateContacts- Go
Audiences.ListContactsAudiences.ListAllContactsAudiences.IterateContacts- Java
audiences().listContactsaudiences().listAllContactsaudiences().iterateContacts- C#
Audiences.ListContactsAsyncAudiences.ListAllContactsAsyncAudiences.IterateContactsAsync- CLI
openemail audiences list-contacts- MCP
listAudienceContacts
POST/audiences/{id}/contacts
Add a contact to an audience
Takes an address already in the workspace book. Adding one that is already in the audience changes nothing, answers 200 and carries the original addedAt, so a retry is safe.
An address that is not a contact is refused rather than created on the spot. Save it with POST /contacts first. To add many contacts in one call, use POST /audiences/{id}/contacts/batch.
Requires the audiences:write scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b.
Request body
emailstringRequiredAn address already in the workspace book. An unknown address is refused rather than created on the spot.
Up to 320 charactersFormatemail
Returns
The membership, with the contact it points at.
Errors
- 422
contact_not_foundonemailwhen that address is not in the workspace book.
The errors every operation can return400401403404429500Error catalog
Also available in
DELETE/audiences/{id}/contacts/{email}
Remove a contact from an audience
Removes the membership. The contact stays in the book, stays in the default audience and stays in every other audience it was in. A contact that is not in this audience is a 404, so a typo cannot report a removal that never happened.
Requires the audiences:write scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b. Not the default audience.emailstringRequiredThe contact's address, matched case insensitively.
Returns
Removed.
Errors
- 404
audience_not_foundfor theid,contact_not_foundonemailwhen that address is not in the workspace book, oraudience_member_not_foundwhen the contact exists but is not in this audience.- 409
audience_immutable: the built-in default audience holds every contact for as long as it is a contact. Delete the contact to take it out.
The errors every operation can return400401403422429500Error catalog
Also available in
POST/audiences/{id}/contacts/batch
Add many contacts to an audience
Puts up to 200 existing contacts in the audience in one call, in one transaction. It never creates a contact: an address that is not in the workspace book comes back in missing and the rest are still added. To create contacts as you add them, use POST /audiences/{id}/import.
A contact already in the audience is counted in unchanged and keeps its original addedAt, so the call is safe to replay. Adding to the built-in default audience answers added: 0, because every contact is in it already.
Requires the audiences:write scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b.
Request body
emailsstring[]Required1 to 200 addresses. Each is trimmed and lower cased and a repeat counts once. They are looked up in the workspace book as they stand, so an address that is not a contact comes back in
missingrather than refusing the call.1 to 200 items
Returns
What the call added, what was there already and what is not a contact.
Errors
- 404
audience_not_foundwhen the id names no audience in this workspace.- 422
invalid_parameteronemailswhen it is empty or holds more than 200 addresses, and on the entry, such asemails.2, when an address is empty or too long,unknown_parameterfor any other key in the body.
The errors every operation can return400401403429500Error catalog
Also available in
POST/audiences/{id}/contacts/batch-remove
Remove many contacts from an audience
Takes up to 200 contacts out of the audience in one call, in one transaction. The contacts stay in the book, in the default audience and in every other audience they are in.
Nothing is refused for one address: a contact that is not in this audience comes back in notInAudience and an address that is not a contact in missing, and the rest are still removed. A replay therefore succeeds and reports the contacts the first call removed under notInAudience.
Requires the audiences:write scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b. Not the default audience.
Request body
emailsstring[]Required1 to 200 addresses. Each is trimmed and lower cased and a repeat counts once. They are looked up in the workspace book as they stand, so an address that is not a contact comes back in
missingrather than refusing the call.1 to 200 items
Returns
What the call removed, what was not in the audience and what is not a contact.
Errors
- 404
audience_not_foundwhen the id names no audience in this workspace.- 409
audience_immutable: the built-in default audience holds every contact for as long as it is a contact. Delete the contacts to take them out.- 422
invalid_parameteronemailswhen it is empty or holds more than 200 addresses, and on the entry, such asemails.2, when an address is empty or too long,unknown_parameterfor any other key in the body.
The errors every operation can return400401403429500Error catalog
Also available in
POST/audiences/{id}/import
Import contacts into an audience
What the CSV import on an audience page does, without the file: up to 500 rows of an address and an optional name, 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 too. An address that is a contact already is reused as it stands and keeps its name: a name sent here only fills one that is empty. Every imported contact ends up in this audience.
A row whose address is not well formed is skipped and returned in invalid, and the other rows are still imported. Importing an address whose contact was deleted brings it back. Replaying the same rows creates nothing twice, so the call is safe to retry. Send a longer list in several calls.
Requires the audiences:write and contacts:write scopes.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b. The default audience is accepted and saves the contacts without putting them in any other list.
Request body
contactsobject[]Required1 to 500 rows. Send a longer list in several calls. Rows with the same address, compared without case, count as one.
1 to 500 itemsemailstringRequiredTrimmed and lower cased. A row whose address is not well formed is skipped and listed in
invalid, and the other rows are still imported.1 to 320 charactersnamestringTrimmed. Used for a new contact, or for an existing one whose name is empty. A name already saved is kept.
Can be nullUp to 200 charactersattributesRecord<string, string>Custom fields for the contact, as an object of keys and text values, such as the other columns of a CSV file. A key starts with a letter and holds up to 64 letters, digits and underscores, and a value is text of at most 500 characters. A value replaces the field of that name on a new or existing contact, an empty value is ignored, and the fields a row leaves out keep their values. A contact that would pass 50 fields keeps the ones it has.
Can be null
Returns
What the import created, added and skipped.
Errors
- 403
insufficient_scopeunless the key holds bothaudiences:writeandcontacts:write.- 404
audience_not_foundwhen the id names no audience in this workspace.- 422
invalid_parameteroncontactswhen it is empty or holds more than 500 rows, or on a row whoseemailis empty or longer than 320 characters or whosenameis longer than 200,unknown_parameterfor any other key.
The errors every operation can return400401429500Error catalog
Also available in
POST/audiences/{id}/empty
Empty an audience
Takes every contact out of the audience in one transaction and answers with the audience as it now stands, contactCount 0, plus removed, the number of contacts taken out. The audience itself stays, with its name and id, and so does every contact: each one stays in the book, in the default audience and in its other audiences. No body.
There is no undo, so check the audience id before you call this.
Requires the audiences:write scope.
Path parameters
idstringRequiredAudience id such as
aud_9f2c4b7e1a0d63d84c5f2e7b. Not the default audience.
Returns
The audience, now empty.
objectstring- One of
"audience" idstringThe durable handle,
aud_plus 24 hex.namestringdescriptionstring- Can be null
builtinstringWhich built-in audience this row is:
defaultfor the one every contact joins, null for one somebody created. Branch on this rather than on the name, which anybody can change.Can be nullOne of"default"showOnPreferencesbooleanWhether the audience is listed, by its name, on the email preferences page the unsubscribe link opens. A member sees there the listed audiences they are in and can leave or rejoin each one. An audience left out of the page stays private, and leaving every listed audience unsubscribes the person from all marketing mail. False unless set.
contactCountintegerCounted at the moment of the read, never cached.
lastContactAtstringWhen the contact who joined most recently joined this audience, read at the moment of the request. Null while the audience is empty.
Can be nullFormatdate-timecreatedAtstring- Format
date-time updatedAtstring- Format
date-time removedintegerContacts taken out of the audience. 0 when it was empty already.
Errors
- 404
audience_not_foundwhen the id names no audience in this workspace.- 409
audience_immutable: the built-in default audience holds every contact for as long as it is a contact, so it cannot be emptied.
The errors every operation can return400401403422429500Error catalog
Also available in
GET/segments
List segments
Every saved segment of this workspace, newest first. A workspace keeps at most 100.
Requires the audiences:read scope.
Returns
Every segment, newest first.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
- TypeScript
nextmail.segments.list()- Python
segments.list()- Ruby
segments.list- PHP
segments->list- Go
Segments.List- Java
segments().list- C#
Segments.ListAsync- CLI
openemail segments list- MCP
listSegments
POST/segments
Create a segment
Saves a set of conditions under a name, to narrow a broadcast with segmentId on POST /broadcasts. A segment holds no contacts of its own: who matches is worked out each time it is read, so a contact who opens an email today can match a segment tomorrow. Each condition names a field and an operator: email (is, is_not, contains, not_contains, ends_with), name (is, is_not, contains, not_contains, is_set, is_not_set), source (is, is_not), created (within_days, not_within_days), audience (in, not_in), opened (within_days, not_within_days), clicked (within_days, not_within_days), engaged (within_days, not_within_days), event (within_days, not_within_days), attribute (is, is_not, contains, not_contains, is_set, is_not_set). Text is compared without regard to case, and value holds what it is compared with. source compares how the contact was added. created, opened, clicked and engaged take days: when the contact was added, the last time they opened or clicked a tracked email from this workspace, and the later of those two. A contact who never opened has not opened within any number of days. audience takes audienceId and counts only subscribed members. event takes event, a name recorded with POST /events, and days. attribute takes key, the name of a custom field on the contact.
Requires the audiences:write scope.
Request body
namestringRequiredWhat the segment is called in the apps, such as Opened in the last 90 days.
1 to 120 charactersdescriptionstringA longer note for the people who use it.
Can be nullUp to 500 charactersdefinitionobjectRequiredThe conditions.
matchisall(the default) when a contact has to meet every condition, oranywhen one is enough, andconditionsholds 1 to 20 of them. Each condition names afieldand anoperator:email(is,is_not,contains,not_contains,ends_with),name(is,is_not,contains,not_contains,is_set,is_not_set),source(is,is_not),created(within_days,not_within_days),audience(in,not_in),opened(within_days,not_within_days),clicked(within_days,not_within_days),engaged(within_days,not_within_days),event(within_days,not_within_days),attribute(is,is_not,contains,not_contains,is_set,is_not_set). Text is compared without regard to case, andvalueholds what it is compared with.sourcecompares how the contact was added.created,opened,clickedandengagedtakedays: when the contact was added, the last time they opened or clicked a tracked email from this workspace, and the later of those two. A contact who never opened has not opened within any number of days.audiencetakesaudienceIdand counts only subscribed members.eventtakesevent, a name recorded withPOST /events, anddays.attributetakeskey, the name of a custom field on the contact. At most 20 conditions.matchstring- One of
"all""any"Default"all" conditionsobject[]Required- 1 to 20 items
fieldstringRequired- One of
"email""name""source""created""audience""opened""clicked""engaged""event""attribute" operatorstringRequired- One of
"is""is_not""contains""not_contains""ends_with""is_set""is_not_set""within_days""not_within_days""in""not_in" valuestring- 1 to 320 characters
daysinteger- At least 1At most 3650
audienceIdstring- 1 to 64 characters
eventstring- 1 to 100 characters
keystring- 1 to 64 characters
Returns
The segment. The Location header names it.
Errors
- 404
audience_not_foundwhen an audience condition names an audience this workspace does not have.- 409
segment_limit_reached: the workspace already keeps 100 segments.- 422
invalid_parameterorunknown_parameteron a condition that does not validate, such as an operator its field does not take.
The errors every operation can return400401403429500Error catalog
Also available in
POST/segments/preview
Preview a segment
Counts the contacts a set of conditions matches now, without saving anything, and returns a few of them. With audienceIds, only subscribed members of those audiences count. A condition on a custom field reads every contact it checks, up to 20000, and answers segment_too_large beyond that.
Requires the audiences:read scope.
Request body
definitionobjectRequiredThe conditions.
matchisall(the default) when a contact has to meet every condition, oranywhen one is enough, andconditionsholds 1 to 20 of them. Each condition names afieldand anoperator:email(is,is_not,contains,not_contains,ends_with),name(is,is_not,contains,not_contains,is_set,is_not_set),source(is,is_not),created(within_days,not_within_days),audience(in,not_in),opened(within_days,not_within_days),clicked(within_days,not_within_days),engaged(within_days,not_within_days),event(within_days,not_within_days),attribute(is,is_not,contains,not_contains,is_set,is_not_set). Text is compared without regard to case, andvalueholds what it is compared with.sourcecompares how the contact was added.created,opened,clickedandengagedtakedays: when the contact was added, the last time they opened or clicked a tracked email from this workspace, and the later of those two. A contact who never opened has not opened within any number of days.audiencetakesaudienceIdand counts only subscribed members.eventtakesevent, a name recorded withPOST /events, anddays.attributetakeskey, the name of a custom field on the contact.matchstring- One of
"all""any"Default"all" conditionsobject[]Required- 1 to 20 items
fieldstringRequired- One of
"email""name""source""created""audience""opened""clicked""engaged""event""attribute" operatorstringRequired- One of
"is""is_not""contains""not_contains""ends_with""is_set""is_not_set""within_days""not_within_days""in""not_in" valuestring- 1 to 320 characters
daysinteger- At least 1At most 3650
audienceIdstring- 1 to 64 characters
eventstring- 1 to 100 characters
keystring- 1 to 64 characters
audienceIdsstring[]Up to 10 audiences. Only their subscribed members count. Left out, every contact counts.
Up to 10 items
Returns
The count and a sample. Nothing was saved.
Errors
- 404
audience_not_foundonaudienceIdsor an audience condition.- 422
segment_too_large, orinvalid_parameteron a condition that does not validate.
The errors every operation can return400401403429500Error catalog
Also available in
GET/segments/{id}
Get a segment
One segment, with its conditions.
Requires the audiences:read scope.
Path parameters
idstringRequiredThe
seg_id of the segment.
Returns
The segment.
Errors
The errors every operation can return400401403422429500Error catalog
Also available in
- TypeScript
nextmail.segments.get()- Python
segments.get()- Ruby
segments.get- PHP
segments->get- Go
Segments.Get- Java
segments().get- C#
Segments.GetAsync- CLI
openemail segments get- MCP
getSegment
PATCH/segments/{id}
Update a segment
Changes the name, the description or the conditions. Sending definition replaces every condition. A broadcast already sent or scheduled keeps the conditions it was given.
Requires the audiences:write scope.
Path parameters
idstringRequiredThe
seg_id of the segment.
Request body
namestringA new name, 1 to 120 characters.
1 to 120 charactersdescriptionstringA longer note. Null takes it away.
Can be nullUp to 500 charactersdefinitionobjectNew conditions, replacing the old ones. The conditions.
matchisall(the default) when a contact has to meet every condition, oranywhen one is enough, andconditionsholds 1 to 20 of them. Each condition names afieldand anoperator:email(is,is_not,contains,not_contains,ends_with),name(is,is_not,contains,not_contains,is_set,is_not_set),source(is,is_not),created(within_days,not_within_days),audience(in,not_in),opened(within_days,not_within_days),clicked(within_days,not_within_days),engaged(within_days,not_within_days),event(within_days,not_within_days),attribute(is,is_not,contains,not_contains,is_set,is_not_set). Text is compared without regard to case, andvalueholds what it is compared with.sourcecompares how the contact was added.created,opened,clickedandengagedtakedays: when the contact was added, the last time they opened or clicked a tracked email from this workspace, and the later of those two. A contact who never opened has not opened within any number of days.audiencetakesaudienceIdand counts only subscribed members.eventtakesevent, a name recorded withPOST /events, anddays.attributetakeskey, the name of a custom field on the contact.matchstring- One of
"all""any"Default"all" conditionsobject[]Required- 1 to 20 items
fieldstringRequired- One of
"email""name""source""created""audience""opened""clicked""engaged""event""attribute" operatorstringRequired- One of
"is""is_not""contains""not_contains""ends_with""is_set""is_not_set""within_days""not_within_days""in""not_in" valuestring- 1 to 320 characters
daysinteger- At least 1At most 3650
audienceIdstring- 1 to 64 characters
eventstring- 1 to 100 characters
keystring- 1 to 64 characters
Returns
The segment as it is now.
Errors
- 404
segment_not_found, oraudience_not_foundon an audience condition.- 422
invalid_parameterorunknown_parameteron a field that does not validate.
The errors every operation can return400401403429500Error catalog
Also available in
DELETE/segments/{id}
Delete a segment
Deletes the segment. No contact is touched, and a broadcast already sent or scheduled keeps the conditions it was given. A draft that still names it is refused when it is sent, until it names another one or none.
Requires the audiences:write scope.
Path parameters
idstringRequiredThe
seg_id of the segment.
Returns
The segment is gone.
Errors
The errors every operation can return400401403422429500Error catalog
Also available in
Objects
Audienceobject
objectstring- One of
"audience" idstringThe durable handle,
aud_plus 24 hex.namestringdescriptionstring- Can be null
builtinstringWhich built-in audience this row is:
defaultfor the one every contact joins, null for one somebody created. Branch on this rather than on the name, which anybody can change.Can be nullOne of"default"showOnPreferencesbooleanWhether the audience is listed, by its name, on the email preferences page the unsubscribe link opens. A member sees there the listed audiences they are in and can leave or rejoin each one. An audience left out of the page stays private, and leaving every listed audience unsubscribes the person from all marketing mail. False unless set.
contactCountintegerCounted at the moment of the read, never cached.
lastContactAtstringWhen the contact who joined most recently joined this audience, read at the moment of the request. Null while the audience is empty.
Can be nullFormatdate-timecreatedAtstring- Format
date-time updatedAtstring- Format
date-time
AudienceBatchAddobject
objectstring- One of
"audience_batch" audienceIdstringaddedintegerContacts that joined the audience in this call.
unchangedintegerContacts that were in the audience already. Their
addedAtis kept.missingstring[]The addresses that are not contacts in this workspace, trimmed, lower cased and listed once each. Nothing is created for them. Save them with
POST /contacts, or usePOST /audiences/{id}/import, which creates contacts as it goes.
AudienceBatchRemoveobject
objectstring- One of
"audience_batch" audienceIdstringremovedintegerContacts taken out of the audience in this call.
notInAudiencestring[]Addresses of contacts that exist but were not in this audience, so there was nothing to remove for them.
missingstring[]The addresses that are not contacts in this workspace, trimmed, lower cased and listed once each. Nothing is created for them. Save them with
POST /contacts, or usePOST /audiences/{id}/import, which creates contacts as it goes.
AudienceContactobject
objectstring- One of
"contact" emailstringTrimmed and lower cased on write. This is the key every contact route takes, because no contact id is exposed.
namestring- Can be null
sourcestringautowhen a send from the app composer recorded the address,manualwhen somebody saved it here or in the app. A recorded send never downgrades amanualcontact toauto.One of"manual""auto""form"notesstring- Can be null
attributesRecord<string, string>The custom fields of the contact, as an object of keys and text values, at most 50 of them. Empty when it has none. An automation reads one as
attributes.<key>, in an email value, a branch or a trigger filter, and itsupdate_fieldstep writes one.photoUrlstringWhere the contact photo is served, or null when the contact has none. Set it with
PUT /contacts/{email}/photo. A new upload gets a new URL.Can be nulllastSeenAtstringWhen mail last went to this address from the app composer. Null until it does.
Can be nullFormatdate-timecreatedAtstring- Format
date-time updatedAtstring- Format
date-time addedAtstringWhen the contact joined this audience. The
added-newestandadded-oldestsorts order by it, and a repeated add keeps the original date.Formatdate-timeunsubscribedAtstringWhen the contact followed the unsubscribe link in a broadcast sent to this audience, or null while it is subscribed. An unsubscribed contact stays in the audience and in the book, and broadcasts to this audience skip it. Removing it from the audience and adding it back makes a fresh, subscribed membership. Mail sent to it one message at a time is not affected.
Can be nullFormatdate-time
AudienceContactListobject
objectstring- One of
"list" hasMorebooleannextCursorstring- Can be null
audienceIdstring
AudienceGrowthobject
objectstring- One of
"audience_growth" sincestringThe start of the window, floored to the start of its first bucket in the local time of
offsetMinutes.Formatdate-timeuntilstringThe end of the window, which is the moment of the read.
Formatdate-timegrainstring- One of
"minute""hour""day" offsetMinutesintegerThe offset the buckets were cut in, as sent or 0.
totalsobjectcontactsintegerDistinct contacts across the audiences read, each counted once however many of them it is in.
subscribedintegerOf those, the contacts still subscribed to at least one of the audiences read, so a broadcast to them would reach them.
membershipsintegerThe series
totalvalues added up. The default audience holds every contact, so a contact in two other audiences counts three times here.addedintegerJoins inside the window across every series.
unsubscribedintegerUnsubscribes inside the window across every series.
listsintegerHow many audiences were read.
busieststringThe bucket key with the most joins across every series, the earliest one on a tie, or null when nobody joined in the window.
Can be null
seriesobject[]One per audience read, the largest first and then by name.
idstringThe audience id.
namestringbuiltinbooleanTrue for the default audience, the one that holds every contact. A boolean here, where the audience object carries the
builtinkind.totalintegerContacts in the audience now.
subscribedintegerOf those, the contacts still subscribed. The rest unsubscribed and are skipped by broadcasts.
beforeintegerOf those, the contacts that joined before
since.addedintegerOf those, the contacts that joined inside the window. With
beforeit makes uptotal.unsubscribedintegerContacts that unsubscribed from the audience inside the window.
bucketsobject[]SPARSE, oldest first. Only buckets in which somebody joined or unsubscribed are listed, so a chart has to fill the gaps with zero itself.
bucketstringThe bucket's key in the local time of
offsetMinutes:YYYY-MM-DDfor a day,YYYY-MM-DDTHHfor an hour,YYYY-MM-DDTHH:MMfor a minute.addedintegerContacts that joined the audience in that bucket and are still in it.
unsubscribedintegerContacts that unsubscribed from the audience in that bucket, through a broadcast unsubscribe link.
AudienceImportobject
objectstring- One of
"audience_import" audienceIdstringcreatedintegerAddresses that were not contacts yet and were saved as new ones, with
sourceset tomanual.addedintegerContacts that joined this audience in this call, new and existing together. A contact already in it is not counted.
skippedintegerRows that were not imported because the address is not well formed.
invalidstring[]The addresses of the skipped rows, exactly as they were sent.
AudienceListobject
objectstring- One of
"list" dataAudience[]hasMorebooleannextCursorstring- Can be null
AudienceMemberobject
objectstring- One of
"audience_member" audienceIdstringaddedAtstringWhen the contact first joined this audience. A repeat add answers with the original date rather than a new one.
Formatdate-timecontactContact
Contactobject
objectstring- One of
"contact" emailstringTrimmed and lower cased on write. This is the key every contact route takes, because no contact id is exposed.
namestring- Can be null
sourcestringautowhen a send from the app composer recorded the address,manualwhen somebody saved it here or in the app. A recorded send never downgrades amanualcontact toauto.One of"manual""auto""form"notesstring- Can be null
attributesRecord<string, string>The custom fields of the contact, as an object of keys and text values, at most 50 of them. Empty when it has none. An automation reads one as
attributes.<key>, in an email value, a branch or a trigger filter, and itsupdate_fieldstep writes one.photoUrlstringWhere the contact photo is served, or null when the contact has none. Set it with
PUT /contacts/{email}/photo. A new upload gets a new URL.Can be nulllastSeenAtstringWhen mail last went to this address from the app composer. Null until it does.
Can be nullFormatdate-timecreatedAtstring- Format
date-time updatedAtstring- Format
date-time
DeletedAudienceobject
objectstringRequired- One of
"audience" idstringRequireddeletedbooleanRequired- One of
true
DeletedSegmentobject
objectstringRequired- One of
"segment" idstringRequireddeletedbooleanRequired- One of
true
RemovedAudienceMemberobject
objectstringRequired- One of
"audience_member" audienceIdstringRequiredemailstringRequired- Format
email deletedbooleanRequired- One of
true
Segmentobject
objectstringRequired- One of
"segment" idstringRequiredThe
seg_id.namestringRequireddescriptionstringRequired- Can be null
definitionobjectRequiredThe conditions.
matchisall(the default) when a contact has to meet every condition, oranywhen one is enough, andconditionsholds 1 to 20 of them. Each condition names afieldand anoperator:email(is,is_not,contains,not_contains,ends_with),name(is,is_not,contains,not_contains,is_set,is_not_set),source(is,is_not),created(within_days,not_within_days),audience(in,not_in),opened(within_days,not_within_days),clicked(within_days,not_within_days),engaged(within_days,not_within_days),event(within_days,not_within_days),attribute(is,is_not,contains,not_contains,is_set,is_not_set). Text is compared without regard to case, andvalueholds what it is compared with.sourcecompares how the contact was added.created,opened,clickedandengagedtakedays: when the contact was added, the last time they opened or clicked a tracked email from this workspace, and the later of those two. A contact who never opened has not opened within any number of days.audiencetakesaudienceIdand counts only subscribed members.eventtakesevent, a name recorded withPOST /events, anddays.attributetakeskey, the name of a custom field on the contact.matchstring- One of
"all""any"Default"all" conditionsobject[]Required- 1 to 20 items
fieldstringRequired- One of
"email""name""source""created""audience""opened""clicked""engaged""event""attribute" operatorstringRequired- One of
"is""is_not""contains""not_contains""ends_with""is_set""is_not_set""within_days""not_within_days""in""not_in" valuestring- 1 to 320 characters
daysinteger- At least 1At most 3650
audienceIdstring- 1 to 64 characters
eventstring- 1 to 100 characters
keystring- 1 to 64 characters
createdAtstringRequired- Format
date-time updatedAtstringRequired- Format
date-time
SegmentListobject
objectstring- One of
"list" dataSegment[]hasMorebooleanAlways false: the list is never paged.
nextCursorstringAlways null.
Can be null
SegmentPreviewobject
objectstringRequired- One of
"segment_preview" audienceIdsstring[]RequiredThe audiences the count was limited to, as sent, or empty for every contact.
contactsintegerRequiredHow many contacts match the conditions now.
sampleobject[]RequiredUp to 10 of the contacts that match.
idstringRequiredemailstringRequirednamestringRequired- Can be null