Tags & Segments
On this page:
- Get all tags
- Get a specific tag
- Add a tag
- Update a tag
- Delete a tag
- Get all segments
- Get a specific segment
- Add a segment
- Update a segment
- Delete a segment
- Error handling
Tags and segments belong to an email list. Use the list’s UUID and the tag or segment’s own UUID in nested URLs; these are different identifiers.
Set MAILCOACH_API_URL and MAILCOACH_TOKEN as shown in Authentication. The API reference contains the complete response schemas. Collection responses use pagination.
Get all tags
GET /api/email-lists/<email-list-uuid>/tags lists a list’s tags.
curl "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json'
Get a specific tag
curl "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags/38b9e5cf-d10f-4463-b74d-bf26495e9f5b" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json'
The response contains the tag under data, including uuid, name and email_list_uuid.
Add a tag
Only name is required. visible_in_preferences is an optional boolean, defaulting to false. Creating an existing default tag returns that tag.
curl -X POST "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"name":"my-tag","visible_in_preferences":false}'
Update a tag
Use the plural tags path and include both UUIDs. Pass name and the desired visible_in_preferences value.
curl -X PUT "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags/38b9e5cf-d10f-4463-b74d-bf26495e9f5b" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"name":"updated-tag","visible_in_preferences":false}'
Delete a tag
curl -X DELETE "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/tags/38b9e5cf-d10f-4463-b74d-bf26495e9f5b" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json'
A successful deletion returns an empty 204 response.
Get all segments
curl "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json'
Get a specific segment
curl "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments/4efdbe3c-25e2-46b0-b799-1e1b6b5c28e6" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json'
The response contains the segment under data. For the complete fields, see the API reference.
Add a segment
name is required. positive_tags and negative_tags are arrays of existing tag names from the same list, not tag UUIDs.
all_positive_tags_required: usetrueto require all positive tags, orfalseto match any.all_negative_tags_required: usetrueto exclude subscribers with all negative tags, orfalseto exclude subscribers with any negative tag.
curl -X POST "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"name":"my-segment","all_positive_tags_required":false,"all_negative_tags_required":false,"positive_tags":["my-tag"],"negative_tags":[]}'
Update a segment
Use the plural segments path and include both UUIDs. Send the complete desired tag conditions: updating replaces the segment’s conditions.
curl -X PUT "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments/4efdbe3c-25e2-46b0-b799-1e1b6b5c28e6" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -d '{"name":"updated-segment","all_positive_tags_required":false,"all_negative_tags_required":false,"positive_tags":["my-tag"],"negative_tags":[]}'
Delete a segment
curl -X DELETE "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/segments/4efdbe3c-25e2-46b0-b799-1e1b6b5c28e6" \ -H "Authorization: Bearer $MAILCOACH_TOKEN" \ -H 'Accept: application/json'
A successful deletion returns an empty 204 response.
Error handling
See common errors and retry guidance. A 204 response is successful and has no JSON body.