Tags & Segments

On this page:

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: use true to require all positive tags, or false to match any.
  • all_negative_tags_required: use true to exclude subscribers with all negative tags, or false to 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.