Subscribers
On this page:
- Get all subscribers from an email list
- Get a specific subscriber
- Subscribing to an email list
- Update a subscriber
- Delete a subscriber
- Confirm a subscriber
- Unsubscribe a subscriber
- Resend confirmation of a subscriber
- Adding tags to a subscriber
- Removing tags from a subscriber
- Error handling
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 byunconfirmed,subscribedorunsubscribed.
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.