Subscriber imports

On this page:

Get all subscriber imports

The /api/subscriber-imports endpoint lists all subscriber imports.

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/subscriber-imports \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

As a result, you get the details of all the subscriber imports:

{
    "data": [
        {
            "uuid": "2ca0e737-b907-468f-819f-5d16e6bd6852",
            "subscribers_csv": null,
            "status": "completed",
            "email_list_uuid": "355cd119-59ba-4d8c-af8c-bd03ed091ae7",
            "subscribe_unsubscribed": false,
            "unsubscribe_others": false,
            "imported_subscribers_count": 577,
            "error_count": 836
        },
        {
            "uuid": "363fb337-7030-4bfd-8f8a-716493bb6c24",
            "subscribers_csv": null,
            "status": "completed",
            "email_list_uuid": "befd416e-a776-40c8-8d26-c3322091d697",
            "subscribe_unsubscribed": false,
            "unsubscribe_others": false,
            "imported_subscribers_count": 178,
            "error_count": 565
        },
        ...
    ],
    "links": {
        "first": "https://<your-mailcoach-domain>/api/subscriber-imports?page=1",
        "last": "https://<your-mailcoach-domain>/api/subscriber-imports?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://<your-mailcoach-domain>/api/subscriber-imports",
        "per_page": 15,
        "to": 3,
        "total": 3
    }
}

Get the details of a specific subscriber import

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

$ MAILCOACH_TOKEN="your API token"
$ curl https://<your-mailcoach-domain>/api/subscriber-imports/2ca0e737-b907-468f-819f-5d16e6bd6852 \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

Response:

{
    "data": {
        "id": 99,
        "uuid": "363fb337-7030-4bfd-8f8a-716493bb6c24",
        "subscribers_csv": null,
        "status": "completed",
        "email_list_uuid": "befd416e-a776-40c8-8d26-c3322091d697",
        "subscribe_unsubscribed": false,
        "unsubscribe_others": false,
        "imported_subscribers_count": 178,
        "error_count": 565
    }
}

Creating a subscriber import

To create an import, send a POST request to the /api/subscriber-imports endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -x POST https://<your-mailcoach-domain>/api/subscriber-imports \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"subscribers_csv":"email\njohn@doe.com", "email_list_uuid": "befd416e-a776-40c8-8d26-c3322091d697", "subscribe_unsubscribed": true, "unsubscribe_others": false}'

All fields are required:

  • subscribers_csv: a CSV string with the subscribers’ information
  • email_list_uuid: a valid email list UUID
  • subscribe_unsubscribed: true/false whether previously unsubscribed emails should be subscribed again
  • unsubscribe_others: true/false whether subscribers not in the CSV should be unsubscribed
  • replace_tags: true/false whether all tags should be replaced on the subscribers

If the API call succeeds, you will be given a response with the import’s details:

{
  "data": {
      "id": 1,
      "uuid": "363fb337-7030-4bfd-8f8a-716493bb6c24",
      "subscribers_csv": "email\njohn@doe.com",
      "status": "draft",
      "email_list_uuid": "befd416e-a776-40c8-8d26-c3322091d697",
      "subscribe_unsubscribed": true,
      "unsubscribe_others": false,
      "imported_subscribers_count": null,
      "error_count": 0
  }
}

Updating a subscriber import

To update an import, send a PUT request to the /api/subscriber-imports/<uuid> endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -x PUT https://<your-mailcoach-domain>/api/subscriber-imports/2ca0e737-b907-468f-819f-5d16e6bd6852 \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"subscribers_csv":"email\njohn@doe.com", "email_list_uuid": "befd416e-a776-40c8-8d26-c3322091d697", "subscribe_unsubscribed": true, "unsubscribe_others": false}'

Fields are the same as in the create endpoint. This endpoint only works if the import has a draft status.

If the API call succeeds, you will be given a response with the import’s details:

{
  "data": {
      "id": 1,
      "uuid": "363fb337-7030-4bfd-8f8a-716493bb6c24",
      "subscribers_csv": "email\njohn@doe.com",
      "status": "draft",
      "email_list_uuid": "befd416e-a776-40c8-8d26-c3322091d697",
      "subscribe_unsubscribed": true,
      "unsubscribe_others": false,
      "imported_subscribers_count": null,
      "error_count": 0
  }
}

Delete a subscriber import

To delete a subscriber import, you can send a DELETE request to the /api/subscriber-imports/<uuid> endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -x DELETE https://<your-mailcoach-domain>/api/subscriber-imports/2ca0e737-b907-468f-819f-5d16e6bd6852 \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

If the API call succeeds, you will be given an empty response with a 204 status code.

Appending to a subscriber import

You can append to the subscribers_csv field by sending a POST request to the /api/subscriber-imports/<uuid>/append endpoint.

This is useful for creating imports with a large amount of subscribers.

$ MAILCOACH_TOKEN="your API token"
$ curl -x POST https://<your-mailcoach-domain>/api/subscriber-imports/2ca0e737-b907-468f-819f-5d16e6bd6852/append \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'
    -d '{"subscribers_csv":"john2@doe.com"}'

subscribers_csv is the only required field.

If the API call succeeds, you will be given a response with the import’s details:

{
  "data": {
      "id": 1,
      "uuid": "363fb337-7030-4bfd-8f8a-716493bb6c24",
      "subscribers_csv": "email\njohn@doe.com\njohn2@doe.com",
      "status": "draft",
      "email_list_uuid": "befd416e-a776-40c8-8d26-c3322091d697",
      "subscribe_unsubscribed": true,
      "unsubscribe_others": false,
      "imported_subscribers_count": null,
      "error_count": 0
  }
}

Starting the import

Once you are ready to start your import, you can send a POST request to the /api/subscriber-imports/<uuid>/start endpoint.

$ MAILCOACH_TOKEN="your API token"
$ curl -x POST https://<your-mailcoach-domain>/api/subscriber-imports/2ca0e737-b907-468f-819f-5d16e6bd6852/start \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json'

This endpoint does not expect a body. The subscriber import should have a draft status.

If the API call succeeds, you will be given an empty response with a 204 status code.

Error handling

If an error occurs, you will 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."
    ]
  }
}
Templates
Subscribers