# 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.



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

- Markdown page: https://mailrith.com/developers/jobs.md

- Category: API Resources

- Reading time: 7 min read

- Last updated: 2026-07-13

- Related keywords: Import and Export Jobs, Import and Export Jobs developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Use Async Jobs for Imports and Exports, Endpoint Overview, Import and Export Examples, Monitor Job Results, Consent And Privacy API Boundaries, Idempotency, Subscribers API, Errors



## AI Agent Notes

- Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document.

- Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise.

- Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using.



## What this guide covers

Create async subscriber import and export jobs, use idempotency, and monitor job status until completion.



## 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.

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 job status, failed rows, or export download information to the user in plain language.
8. For user-facing CSV workflows, compare your workflow 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 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.

Related OpenAPI operation groups:
- Jobs

## Import 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.

**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,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"
  }'
```

**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. 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.



## Related Guides

- [Consent And Privacy API Boundaries](https://mailrith.com/developers/consent-and-lawful-basis.md): The public Subscriber API stores profile and list-management data, not separate consent-evidence fields. This guide explains the API boundary, safe Subscriber upserts, imports, webhooks, and when to use Mailrith-hosted GDPR consent workflows.

- [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 the key with your own job record.

- [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the main way integrations write Subscriber data in `v1`. This guide explains when to list subscribers, when to upsert subscribers, 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 include stable error codes and plain-language messages. This guide explains how to log errors, avoid matching on message text, map status codes to user or system actions, and retry only when the same request may succeed later.