# 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 results without confusing queued work with completed work.



- Human page: https://mailrith.com/developers/jobs

- Category: API Resources

- Reading time: 7 min read



## What this guide covers

Create async subscriber imports and exports, use idempotency, and monitor results to completion.



## Use Async Jobs for Imports and Exports

Large subscriber movement is handled asynchronously. Instead of making one request wait until every row is processed, your integration submits a job, stores the returned job ID, and checks the job later.

Use async import jobs for CSV-style subscriber imports and use async export jobs when another system needs a generated subscriber file. This keeps long-running work reliable and gives your integration a clear status to monitor.

After submitting 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 available as a recovery path.

1. Prepare the CSV text or export filters in your own system.
2. Create a local job record and idempotency key.
3. Submit the Mailrith import or export job.
4. Store the returned Mailrith job ID.
5. Poll the job status endpoint at a reasonable interval.
6. Stop polling when the job reaches a final state.
7. Show the final result, failed rows, or export download information to the user in plain language.
8. For user-facing CSV workflows, compare your behavior with [Subscriber Imports, Exports, and Bulk Actions](https://mailrith.com/docs/subscriber-imports-exports.md).

- 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 when 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 represent email, name, tags, or custom fields.

`GET /v1/jobs/subscriber-imports/{job_id}` returns the current import job status and result information.

`POST /v1/jobs/subscriber-exports` queues an export job. The request can include filters such as subscriber status or subscriber selection supported by the contract.

`GET /v1/jobs/subscriber-exports/{job_id}` returns export job status and, when the export is ready, information needed to download the result.

Related OpenAPI operation groups:
- Jobs

## Import and Export Examples

The examples below show the smallest useful job creation calls. Real migrations usually include more rows, more mappings, and a durable job record in your own system.

For imports, confirm your CSV headers match the `csv_column` values exactly. For exports, confirm the filters match what the user expects before queueing the job.

**Queue an Import Job**

```bash
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**

```bash
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 work. Keep checking until Mailrith reports a final state, then show or store the result.

For imports, the final result needs to tell users whether rows were accepted or rejected. For exports, the final result needs to tell users when the file is ready and how to retrieve it according to the response schema.

If a job fails, do not immediately resubmit a changed job without showing the failure reason to the owner. Fix the CSV, mappings, filters, or credentials first, 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.
- Surface 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.



## Related Guides

- [Idempotency](https://mailrith.com/developers/idempotency.md): Import and export job creation endpoints accept idempotency keys so network retries do not queue duplicate work. This guide explains when to use a key, how to choose one, and how to store it with your own job record.

- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the core subscriber write surface in `v1`. This guide explains when to list, when to upsert, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests.

- [Errors](https://mailrith.com/developers/errors.md): Non-2xx responses carry stable error codes and plain-language messages. This guide explains how to log errors, avoid message matching, map status codes to user or system actions, and retry only when the same request may succeed later.