Email lists

On this page:

Set MAILCOACH_API_URL and MAILCOACH_TOKEN as shown in Authentication. See the generated API reference for complete schemas.

Get all email lists

curl "$MAILCOACH_API_URL/email-lists" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Results are paginated. Search by name with ?filter[search]=newsletter, or use ?filter[name]=subscribers for an exact name match.

Supported sort fields are name, created_at and active_subscribers_count. For example, ?sort=-created_at sorts newest first. Sorting on updated_at is not supported.

Get a specific email list

Use the list’s UUID, not a numeric database ID:

curl "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

The list is returned under data, including uuid, name, sender defaults and settings.

Add an email list

Both name and default_from_email are required. Use a sender address configured for your account.

curl -X POST "$MAILCOACH_API_URL/email-lists" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"My subscribers","default_from_email":"hello@example.com","default_from_name":"Your team"}'

The response contains the new list under data. Save its uuid as email_list_uuid when creating campaigns. See the API reference for all writable settings and validation rules.

Update an email list

Include both required fields when updating. Sender defaults belong to the email list; campaign create and update requests do not accept sender overrides.

curl -X PUT "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Updated subscribers","default_from_email":"hello@example.com","default_from_name":"Your team"}'

The response contains the updated list under data.

Delete an email list

This deletes the list. Check the UUID before running the request.

curl -X DELETE "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Success returns an empty 204 response.

Error handling

See common errors and retry guidance. A 204 response is successful and has no JSON body.