Subscribers

On this page:

Get all subscribers from an email list

The /api/email-lists/<uuid>/subscribers endpoint lists all subscribers of a specific email list.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/subscribers \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Searching on email specifically is possible on this endpoint using ?filter[email]=info@example.com.

Fuzzy searching on email, first_name, last_name and tags is possible on this endpoint using ?filter[search]=searchterm for searching.

Filtering on subscriber status is possible using ?filter[status]=unconfirmed, possible values are unconfirmed, subscribed and unsubscribed

Sorting is possible on this endpoint on created_at, updated_at, subscribed_at, unsubscribed_at, email, first_name and last_name. For example ?sort=-created_at to sort descending on created_at

As a result, you get the details of all the email list’s subscribers:

{
    "data": [
        {
            "email_list_uuid": "a69075c6-ff5c-4b6a-b217-12026cb72e4f",
            "email": "john@doe.com",
            "first_name": null,
            "last_name": null,
            "extra_attributes": [],
            "tags": [],
            "uuid": "2a0c72d9-f91a-4fd2-88a7-589dfd75f464",
            "subscribed_at": "2020-08-06T13:24:31.000000Z",
            "unsubscribed_at": null,
            "created_at": "2020-08-06T13:24:31.000000Z",
            "updated_at": "2020-08-06T13:24:31.000000Z"
        },
        ...
    ],
    "links": {
        "first": "https://<your-mailcoach-domain>/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/subscribers?page=1",
        "last": "https://<your-mailcoach-domain>/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/subscribers?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://<your-mailcoach-domain>/api/email-lists/a69075c6-ff5c-4b6a-b217-12026cb72e4f/subscribers",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

Get a specific subscriber

If you want to get the details of a specific subscriber, you can send a GET request to the /api/subscribers/<uuid> endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464 \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Response:

{
    "data": {
        "email_list_uuid": "a69075c6-ff5c-4b6a-b217-12026cb72e4f",
        "email": "john@doe.com",
        "first_name": null,
        "last_name": null,
        "extra_attributes": [],
        "tags": [],
        "uuid": "2a0c72d9-f91a-4fd2-88a7-589dfd75f464",
        "subscribed_at": "2020-08-06T13:24:31.000000Z",
        "unsubscribed_at": null,
        "created_at": "2020-08-06T13:24:31.000000Z",
        "updated_at": "2020-08-06T13:24:31.000000Z"
    }
}

Subscribing to an email list

To subscribe an email address to an email list, send a POST request to the /api/email-lists/<uuid>/subscribers endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/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@doe.com", "first_name":"John", "last_name":"Doe"}'

The only required field is email and should be a valid email address.

Calling this for a subscriber already in the email list will update that subscriber. If you want the API call to fail with a validation exception instead, you can pass a strict=true in the url or body.

If the API call succeeded, you’ll be given a response with the subscriber’s details:

You can pass the following fields while creating a subscriber:

  • email: string, required
  • first_name: nullable
  • last_name: nullable
  • extra_attributes: nullable, array
  • tags: array
  • skip_confirmation: bool

When passing tags, the tags will be synced to the subscriber.

{
  "data": {
    "uuid": "2a0c72d9-f91a-4fd2-88a7-589dfd75f464",
    "email_list_uuid": "a69075c6-ff5c-4b6a-b217-12026cb72e4f",
    "email": "john@doe.com",
    "first_name": null,
    "last_name": null,
    "extra_attributes": [],
    "tags": [],
    "subscribed_at": "2020-08-06T13:24:31.000000Z",
    "unsubscribed_at": null,
    "created_at": "2020-08-06T13:24:31.000000Z",
    "updated_at": "2020-08-06T13:24:31.000000Z"
  }
}

Update a subscriber

To update a subscriber, you can send a PATCH request to the /api/subscribers/<uuid> endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -X PATCH https://<your-mailcoach-domain>/api/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464 \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"email":"john@doe.com", "first_name":"John", "last_name":"Doe"}'

You can pass the following fields while updating a subscriber:

  • email: string, required
  • first_name: nullable
  • last_name: nullable
  • tags: array
  • append_tags: boolean
  • extra_attributes: nullable, array

The append_tags option determines whether tags will be synced (replaced) or appended to the subscriber.

Delete a subscriber

To delete a subscriber, and erase all knowledge of it existing, you can send a DELETE request to the /api/subscribers/<uuid> endpoint.

This means the email address can be subscribed again on a later date.

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://<your-mailcoach-domain>/api/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464 \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeded, you’ll be given an empty response with a 204 status code.

Confirm a subscriber

To confirm a subscriber’s subscription to an email list, you can send a POST request to the /api/subscribers/<uuid>/confirm endpoint

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464/confirm \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeded, you’ll be given an empty response with a 204 status code.

Alternatively if you only have the email, you can send a POST request to the /api/email-lists/<uuid>/confirm endpoint with an email in the body.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/subscribers/a69075c6-ff5c-4b6a-b217-12026cb72e4f/confirm \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'
    -d '{"email":"john@doe.com"}'

Unsubscribe a subscriber

To unsubscribe a subscriber’s subscription to an email list, you can send a POST request to the /api/subscribers/<uuid>/unsubscribe endpoint

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464/unsubscribe \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeded, you’ll be given an empty response with a 204 status code.

Alternatively if you only have the email, you can send a POST request to the /api/email-lists/<uuid>/unsubscribe endpoint with an email in the body.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/subscribers/a69075c6-ff5c-4b6a-b217-12026cb72e4f/unsubscribe \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'
    -d '{"email":"john@doe.com"}'

Resend confirmation of a subscriber

To resend the confirmation email a subscriber received, you can send a POST request to the /api/subscribers/<uuid>/resend-confirmation endpoint

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/subscribers/2a0c72d9-f91a-4fd2-88a7-589dfd75f464/resend-confirmation \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeded, you’ll be given an empty response with a 204 status code.

Alternatively if you only have the email, you can send a POST request to the /api/email-lists/<uuid>/resend-confirmation endpoint with an email in the body.

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/subscribers/a69075c6-ff5c-4b6a-b217-12026cb72e4f/resend-confirmation \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'
    -d '{"email":"john@doe.com"}'

Adding tags to a subscriber

To add tags to a subscriber, you can send a POST request to the /api/subscribers/<uuid>/tags endpoint

$ MAILCOACH_TOKEN="your API token"
$ curl -X POST https://<your-mailcoach-domain>/api/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"]}'

You can pass the following fields to add tags:

  • tags: array
  • tags.*: string

Removing tags from a subscriber

To add tags to a subscriber, you can send a DELETE request to the /api/subscribers/<uuid>/tags endpoint

$ MAILCOACH_TOKEN="your API token"
$ curl -X DELETE https://<your-mailcoach-domain>/api/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"]}'

You can pass the following fields to add tags:

  • tags: array
  • tags.*: string

Error handling

If an error occurred, you’ll be given a non-HTTP/200 response code. The resulting payload might look like this.

{
    "message": "The given data was invalid.",
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}
Subscriber imports
Campaigns