Sending to audiences
One email to everybody in one or more audiences, a separate copy for each person.
Sending to audiences tools
| Tool | What it does |
|---|---|
| previewAudienceSend | How many people a send to these audiences would reach, before anything is sent, with how many would be skipped because they unsubscribed and how many because their address is suppressed. A person in several of the audiences counts once. |
| sendToAudience | Send one email from one of your addresses to everybody in up to 10 audiences, each person getting a copy of their own. It takes html or text with merge fields such as {{firstName|there}}, or a template, and an optional time to send. It answers at once and the sending goes on in the background. All contacts cannot be one of the audiences. |
| listBroadcasts | The sends to audiences from this mailbox, newest first, with how far each one got, a page at a time. Name an audience to see only the sends that included it. |
| getBroadcast | One send and how far it got: how many people it was for, and how many copies are waiting, sent, failed or cancelled, and how many people were skipped. |
| listBroadcastRecipients | Everybody one send went to, one line each: the copy, its status, when it was sent and delivered, whether it bounced or was reported as spam, how often it was opened and clicked, and whether the person unsubscribed through it. Keep one group, such as the bounced or the never opened, or search by address or name. |
| getBroadcastRecipient | One person's copy of a send: what happened to it, and the subject and text exactly as that person received them, with the merge fields filled in. |
| getBroadcastStats | How one send performed: how many copies were sent, delivered, bounced, reported as spam or failed, how many people opened, clicked and unsubscribed, and the same by minute, hour or day. Give it a window to also count what happened lately. |
| getBroadcastAnalytics | How the sends over a window did, added up and by minute, hour or day, with one line per send to compare them. Name some sends to add up only those. |
| cancelBroadcast | Stop a send. Every copy that has not gone yet is cancelled and nobody else is added. Copies already sent cannot be recalled. |
| createBroadcastDraft | Save a send to audiences as a draft without sending it. The audiences can be left for later, and nothing counts against the plan until it is sent. |
| updateBroadcast | Change a draft, or a scheduled send that has not started: its audiences, the audiences left out, its subject and body, its campaign tags or its time. |
| sendBroadcastDraft | Send a draft to its audiences now, or schedule it. It is checked like a new send before anything goes out. |
| duplicateBroadcast | Copy any send into a new draft with the same sender, audiences and content, ready to change and send again. |
| resendBroadcast | Send a finished send again, as a new one, to the people it reached who have not opened it, under a new subject if you like. |
| sendBroadcastTest | Send a test copy to yourself or up to five addresses before it goes out. The subject starts with [Test] and nobody joins an audience. |
| listSegments | The saved segments of the workspace, newest first. A segment is a set of conditions on contacts that narrows a send to the people who match. |
| getSegment | One segment, with each of its conditions. |
| createSegment | Save a segment: a name and the conditions a contact has to meet, such as opened in the last 90 days, joined an audience, did an event or has a custom field set to a value. |
| updateSegment | Rename a segment or change its conditions. A send already on its way keeps the conditions it was given. |
| deleteSegment | Delete a segment. No contact is touched, and a send already on its way keeps the conditions it was given. |
| previewSegment | Count the contacts a segment matches now, with a few of them, before saving or sending anything. |
Every copy is an ordinary email addressed to one person, so nobody sees who else it went to, and each one has its own tracking and webhooks. The copies are not filed in Sent: the send is the record. getBroadcast follows it as a whole, getBroadcastStats adds up how it did, and listBroadcastRecipients and getBroadcastRecipient show what happened to each person's copy.
The merge fields are {{firstName}}, {{lastName}}, {{name}}, {{email}} and {{unsubscribeUrl}}, each with an optional fallback after a bar. A custom field of the contact is {{attributes.<key>}}, such as {{attributes.plan|Free}}. Every copy carries a one-click unsubscribe header, and a body or a template that does not place {{unsubscribeUrl}} itself gets a short unsubscribe footer, with the postal address of the workspace once one is set. Somebody who unsubscribes is off all of the marketing mail of the workspace, and later sends skip them, as they skip addresses on the suppression list.
The whole send is checked against the plan before anything goes out, so a send the plan cannot cover is refused rather than stopped half way. Nothing makes a repeated sendToAudience safe, so after a lost answer read listBroadcasts before trying again.
sendToAudience needs emails:send and audiences:read, previewAudienceSend needs audiences:read, listBroadcasts, getBroadcast, listBroadcastRecipients, getBroadcastRecipient, getBroadcastStats and getBroadcastAnalytics need emails:read, and cancelBroadcast needs emails:send. The assistant in the app always asks before sendToAudience, and asks before cancelBroadcast unless you asked for it. Somebody whose access is limited to some addresses sends only to the contacts they added, and sees, follows and cancels only the sends from an address they may send as. The workspace owner, connected with such a limit, sends to every contact but still reaches only the sends from those addresses.
A send can leave out the members of other audiences, such as the customers who already bought, and can add campaign tags such as utm_source to every link. createBroadcastDraft, updateBroadcast, duplicateBroadcast, sendBroadcastDraft and resendBroadcast need emails:send and audiences:read, and sendBroadcastTest needs emails:send. The assistant in the app always asks before sendBroadcastDraft, resendBroadcast and sendBroadcastTest, and asks before the other three unless you asked for them.
Pass a segment as segmentId to sendToAudience, createBroadcastDraft, updateBroadcast or previewAudienceSend to send only to the people in the audiences who match it. Its conditions are read when the send starts or is scheduled. listSegments, getSegment and previewSegment need audiences:read, and createSegment, updateSegment and deleteSegment need audiences:write. The assistant in the app always asks before deleteSegment, and asks before createSegment and updateSegment unless you asked for them.
Pass abTest to sendToAudience, createBroadcastDraft or updateBroadcast to try 2 to 4 versions of the subject or the body on a share of the people first. Once the wait is over, the version with the highest share of opens, or of clicks, goes to everybody else. getBroadcastStats shows how each version did, the most clicked links, the email apps and the countries.
Reference
previewAudienceSend
How many people a send to these audiences would reach, before sending anything. A person in several of the audiences is counted once. Recipients excludes contacts who unsubscribed and addresses suppressed after a bounce or complaint; both are counted separately. All contacts, the built-in audience of everyone the workspace has written to, cannot receive a broadcast and is refused.
Inputs
audienceIdsstring[]Required- 1 to 10 items
excludeAudienceIdsstring[]Audiences whose members are left out of the count.
Up to 10 itemssegmentIdstringA saved segment id (seg_...) that narrows the audiences: only the contacts that match its conditions get a copy. listSegments shows them.
1 to 64 characters
Also available in
sendToAudience
Send one email to every contact in one or more audiences. Each person gets their own copy, so nobody sees anybody else. Personalise with {{firstName}}, {{lastName}}, {{name}}, {{email}} and {{unsubscribeUrl}}, and give a fallback after a bar: {{firstName|there}}. A custom field of the contact is {{attributes.<key>}} in the subject and an html or text body, such as {{attributes.plan|Free}}, and reads as its fallback, or nothing, when the contact has no such field. Every copy carries a one-click unsubscribe header, and a short unsubscribe line is added at the end of an html or text body that does not place {{unsubscribeUrl}} itself. A template gets the same values as props, for the props it declares. Give html or text, or a template id, never both. The send is queued and goes out in the background; getBroadcast reports progress and cancelBroadcast stops what has not gone out yet. Contacts who unsubscribed and suppressed addresses are skipped. All contacts, the built-in audience of everyone the workspace has written to, is refused: send to an audience people joined. The whole send is checked against the plan before anything goes out, so a send the plan cannot cover is refused rather than stopped half way. scheduledAt takes an ISO-8601 time or a duration such as PT2H. Nothing is filed in Sent for each person; the broadcast is the record.
Inputs
audienceIdsstring[]Required- 1 to 10 items
fromstringRequired- 3 to 320 characters
subjectstring- Up to 998 characters
htmlstring- Up to 1000000 characters
textstring- Up to 1000000 characters
templateIdstring- 1 to 128 characters
templateVersioninteger- More than 0
propsRecord<string, any>slotsRecord<string, any>Values for the template's slots, the parts its layout leaves for each send.
replyTostring- Up to 320 characters
scheduledAtstring- Up to 64 characters
trackOpensbooleantrackClicksbooleantagsRecord<string, string>Up to 8 tags of your own, copied onto every copy beside broadcast_id.
excludeAudienceIdsstring[]Audiences whose members are left out, even when they are in one of audienceIds.
Up to 10 itemssegmentIdstringA saved segment id (seg_...) that narrows the audiences: only the contacts that match its conditions get a copy. listSegments shows them.
1 to 64 charactersutmobjectCampaign tags added to the links, such as { source, medium, campaign }.
sourcestring- 1 to 100 characters
mediumstring- 1 to 100 characters
campaignstring- 1 to 200 characters
termstring- 1 to 100 characters
contentstring- 1 to 100 characters
abTestobjectAn A/B test: 2 to 4 variants, each a subject or a body (html or text) that replaces the broadcast's own ({} keeps it), testPercent of the people (5 to 50, 20 unless set) split evenly between them, metric (opens or clicks) to pick the winner, and waitMinutes (30 to 4320, 240 unless set) to wait before picking it. Everybody else then gets the winning variant. A template broadcast can only vary the subject.
variantsobject[]Required- 2 to 4 items
subjectstring- 1 to 998 characters
htmlstring- 1 to 1000000 characters
textstring- 1 to 1000000 characters
testPercentinteger- At least 5At most 50Default
20 metricstring- One of
"opens""clicks"Default"opens" waitMinutesinteger- At least 30At most 4320Default
240
Also available in
listBroadcasts
The sends to audiences made from this mailbox, newest first, with how far each got. Pass audienceId to see the sends to one audience. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.
Inputs
audienceIdstring- 1 to 64 characters
limitinteger- At least 1At most 100
cursorstring
Also available in
- API
GET /broadcasts- TypeScript
nextmail.broadcasts.list()nextmail.broadcasts.listAll()nextmail.broadcasts.iterate()- Python
broadcasts.list()broadcasts.list_all()broadcasts.iterate()- Ruby
broadcasts.listbroadcasts.list_allbroadcasts.iterate- PHP
broadcasts->listbroadcasts->listAllbroadcasts->iterate- Go
Broadcasts.ListBroadcasts.ListAllBroadcasts.Iterate- Java
broadcasts().listbroadcasts().listAllbroadcasts().iterate- C#
Broadcasts.ListAsyncBroadcasts.ListAllAsyncBroadcasts.IterateAsync
getBroadcast
One send to an audience and how far it got: how many people it was for, how many copies are queued, sent, failed or cancelled, and how many contacts were skipped because they unsubscribed or are suppressed.
Inputs
broadcastIdstringRequired- 1 to 64 characters
Also available in
listBroadcastRecipients
Everybody one send to an audience went to, one line each: the copy id, its status, when it was sent and delivered, whether it bounced or was reported as spam, how often it was opened and clicked, and whether the person unsubscribed through it. filter keeps pending, sent, delivered, opened, not_opened, clicked, bounced, complained, failed or unsubscribed; q searches the address and the name. Sorted by address.
Inputs
broadcastIdstringRequired- 1 to 64 characters
filterstring- One of
"pending""sent""delivered""opened""not_opened""clicked""bounced""complained""failed""unsubscribed" qstring- Up to 200 characters
limitinteger- At least 1At most 100
cursorstring
Also available in
- API
GET /broadcasts/{id}/recipients- TypeScript
nextmail.broadcasts.listRecipients()nextmail.broadcasts.listAllRecipients()nextmail.broadcasts.iterateRecipients()- Python
broadcasts.list_recipients()broadcasts.list_all_recipients()broadcasts.iterate_recipients()- Ruby
broadcasts.list_recipientsbroadcasts.list_all_recipientsbroadcasts.iterate_recipients- PHP
broadcasts->listRecipientsbroadcasts->listAllRecipientsbroadcasts->iterateRecipients- Go
Broadcasts.ListRecipientsBroadcasts.ListAllRecipientsBroadcasts.IterateRecipients- Java
broadcasts().listRecipientsbroadcasts().listAllRecipientsbroadcasts().iterateRecipients- C#
Broadcasts.ListRecipientsAsyncBroadcasts.ListAllRecipientsAsyncBroadcasts.IterateRecipientsAsync
getBroadcastRecipient
One person's copy of a send to an audience, from listBroadcastRecipients by its copy id: what happened to it, and the subject and text exactly as that person received them, merge fields filled in.
Inputs
broadcastIdstringRequired- 1 to 64 characters
emailIdstringRequired- 1 to 64 characters
Also available in
getBroadcastStats
How one send to an audience performed: how many copies were sent, delivered, bounced, reported as spam or failed, how many people opened, clicked and unsubscribed, and the same per hour or per day (grain). offsetMinutes is the reader's offset from UTC. Pass days or minutes (minutes wins) to also count what happened lately: the window line then counts the copies delivered, bounced, reported, opened, clicked and unsubscribed inside it, and the per bucket lines keep only its buckets. It also lists the links clicked most, the mail clients and countries people opened from, and for an A/B test how each variant did and which one won.
Inputs
broadcastIdstringRequired- 1 to 64 characters
grainstring- One of
"minute""hour""day" offsetMinutesinteger- At least -840At most 840
daysinteger- At least 1At most 1095
minutesinteger- At least 1At most 1576800
Also available in
getBroadcastAnalytics
How the sends to audiences did over a window that ends now, the Analytics tab of the Broadcasts page: copies sent, delivered, bounced, reported as spam and failed, and people who opened, clicked and unsubscribed, added up and per day, hour or minute (grain), then one line per send so they can be compared. A copy counts when it was sent inside the window, with everything that happened to it since. Pass broadcastIds to add up only some sends; the per send lines always list every send in the window. days reaches back from 1 to 1095 (30 by default), minutes sets a shorter window and wins over days, and offsetMinutes is the reader's offset from UTC. Test sends are left out.
Inputs
broadcastIdsstring[]- Up to 50 items
daysinteger- At least 1At most 1095
minutesinteger- At least 1At most 1576800
grainstring- One of
"minute""hour""day" offsetMinutesinteger- At least -840At most 840
Also available in
cancelBroadcast
Stop a send to an audience. Copies that have not gone out yet are cancelled, and nobody else is added. Copies already sent cannot be recalled.
Inputs
broadcastIdstringRequired- 1 to 64 characters
Also available in
createBroadcastDraft
Save a send to audiences as a draft, without sending it. Nothing goes out and nothing counts against the plan. updateBroadcast changes it, sendBroadcastTest sends a test copy, and sendBroadcastDraft sends or schedules it. Takes the same fields as sendToAudience, but audienceIds may be left out until later. Each person gets their own copy, so nobody sees anybody else. Personalise with {{firstName}}, {{lastName}}, {{name}}, {{email}} and {{unsubscribeUrl}}, and give a fallback after a bar: {{firstName|there}}. A custom field of the contact is {{attributes.<key>}} in the subject and an html or text body, such as {{attributes.plan|Free}}, and reads as its fallback, or nothing, when the contact has no such field. Every copy carries a one-click unsubscribe header, and a short unsubscribe line is added at the end of an html or text body that does not place {{unsubscribeUrl}} itself. A template gets the same values as props, for the props it declares.
Inputs
fromstringRequired- 3 to 320 characters
audienceIdsstring[]- Up to 10 items
replyTostring- Up to 320 characters
utmobjectCampaign tags added to the links, such as { source, medium, campaign }.
sourcestring- 1 to 100 characters
mediumstring- 1 to 100 characters
campaignstring- 1 to 200 characters
termstring- 1 to 100 characters
contentstring- 1 to 100 characters
segmentIdstringA saved segment id (seg_...) that narrows the audiences: only the contacts that match its conditions get a copy. listSegments shows them.
1 to 64 characterssubjectstring- Up to 998 characters
htmlstring- Up to 1000000 characters
textstring- Up to 1000000 characters
templateIdstring- 1 to 128 characters
templateVersioninteger- More than 0
propsRecord<string, any>slotsRecord<string, any>Values for the template's slots, the parts its layout leaves for each send.
trackOpensbooleantrackClicksbooleantagsRecord<string, string>Up to 8 tags of your own, copied onto every copy beside broadcast_id.
excludeAudienceIdsstring[]Audiences whose members are left out, even when they are in one of audienceIds.
Up to 10 itemsabTestobjectAn A/B test: 2 to 4 variants, each a subject or a body (html or text) that replaces the broadcast's own ({} keeps it), testPercent of the people (5 to 50, 20 unless set) split evenly between them, metric (opens or clicks) to pick the winner, and waitMinutes (30 to 4320, 240 unless set) to wait before picking it. Everybody else then gets the winning variant. A template broadcast can only vary the subject.
Can be nullvariantsobject[]Required- 2 to 4 items
subjectstring- 1 to 998 characters
htmlstring- 1 to 1000000 characters
textstring- 1 to 1000000 characters
testPercentinteger- At least 5At most 50Default
20 metricstring- One of
"opens""clicks"Default"opens" waitMinutesinteger- At least 30At most 4320Default
240
Also available in
updateBroadcast
Change a draft, or a scheduled send to audiences that has not started. Only the fields given change. Giving html, text or templateId replaces the body as a whole. replyTo and utm take null to remove them. scheduledAt moves a scheduled send; a draft is scheduled with sendBroadcastDraft instead. A send that is queued, going out or finished cannot be changed.
Inputs
broadcastIdstringRequired- 1 to 64 characters
fromstring- 3 to 320 characters
audienceIdsstring[]- Up to 10 items
replyTostring- Can be nullUp to 320 characters
utmobject- Can be null
sourcestring- 1 to 100 characters
mediumstring- 1 to 100 characters
campaignstring- 1 to 200 characters
termstring- 1 to 100 characters
contentstring- 1 to 100 characters
segmentIdstringA saved segment id (seg_...) that narrows the audiences: only the contacts that match its conditions get a copy. listSegments shows them. null takes it away.
Can be null1 to 64 charactersscheduledAtstring- Up to 64 characters
subjectstring- Up to 998 characters
htmlstring- Up to 1000000 characters
textstring- Up to 1000000 characters
templateIdstring- 1 to 128 characters
templateVersioninteger- More than 0
propsRecord<string, any>slotsRecord<string, any>Values for the template's slots, the parts its layout leaves for each send.
trackOpensbooleantrackClicksbooleantagsRecord<string, string>Up to 8 tags of your own, copied onto every copy beside broadcast_id.
excludeAudienceIdsstring[]Audiences whose members are left out, even when they are in one of audienceIds.
Up to 10 itemsabTestobjectAn A/B test: 2 to 4 variants, each a subject or a body (html or text) that replaces the broadcast's own ({} keeps it), testPercent of the people (5 to 50, 20 unless set) split evenly between them, metric (opens or clicks) to pick the winner, and waitMinutes (30 to 4320, 240 unless set) to wait before picking it. Everybody else then gets the winning variant. A template broadcast can only vary the subject.
Can be nullvariantsobject[]Required- 2 to 4 items
subjectstring- 1 to 998 characters
htmlstring- 1 to 1000000 characters
textstring- 1 to 1000000 characters
testPercentinteger- At least 5At most 50Default
20 metricstring- One of
"opens""clicks"Default"opens" waitMinutesinteger- At least 30At most 4320Default
240
Also available in
sendBroadcastDraft
Send a draft to its audiences now, or schedule it with scheduledAt (an ISO-8601 time or a duration such as PT2H). It is checked like a new send: it needs an audience, a body, a subject and room in the plan for every copy. getBroadcast follows it and cancelBroadcast stops what has not gone out.
Inputs
broadcastIdstringRequired- 1 to 64 characters
scheduledAtstring- Up to 64 characters
Also available in
duplicateBroadcast
Copy any send to audiences into a new draft with the same sender, audiences, content, tracking, tags and campaign tags, without its schedule. Nothing is sent.
Inputs
broadcastIdstringRequired- 1 to 64 characters
Also available in
resendBroadcast
Send a finished send to audiences again, as a new broadcast, to the people it reached who have not opened it, optionally under a new subject and at a later time (scheduledAt). It only works when the first send tracked opens. Opens come from a tracking image, so people whose mail app blocks images count as not opened.
Inputs
broadcastIdstringRequired- 1 to 64 characters
subjectstring- 1 to 998 characters
scheduledAtstring- Up to 64 characters
Also available in
sendBroadcastTest
Send a test copy of a send to audiences, to read it before it goes out. It goes to the user's own account address unless to names up to 5 others. Merge fields are filled from the contact with that address or a sample name, the subject starts with [Test], opens and clicks are not tracked, and nobody joins an audience. Each copy counts as one send.
Inputs
fromstringRequired- 3 to 320 characters
tostring[]- 1 to 5 items
replyTostring- Up to 320 characters
utmobjectsourcestring- 1 to 100 characters
mediumstring- 1 to 100 characters
campaignstring- 1 to 200 characters
termstring- 1 to 100 characters
contentstring- 1 to 100 characters
subjectstring- Up to 998 characters
htmlstring- Up to 1000000 characters
textstring- Up to 1000000 characters
templateIdstring- 1 to 128 characters
templateVersioninteger- More than 0
propsRecord<string, any>slotsRecord<string, any>Values for the template's slots, the parts its layout leaves for each send.
trackOpensbooleantrackClicksbooleantagsRecord<string, string>Up to 8 tags of your own, copied onto every copy beside broadcast_id.
excludeAudienceIdsstring[]Audiences whose members are left out, even when they are in one of audienceIds.
Up to 10 itemsabTestobjectAn A/B test: 2 to 4 variants, each a subject or a body (html or text) that replaces the broadcast's own ({} keeps it), testPercent of the people (5 to 50, 20 unless set) split evenly between them, metric (opens or clicks) to pick the winner, and waitMinutes (30 to 4320, 240 unless set) to wait before picking it. Everybody else then gets the winning variant. A template broadcast can only vary the subject.
Can be nullvariantsobject[]Required- 2 to 4 items
subjectstring- 1 to 998 characters
htmlstring- 1 to 1000000 characters
textstring- 1 to 1000000 characters
testPercentinteger- At least 5At most 50Default
20 metricstring- One of
"opens""clicks"Default"opens" waitMinutesinteger- At least 30At most 4320Default
240
Also available in
listSegments
The saved segments of this workspace, newest first. A segment is a set of conditions on contacts, such as opened in the last 90 days or a custom field, that narrows a send to audiences: pass its id as segmentId to sendToAudience.
Inputs
Takes no input.
Also available in
- API
GET /segments- TypeScript
nextmail.segments.list()- Python
segments.list()- Ruby
segments.list- PHP
segments->list- Go
Segments.List- Java
segments().list- C#
Segments.ListAsync
getSegment
One segment, with each of its conditions.
Inputs
segmentIdstringRequired- 1 to 64 characters
Also available in
- API
GET /segments/{id}- TypeScript
nextmail.segments.get()- Python
segments.get()- Ruby
segments.get- PHP
segments->get- Go
Segments.Get- Java
segments().get- C#
Segments.GetAsync
createSegment
Save a segment: a name and the conditions a contact has to meet. It holds no contacts of its own, so who matches is worked out each time it is used. previewSegment counts the matches first without saving anything. Nothing is sent.
Inputs
namestringRequired- 1 to 120 characters
descriptionstring- Up to 500 characters
matchstringall (the default) when a contact has to meet every condition, any when one is enough.
One of"all""any"conditionsobject[]RequiredEach condition names a
fieldand 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.1 to 20 itemsfieldstringRequired- 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- Up to 320 characters
daysinteger- At least 1
audienceIdstring- Up to 64 characters
eventstring- Up to 100 characters
keystring- Up to 64 characters
Also available in
updateSegment
Rename a segment, change its description or its conditions. Giving conditions replaces all of them; giving only match keeps the conditions. A send already on its way keeps the conditions it was given. description takes null to remove it.
Inputs
segmentIdstringRequired- 1 to 64 characters
namestring- 1 to 120 characters
descriptionstring- Can be nullUp to 500 characters
matchstringall (the default) when a contact has to meet every condition, any when one is enough.
One of"all""any"conditionsobject[]Each condition names a
fieldand 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.1 to 20 itemsfieldstringRequired- 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- Up to 320 characters
daysinteger- At least 1
audienceIdstring- Up to 64 characters
eventstring- Up to 100 characters
keystring- Up to 64 characters
Also available in
deleteSegment
Delete a segment. No contact is touched, and a send already on its way keeps the conditions it was given. A draft that still names it is refused when it is sent.
Inputs
segmentIdstringRequired- 1 to 64 characters
Also available in
previewSegment
How many contacts a segment matches now, with a few of them, without saving or sending anything. Give segmentId for a saved segment, or conditions to try new ones. audienceIds counts only the subscribed members of those audiences.
Inputs
segmentIdstring- 1 to 64 characters
matchstringall (the default) when a contact has to meet every condition, any when one is enough.
One of"all""any"conditionsobject[]Each condition names a
fieldand 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.1 to 20 itemsfieldstringRequired- 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- Up to 320 characters
daysinteger- At least 1
audienceIdstring- Up to 64 characters
eventstring- Up to 100 characters
keystring- Up to 64 characters
audienceIdsstring[]- Up to 10 items