---
title: "Add or update up to 500 subscribers"
method: POST
path: "/api/v1/subscribers/batch"
tags: ["Subscribers"]
---

# Add or update up to 500 subscribers

`POST /api/v1/subscribers/batch`

## Request

- Base URL: `https://mailcheer.com`
- URL: `https://mailcheer.com/api/v1/subscribers/batch`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Permission required: `subscribers:write`.

Each entry goes through exactly the same path as `POST /api/v1/subscribers`: double opt-in by default, the confirmation guard, the suppression list, unsubscribed people who are not brought back. A refused line does not fail the others: the response gives one line per entry, in order — `created`, `updated` or `rejected` with the refusal the single add would have returned. The same address twice in a batch: the second is rejected.

A batch of N counts as N requests against the rate limit (600 per minute per key): it saves round trips, it does not raise the limit. A refused batch consumes nothing (`429`, `Retry-After`).

## Headers

- `Idempotency-Key` string

## Request body

- SubscriberBatch
  - `subscribers` SubscriberRequest[], required: 1 to 500 subscribers, each in the form of `POST /api/v1/subscribers`.
    - `email` string, email, required: **Required.** Lower-cased on save.
    - `firstName` string
    - `lastName` string
    - `prenom` string: Alias of `firstName`. Fill in only one of the two.
    - `nom` string: Alias of `lastName`. Fill in only one of the two.
    - `tags` string[]: Workspace tags. The ones that do not exist yet are created.
    - `fields` object: Custom fields, by their technical key. Unknown keys create nothing: they come back in `ignored_fields`.
    - `double_opt_in` boolean: `false` subscribes straight away, with no confirmation email. The caller then bears responsibility for the consent.

## Response `200`

One line per entry.

- SubscriberBatchResult
  - `object` 'batch'
  - `data` object[]: One line per entry, in order. `created` and `updated` carry the fields of `POST /api/v1/subscribers`'s response (`subscriber`, `confirmation_sent`…); `rejected` carries `error` — the refusal the single add would have returned.
    - `index` integer
    - `email` string, nullable
    - `result` 'created' | 'updated' | 'rejected'
    - `subscriber` Subscriber
      - `id` string
      - `object` 'subscriber'
      - `email` string
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `status` 'pending' | 'subscribed' | 'unsubscribed' | 'bounced' | 'complained'
      - `source` string, nullable
      - `tags` string[]
      - `fields` object
      - `confirmed_at` string, date-time, nullable
      - `unsubscribed_at` string, date-time, nullable
      - `created_at` string, date-time
      - `updated_at` string, date-time: The last change to the record: status, name, fields, tags. Keep the largest value you receive and pass it as `updated_since` next time, minus one minute.
    - `confirmation_sent` boolean
    - `confirmation_not_sent_reason` string, nullable
    - `confirmation_retry_at` string, date-time, nullable
    - `ignored_fields` string[]
    - `error` Error (unresolved $ref)
  - `summary` object
    - `created` integer
    - `updated` integer
    - `rejected` integer

## Other responses

- `401`: Key missing, unknown or revoked.
- `403`: The key does not have the requested permission, or the workspace cannot send: `sending_blocked` (suspended, blocked or banned — nothing goes out, through any channel), `commitment_required` (the anti-spam commitment is not accepted), `reputation_blocked` (too many bounces or complaints).
- `422`: Malformed field, unverified domain, or recipient on the suppression list.
- `429`: More than 600 requests per minute for this key (`rate_limit_exceeded` — a batch of N subscribers counts as N), or a new workspace reached its daily limit (`daily_quota_exceeded`: 1,000 emails per rolling 24 hours until it is verified). `Retry-After` always says how many seconds to wait.

---

[API](https://skmtc.dev/mailcheer/apis/mailcheer-api.md) · [All operations](https://skmtc.dev/mailcheer/apis/mailcheer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailcheer/apis/mailcheer-api/revisions/ba64b7ef2170?raw)