---
title: "Change contacts' status"
method: POST
path: "/prospects/status"
tags: ["Suppressions"]
---

# Change contacts' status

`POST /prospects/status`

## Request

- Base URL: `https://warmysender.com/api/v1`
- URL: `https://warmysender.com/api/v1/prospects/status`
- Auth: HTTP bearer

Sets the status of up to 1,000 contacts (for example dnc or active). A contact who unsubscribed or whose address bounced is never set back to a status that can be emailed: it is counted in refused, listed in refused_ids and explained in message.

Required scope: `prospects:write`.

Requires a unique `Idempotency-Key` request header so retries never duplicate.

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `prospect_ids` string[], required: Contact ids to change (1–1000).
  - `status` 'active' | 'bounced' | 'invalid' | 'unsubscribed' | 'dnc' | 'suppressed' | 'risky', required: New status.

## Response `200`

Success

## Other responses

- `400`: `validation_error` — Body failed validation (unknown status, empty or oversized list).
- `401`: `unauthorized` — Missing or invalid API key.
- `403`: `insufficient_scope` — The API key lacks the scope this endpoint requires.
- `429`: `rate_limited` — Too many requests — slow down and retry after the Retry-After delay.

---

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