---
title: "Unsubscribe email addresses"
method: POST
path: "/api/v1/people/identities/unsubscribe"
tags: ["People"]
---

# Unsubscribe email addresses

`POST /api/v1/people/identities/unsubscribe`

## Request

- Base URL: `https://api.recruitwithatlas.com`
- URL: `https://api.recruitwithatlas.com/api/v1/people/identities/unsubscribe`
- Auth: HTTP bearer

Use this endpoint to record that people have unsubscribed from email - for example when a candidate clicks unsubscribe in your marketing tool and Atlas should stop emailing them too.

Send up to 100 email addresses; matching is case-insensitive. For each address, Atlas finds the email identity in your agency and marks it inactive with `inactiveReason: "unsubscribed"` - the same as marking it unsubscribed in the Atlas app. Only the addresses you send change; a person's other email addresses stay as they are.

Campaigns no longer email an unsubscribed address - their emails to it are skipped - and it is not used for new campaigns. This only affects that address: the person's other addresses and their campaigns carry on. A recruiter can still send it an individual email, and that conversation keeps syncing to Atlas.

Each address gets one result:
- `unsubscribed` - the address is now unsubscribed. This includes an address that was already inactive for another reason, such as a bounce: an unsubscribe replaces that reason.
- `alreadyUnsubscribed` - the address was already unsubscribed and nothing changed, so resending an address is safe.
- `notFound` - no person in your agency has this email address.
- `failed` - the address could not be processed; `error` says why.

This endpoint only ever unsubscribes - an address cannot be resubscribed through the API.

Items are processed independently, a few at a time; results are reported in request order via `index`. Internal errors carry a generic message and the item was not processed, so it is safe to retry. The response is always `200`; a request-level validation error (malformed or duplicate address, empty array or more than 100 addresses) is rejected with `422` and writes nothing.

## Request body

- UnsubscribeIdentitiesPayload
  - `emails` string[], required: Email addresses to mark as unsubscribed (1–100 items). Matching is case-insensitive; an address may appear at most once per request.

## Response `200`

One result per address, in request order

- object
  - `status` 'ok', required
  - `data` object[], required
    - `index` integer, required: Zero-based position of the address in the request `emails` array
    - `email` string, required: The address as sent
    - `status` 'unsubscribed' | 'alreadyUnsubscribed' | 'notFound' | 'failed', required: Outcome for this address
    - `personId` string, uuid: Person the address belongs to (present when status is `unsubscribed` or `alreadyUnsubscribed`)
    - `identityId` string, uuid: Email identity ID (present when status is `unsubscribed` or `alreadyUnsubscribed`)
    - `error` string: Failure reason (present when status is `failed`)
  - `summary` object, required
    - `total` integer, required: Number of addresses in the request
    - `unsubscribed` integer, required: Addresses newly unsubscribed
    - `alreadyUnsubscribed` integer, required: Addresses that were already unsubscribed
    - `notFound` integer, required: Addresses no person in the agency has
    - `failed` integer, required: Addresses that failed

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `422`: Validation error - the request failed schema validation (`errors.fieldErrors`) or a business rule (`errors.formErrors`)
- `429`: Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the "Rate limits" section of the introduction for details.
- `500`: Internal server error

## Changes

- **2026-11-16** `7239e8f4db5c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/recruitwithatlas/apis/atlas-api/changes/api/v1/people/identities/unsubscribe/post.md)

---

[API](https://skmtc.dev/recruitwithatlas/apis/atlas-api.md) - [All operations](https://skmtc.dev/recruitwithatlas/apis/atlas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recruitwithatlas/apis/atlas-api/revisions/9075f4b8fc9c?raw)
