---
title: "Unsubscribe a contact from one list"
method: PATCH
path: "/lists/{list_id}/unsubscribe"
tags: ["Lists"]
---

# Unsubscribe a contact from one list

`PATCH /lists/{list_id}/unsubscribe`

## Request

- Base URL: `https://api.sendfox.com`
- URL: `https://api.sendfox.com/lists/{list_id}/unsubscribe`
- Auth: OAuth 2
  - Authorization code: `https://sendfox.com/oauth/authorize`
  - Token URL: `https://sendfox.com/oauth/token`

Stops this one list for this one contact. Their other lists and their account-wide status are untouched, which is what distinguishes this from `PATCH /unsubscribe` — that endpoint is account-wide and is unchanged.
Idempotent. Repeating the request returns the original timestamp rather than moving it, so a retry never loses the date the person actually asked.
The opt-out is recorded durably, so it survives the contact being removed from the list and added back: re-adding them does not start sending again.
There is no matching resubscribe endpoint. Taking consent away on someone's behalf is safe for an integration to do; handing it back is not.

## Request body

- object
  - `email` string, email, required: Email address of a contact already on this list

## Response `200`

The contact, with the same two extra fields the unsubscribes list returns.

- object
  - `id` integer
  - `email` string, email, required
  - `first_name` string
  - `last_name` string
  - `ip_address` string
  - `unsubscribed_at` string, date-time, nullable
  - `bounced_at` string, date-time, nullable: When this address hard bounced. A hard bounce also sets unsubscribed_at. If unsubscribed_at is null, or far from this date, the bounce isn't what's stopping their email; they were resubscribed or opted out separately.
  - `bounce_paused_at` string, date-time, nullable: When this contact was last paused for repeated bounces. Can remain set after the pause has ended; read bounce_paused_until to tell.
  - `bounce_paused_until` string, date-time, nullable: When the current repeated-bounce pause ends. Null if the contact isn't paused, or has since unsubscribed or become invalid, since no retry is coming.
  - `invalid_at` string, date-time, nullable: When this address was found to be invalid. It isn't mailed while this is set.
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `list_unsubscribed_at` string, date-time: When they stopped this list.
  - `unsubscribed_scope` 'list' | 'account' | 'both'

## Other responses

- `400`: Missing or malformed email
- `403`: Not your list, or your plan does not permit changes. Reading GET /lists/{list_id}/unsubscribes stays available either way.
- `404`: That contact is not on this list
- `429`: Rate limit reached: 60 requests per minute per user, shared across all endpoints. Wait for the `Retry-After` seconds, then try again.

## Changes

- **2026-11-07** `ae5d5ba1d502`: 5 info
  - added the non-success response with the status `429`
  - added the optional property `allOf[#/components/schemas/Contact]/bounce_paused_at` to the response with the `200` status
  - added the optional property `allOf[#/components/schemas/Contact]/bounce_paused_until` to the response with the `200` status
  - added the optional property `allOf[#/components/schemas/Contact]/bounced_at` to the response with the `200` status
  - …1 more
- **2026-09-30** `1c85e046fea0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sendfox/apis/sendfox-api/changes/lists/:list_id/unsubscribe/patch.md)

---

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