Import and Export Jobs
Imports and exports are asynchronous in `v1`. This guide explains when to queue a job, how import mappings and export filters work at a high level, how to use idempotency, and how to monitor final job status without confusing queued work with completed work.
Use Async Jobs for Imports and Exports
Mailrith handles large subscriber changes asynchronously. Your integration submits a job, stores the returned job ID, and checks the job later instead of keeping one request open until every CSV row is processed.
Use async import jobs for CSV-style subscriber imports. Use async export jobs when another system needs Mailrith to generate a subscriber file. These jobs make long-running work more reliable and give your integration a clear status to monitor.
After you submit a job, poll the matching GET endpoint until the job reaches a final state, such as completed or failed. If you also use webhooks for job events, keep polling as a backup path in case a webhook is missed.
- Prepare the CSV text or export filters in your own system.
- Create a local job record and idempotency key.
- Submit the Mailrith import or export job.
- Store the returned Mailrith job ID.
- Poll the job status endpoint at a reasonable interval.
- Stop polling when the job reaches a final state.
- Show the final job status, failed rows, or export download information to the user in plain language.
- For user-facing CSV workflows, compare your workflow with Subscriber Imports, Exports, and Bulk Actions.
- Use imports for bulk subscriber creation, migration, and list cleanup workflows.
- Use exports for reporting, backups, audits, and external analysis.
- Store Mailrith's returned job ID in your own system.
- Use idempotency keys when creating jobs so retries do not queue duplicate work.
- Show job status to users in plain language, especially while a job is still processing.
Endpoint Overview
POST /v1/jobs/subscriber-imports queues an import job. The request includes CSV text and mappings that tell Mailrith which CSV columns contain email, name, country, Subscriber status, or custom fields.
Review the source list in your own migration process before you queue an import.
GET /v1/jobs/subscriber-imports/{job_id} returns the current import job status and import result information.
POST /v1/jobs/subscriber-exports queues an export job. The request can include filters supported by the contract, such as subscriber status or subscriber selection.
GET /v1/jobs/subscriber-exports/{job_id} returns the export job status and, when the export is ready, the information needed to download the file.
/v1/jobs/subscriber-exports Create a subscriber export job
Queues an asynchronous subscriber export for the authenticated workspace. Requires `jobs:write` and `subscribers:read` because the finished file contains subscriber data.
View Schema /v1/jobs/subscriber-exports/{job_id} Get a subscriber export job
Returns the current state of a previously created export job. Requires `jobs:read` and `subscribers:read` because completed jobs include a subscriber CSV download URL.
View Schema /v1/jobs/subscriber-imports Create a subscriber import job
Queues an asynchronous import job that creates or updates subscribers from CSV text.
View Schema /v1/jobs/subscriber-imports/{job_id} Get a subscriber import job
Returns the current state of a previously created import job.
View SchemaImport and Export Examples
The examples below show the smallest useful job creation requests. Real migrations usually include more CSV rows, more mappings, and a durable job record in your own system.
For imports, confirm that each CSV header matches its csv_column value exactly. For exports, confirm that the filters match the user's requested subscriber set before you queue the job.
curl -X POST https://api.mailrith.com/v1/jobs/subscriber-imports \
-H "Authorization: Bearer mrk_example_secret_key" \
-H "Idempotency-Key: import-2026-04-11" \
-H "Content-Type: application/json" \
-d '{
"csv_text": "Email,Name,Country,Subscriber Status\nada@example.com,Ada Lovelace,DE,Active",
"mappings": [
{
"csv_column": "Email",
"field": { "type": "email" }
},
{
"csv_column": "Name",
"field": { "type": "name" }
},
{
"csv_column": "Country",
"field": { "type": "country" }
},
{
"csv_column": "Subscriber Status",
"field": { "type": "subscriber-status" }
}
],
"new_tag_name": "Website Signup"
}'curl -X POST https://api.mailrith.com/v1/jobs/subscriber-exports \
-H "Authorization: Bearer mrk_example_secret_key" \
-H "Idempotency-Key: export-2026-04-11" \
-H "Content-Type: application/json" \
-d '{
"status": "Active",
"cold_only": false
}'Monitor Job Results
A queued job is not finished. Keep checking the job status until Mailrith reports a final state, then show or store the final job information.
For imports, the final import result must tell users which rows were accepted and which rows were rejected. For exports, the final export result must tell users when the file is ready and how to retrieve the file according to the response schema.
If a job fails, show the failure reason to the owner before you resubmit changed work. First fix the CSV, mappings, filters, or credentials. Then submit a new logical job with a new idempotency key.
- Poll at a reasonable interval instead of every second.
- Stop polling once the job reaches a final state.
- Show failed rows or failure messages in your own UI or logs.
- Keep the original CSV and mapping version long enough to troubleshoot failed imports.
- Use webhooks as a faster notification path when your system needs to react immediately.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.