Subscriber imports
On this page:
- Get all subscriber imports
- Get the details of a specific subscriber import
- Creating a subscriber import
- Updating a subscriber import
- Delete a subscriber import
- Appending to a subscriber import
- Starting the import
- Error handling
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.