Idempotency

Import and export job creation endpoints accept idempotency keys so you can survive network retries without queueing duplicate work.

3 min read

Use idempotency for async job creation

Asynchronous job creation endpoints accept an Idempotency-Key header so callers can retry safely after network failures.

When the same key is replayed with the same request body, Mailrith returns the original successful job response.

Apply an Idempotency-Key when creating subscriber import or export jobs if your network path can retry after a timeout.

Mailrith will return the original successful job response when the same key and request body are replayed.

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

Keep retries safe

Generate one idempotency key per logical job submission.
Reuse that key only when you are retrying the exact same request payload.
Create a new key when the CSV content or export selection changes.

Import job with idempotency key

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-website-signups" \
  -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" }
      }
    ]
  }'