People

Unsubscribe email addresses

Changed on

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.

post/api/v1/people/identities/unsubscribe

Request

  • Base URL
    https://api.recruitwithatlas.com
  • Auth
    HTTP bearer

Request body

emailsstring[] required

Email addresses to mark as unsubscribed (1–100 items). Matching is case-insensitive; an address may appear at most once per request.

Example request

{
  "emails": [
    "jane.doe@example.com",
    "john.smith@example.com"
  ]
}

Response

One result per address, in request order

status'ok' required

Changes