Subscribers

On this page:

Set MAILCOACH_API_URL and MAILCOACH_TOKEN as shown in Authentication. Use the API reference for complete response schemas.

Get all subscribers from an email list

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

Results are paginated. Pass filters as query parameters, not in the request body:

  • filter[email]=john@example.com: search by email.
  • filter[search]=John: search email, first name, last name and tags.
  • filter[status]=subscribed: filter by unconfirmed, subscribed or unsubscribed.

Sort by created_at, updated_at, subscribed_at, unsubscribed_at, email, first_name or last_name. Prefix a field with - for descending order, for example ?sort=-created_at.

Get a specific subscriber

Use the subscriber’s UUID, not the list UUID:

curl "$MAILCOACH_API_URL/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

The subscriber is returned under data, including uuid, email_list_uuid, email, names, tags and subscription timestamps.

Subscribing to an email list

Only email is required. Optional fields are first_name, last_name, extra_attributes (a JSON object), tags (an array of strings), and skip_confirmation (a boolean).

curl -X POST "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/subscribers" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"john@example.com","first_name":"John","last_name":"Doe"}'

Calling this for an existing subscriber updates that subscriber. Pass strict=true in the query or body to reject an existing subscription instead. Supplied tags replace the subscriber’s tags. Only use skip_confirmation: true when you already have the subscriber’s consent.

The response contains the subscriber under data.

Update a subscriber

curl -X PATCH "$MAILCOACH_API_URL/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"john@example.com","first_name":"John","last_name":"Doe"}'

Supported fields are email, first_name, last_name, extra_attributes, tags and append_tags. email is optional when updating. Supplied tags replace existing tags unless append_tags is true. The response contains the updated subscriber under data.

Delete a subscriber

Deleting removes the subscriber record, allowing the address to subscribe again later. Use unsubscribe instead when you want to retain the subscription history.

curl -X DELETE "$MAILCOACH_API_URL/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Success returns an empty 204 response.

Confirm a subscriber

Use the subscriber UUID:

curl -X POST "$MAILCOACH_API_URL/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464/confirm" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Or use the list UUID with an email in the body:

curl -X POST "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/confirm" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"john@example.com"}'

Success returns an empty 204 response.

Unsubscribe a subscriber

curl -X POST "$MAILCOACH_API_URL/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464/unsubscribe" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Or use the list UUID with an email in the body:

curl -X POST "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/unsubscribe" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"john@example.com"}'

Success returns an empty 204 response.

Resend confirmation of a subscriber

This sends a confirmation email:

curl -X POST "$MAILCOACH_API_URL/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464/resend-confirmation" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Or use the list UUID with an email in the body:

curl -X POST "$MAILCOACH_API_URL/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/resend-confirmation" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"john@example.com"}'

Success returns an empty 204 response.

Adding tags to a subscriber

Pass an array of tag names. This adds tags without replacing existing tags.

curl -X POST "$MAILCOACH_API_URL/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464/tags" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"tags":["foo","bar"]}'

Removing tags from a subscriber

curl -X DELETE "$MAILCOACH_API_URL/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464/tags" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"tags":["foo","bar"]}'

Both tag operations return the updated subscriber under data.

Error handling

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