Import and Export Jobs

Imports and exports are asynchronous in `v1`. This page shows how to submit those jobs, use idempotency safely, and monitor completion.

4 min read

Use async jobs for imports and exports

Large audience movement is handled asynchronously in v1. Submit a job, store the returned job id, then poll the corresponding GET endpoint until the status reaches Completed or Failed.

Endpoints

Imports accept raw CSV text plus field mappings. Exports accept an optional audience selection and later return a download URL when the file is ready.

POST /v1/jobs/subscriber-exports

Create a subscriber export job

Queues an asynchronous subscriber export for the authenticated workspace.

View schema

GET /v1/jobs/subscriber-exports/{job_id}

Get a subscriber export job

Returns the current state of a previously created export job.

View schema

POST /v1/jobs/subscriber-imports

Create a subscriber import job

Queues an asynchronous subscriber import from CSV text.

View schema

GET /v1/jobs/subscriber-imports/{job_id}

Get a subscriber import job

Returns the current state of a previously created import job.

View schema

Import and export examples

Queue an import 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\nada@example.com,Ada Lovelace",
    "mappings": [
      {
        "csv_column": "Email",
        "field": { "type": "email" }
      },
      {
        "csv_column": "Name",
        "field": { "type": "name" }
      }
    ],
    "new_tag_name": "Website Signup"
  }'

Queue an export job

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
  }'

Need help shipping an integration?

Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.

Contact Mailrith

Related guides

3 min read

Idempotency

Retry async job creation safely with the `Idempotency-Key` header.

4 min read

Subscribers API

List and upsert subscribers with tags, sequences, and custom-field values.

3 min read

Errors

Handle stable error envelopes and status codes without depending on internal implementation details.

Segments API

API Reference