# Idempotency



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



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

- Category: API Concepts

- Reading time: 5 min read



## What this guide covers

Retry import and export job creation safely with the `Idempotency-Key` header.



## Use Idempotency for Async Job Creation

Idempotency protects create-style requests from accidental duplication. In Mailrith's public API, it is most important when queueing subscriber import and export jobs because those jobs can perform a lot of work after the request returns.

If your integration sends a job creation request and the network times out, you may not know whether Mailrith received it. Repeating the request with the same `Idempotency-Key` lets Mailrith return the original job response instead of creating another job.

Use idempotency keys for import and export job creation any time the caller, queue worker, or HTTP client might retry a request automatically.

1. Create your own local job record before sending the Mailrith request.
2. Generate one idempotency key for that local job.
3. Send the Mailrith import or export request with `Idempotency-Key` and the job payload.
4. Store the returned Mailrith job ID if the request succeeds.
5. If the request times out, retry with the same key and exact same payload.
6. If the CSV, mappings, or export filters change, create a new local job and a new idempotency key.
7. Monitor the job as described in [Import and Export Jobs](https://mailrith.com/developers/jobs.md).

- Generate one idempotency key for one logical job submission.
- Reuse the same key only for retries of the exact same request body.
- Store the key with your own job record so a queue worker can retry safely after a crash.
- Use a new key when the CSV content, mappings, filters, or export selection changes.
- Do not use one long-lived key for every import or export. That would make different jobs look like the same request.

Related OpenAPI operation groups:
- Jobs

## Keep Retries Safe

A safe retry pattern starts before the HTTP request is sent. First create your own local job record, then generate an idempotency key, then send the Mailrith request with that key.

If the request succeeds, store Mailrith's returned job ID beside your own job record. If the request times out, retry with the same key and same request body. If Mailrith already created the job, it can return the original response.

If you change the payload after a failed attempt, create a new idempotency key. A changed payload is no longer the same logical job.

- Good key examples: `import_2026_04_25_crm_001`, a UUID, or your own queue job ID.
- Bad key examples: `import`, `retry`, the workspace ID, or the API key.
- Keep idempotency keys out of user-visible copy. They are operational identifiers, not labels.
- Log the idempotency key with your job ID so you can trace repeated attempts.

**Import Job With an Idempotency Key**

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



## Related Guides

- [Import and Export Jobs](https://mailrith.com/developers/jobs.md): 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.

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

- [Testing the API](https://mailrith.com/developers/testing-the-api.md): Mailrith's public API can be tested manually with local curl requests and automatically through the integration suite. This page shows the repo-native commands for both paths.