Subscriber imports

Get all subscriber imports#

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

$ MAILCOACH_TOKEN="your API token"
$ curl https://[[your-domain]].mailcoach.app/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_id": 2,
            "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_id": 3,
            "subscribe_unsubscribed": false,
            "unsubscribe_others": false,
            "imported_subscribers_count": 178,
            "error_count": 565
        },
        ...
    ],
    "links": {
        "first": "https://[[your-domain]].mailcoach.app/api/subscriber-imports?page=1",
        "last": "https://[[your-domain]].mailcoach.app/api/subscriber-imports?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://[[your-domain]].mailcoach.app/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-domain]].mailcoach.app/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_id": 3,
        "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-domain]].mailcoach.app/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_id": 1, "subscribe_unsubscribed": true, "unsubscribe_others": false}'

All fields are required:

• subscribers_csv: a csv string with the subscribers' information
• email_list_id: a valid email list id
• 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

If the API call succeeded, you'll 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_id": 1,
      "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-domain]].mailcoach.app/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_id": 1, "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 succeeded, you'll 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_id": 1,
      "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-domain]].mailcoach.app/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 succeeded, you'll 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-domain]].mailcoach.app/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 succeeded, you'll 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_id": 1,
      "subscribe_unsubscribed": true,
      "unsubscribe_others": false,
      "imported_subscribers_count": null,
      "error_count": 0
  }
}

Starting the import#

Once you're 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-domain]].mailcoach.app/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 succeeded, you'll be given an empty response with a 204 status code.

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."
    ]
  }
}