nextmail.segments
Every method in this namespace: its signature, its parameters, what it returns and an example.
Methods
Saved conditions on contacts, such as opened in the last 90 days or a custom field, that narrow a broadcast to the people who match: save, change and delete them, and count who they match.
segments.list()
List the saved segments
def list( *, api_key: str | None = None, timeout: float | None = None,) -> builtins.list[SegmentResource]Returns every saved segment of the workspace as a plain list, newest first, each with its name, its description and its conditions. A workspace keeps at most 100, so the list is never paged.
A segment holds no contacts of its own. Who matches is worked out each time it is read, so use preview to count the matches and pass a segment id as segmentId to broadcasts.send to narrow a broadcast with it.
Parameters
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
list[SegmentResource], each a dict with id, name, description, definition, createdAt and updatedAt.
Example
from nextmail import nextmail segments = nextmail.segments.list() for segment in segments: print(segment['id'], segment['name'], len(segment['definition']['conditions']))Notes
The SDK retries it after a network failure or a retryable status, since it changes nothing.
Segments belong to the workspace, not to the key or the person who made them.
Also available in
segments.get()
Get one segment
def get( id: str, *, api_key: str | None = None, timeout: float | None = None,) -> SegmentResourceReturns one saved segment by its id, with match and every condition in definition. The conditions come back as they were saved, so the dict can be edited and passed to update or preview as it is.
Parameters
idstrRequiredSegment id such as
seg_5d2a9c7e1b4f08a36c1e9b42.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SegmentResource.
Example
from nextmail import nextmail segment = nextmail.segments.get('seg_5d2a9c7e1b4f08a36c1e9b42') print(segment['name'], segment['definition']['match'], segment['definition']['conditions'])Notes
A segment from another workspace, or one that was deleted, is a 404
segment_not_found.
Also available in
segments.create()
Save a segment
def create( body: SegmentCreate, *, api_key: str | None = None, timeout: float | None = None,) -> SegmentResourceSaves a set of conditions under a name. definition['match'] is all (the default) when a contact has to meet every condition, or any when one is enough, and definition['conditions'] holds 1 to 20 of them.
Each condition names a field and an operator. email takes is, is_not, contains, not_contains and ends_with, and name takes those but ends_with, plus is_set and is_not_set. source takes is and is_not with how the contact was added. created, opened, clicked and engaged take within_days and not_within_days with days: when the contact was added, the last time they opened or clicked a tracked email from the workspace, and the later of those two. audience takes in and not_in with audienceId, and counts only subscribed members. event takes within_days and not_within_days with event, a name sent with events.send, and days. attribute takes key, the name of a custom field on the contact, with the operators name takes. Text is compared without regard to case.
Nothing is sent and no contact changes. A segment is used by passing its id as segmentId to broadcasts.send.
Parameters
body['name']strRequiredWhat the segment is called, 1 to 120 characters.
body['description']str | NoneA longer note, up to 500 characters.
body['definition']SegmentDefinitionInputRequired{'match': 'all' | 'any', 'conditions': [...]}with 1 to 20 conditions.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SegmentResource with the new seg_ id.
Example
from nextmail import nextmail segment = nextmail.segments.create( { 'name': 'Opened in the last 90 days', 'definition': { 'match': 'all', 'conditions': [{'field': 'opened', 'operator': 'within_days', 'days': 90}], }, }) nextmail.broadcasts.send( { 'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71'], 'segmentId': segment['id'], 'from': 'Acme <[email protected]>', 'subject': 'Thanks for reading', 'text': 'Hi {{firstName|there}}, here is something for our regular readers.', })Notes
A workspace keeps at most 100 segments. The 101st is refused with 409
segment_limit_reached.An audience condition that names an audience the workspace does not have is a 404
audience_not_found, and an operator its field does not take is a 422invalid_parameter.The SDK does not retry a create after a network failure, so a retry after a lost response can save two. List them and delete the spare.
Also available in
segments.update()
Change a segment
def update( id: str, patch: SegmentPatch, *, api_key: str | None = None, timeout: float | None = None,) -> SegmentResourceA partial update: a field you leave out keeps what it holds. Sending definition replaces match and every condition at once, and description: None takes the description away.
A broadcast already sent or scheduled keeps the conditions it was given, so a change here only reaches the broadcasts sent after it.
Parameters
idstrRequiredThe
seg_id of the segment.patch['name']strA new name, 1 to 120 characters.
patch['description']str | NoneA new note.
Nonetakes it away.patch['definition']SegmentDefinitionInputNew conditions, replacing the old ones.
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SegmentResource as it stands after the change.
Example
from nextmail import nextmail segment = nextmail.segments.update( 'seg_5d2a9c7e1b4f08a36c1e9b42', { 'name': 'Opened in the last 30 days', 'definition': { 'conditions': [{'field': 'opened', 'operator': 'within_days', 'days': 30}] }, },) print(segment['updatedAt'])Notes
The SDK retries it after a network failure, since sending the same change twice leaves the same segment.
A segment from another workspace is a 404
segment_not_found.
Also available in
segments.delete()
Delete a segment
def delete( id: str, *, api_key: str | None = None, timeout: float | None = None,) -> DeletedSegmentResourceDeletes the saved segment. No contact is touched, and a broadcast already sent or scheduled keeps the conditions it was given.
A draft that still names the segment in segmentId is refused with 404 segment_not_found when it is sent, until it names another segment or none.
Parameters
idstrRequiredThe
seg_id of the segment.api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
DeletedSegmentResource, {'object': 'segment', 'id': ..., 'deleted': True}.
Example
from nextmail import nextmail removed = nextmail.segments.delete('seg_5d2a9c7e1b4f08a36c1e9b42') print(removed['id'], removed['deleted'])Notes
The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.
Also available in
segments.preview()
Count the contacts a segment matches
def preview( body: SegmentPreviewInput, *, api_key: str | None = None, timeout: float | None = None,) -> SegmentPreviewResourceCounts the contacts a set of conditions matches now and returns up to 10 of them, without saving or sending anything. Pass the definition of a saved segment to count it, or new conditions to try them first.
With audienceIds, only the subscribed members of those audiences count, which is the number a broadcast to them with this segment would start from before unsubscribes and suppressions are taken out. broadcasts.preview with segmentId gives that final number.
Parameters
body['definition']SegmentDefinitionInputRequiredThe conditions to count, as
createtakes them.body['audienceIds']list[str]Up to 10 audiences. Only their subscribed members count. Left out, every contact of the workspace counts.
api_keystrOverrides the client's API key for this call only.
timeoutfloatSeconds this call may take, the response included, before it raises
NextmailNetworkErrorwithis_timeout. It overrides the client'stimeoutfor this call, and0turns the limit off.
Returns
SegmentPreviewResource with contacts, the number that match, and sample, up to 10 of them.
Example
from nextmail import nextmail preview = nextmail.segments.preview( { 'definition': { 'conditions': [{'field': 'engaged', 'operator': 'not_within_days', 'days': 180}], }, 'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71'], }) count = preview['contacts'] print(f'{count} people have not opened or clicked in six months')Notes
A condition on a custom field reads each contact it checks and stops at 20,000 of them, answering 422
segment_too_large. Narrow it withaudienceIdsfirst.The SDK retries it after a network failure or a retryable status, since it changes nothing.