Subscriber imports

On this page:

Subscriber imports let you upload CSV data, optionally append more rows, then start processing separately. Creating an import does not start it.

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

Get all subscriber imports

curl "$MAILCOACH_API_URL/subscriber-imports" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

Get the details of a specific subscriber import

Use the import’s uuid, not a numeric database ID.

curl "$MAILCOACH_API_URL/subscriber-imports/2ca0e737-b907-468f-819f-5d16e6bd6852" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

The import is returned under data, including its uuid, status, email_list_uuid, imported_subscribers_count and error_count.

Creating a subscriber import

The required fields are subscribers_csv, a CSV string including a header row, and email_list_uuid.

curl -X POST "$MAILCOACH_API_URL/subscriber-imports" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"subscribers_csv":"email\njohn@example.com","email_list_uuid":"a69075c6-ff5c-4b6a-b217-12026cb72e4f","subscribe_unsubscribed":false,"unsubscribe_others":false,"replace_tags":false}'

These optional booleans change how existing subscribers are handled:

  • subscribe_unsubscribed: resubscribe previously unsubscribed addresses. Only enable this when you have permission to resubscribe them.
  • unsubscribe_others: unsubscribe existing subscribers absent from the CSV. Only enable this when the CSV represents the complete audience you want to keep subscribed.
  • replace_tags: replace subscribers’ tags rather than appending them.

The response contains the new import under data, with status set to draft.

Updating a subscriber import

Only draft imports can be updated. Both required fields must be supplied again.

curl -X PUT "$MAILCOACH_API_URL/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@example.com","email_list_uuid":"a69075c6-ff5c-4b6a-b217-12026cb72e4f","subscribe_unsubscribed":false,"unsubscribe_others":false,"replace_tags":false}'

Delete a subscriber import

curl -X DELETE "$MAILCOACH_API_URL/subscriber-imports/2ca0e737-b907-468f-819f-5d16e6bd6852" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

A successful deletion returns an empty 204 response.

Appending to a subscriber import

Append CSV rows before starting the import. Do not repeat the header row. subscribers_csv is the only required field.

curl -X POST "$MAILCOACH_API_URL/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":"jane@example.com"}'

The updated import is returned under data.

Starting the import

This request starts processing the draft import. It does not expect a body.

curl -X POST "$MAILCOACH_API_URL/subscriber-imports/2ca0e737-b907-468f-819f-5d16e6bd6852/start" \
    -H "Authorization: Bearer $MAILCOACH_TOKEN" \
    -H 'Accept: application/json'

A successful request returns an empty 204 response. Retrieve the import again to check processing status and counts.

Error handling

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