> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Resubscribe Recipient

> Record an explicit opt-in the person made in your app — the only call that undoes an unsubscribe

When someone clicks the unsubscribe link in an email, Shipstar marks them `unsubscribed` and no [upsert](https://docs.shipstar.ai/api-reference/mailing-lists/upsert-recipients.md), add or restore ever changes that row again — a bulk sync must never be able to undo an opt-out by accident. Two things can: the person clicking **Resubscribe** on the unsubscribe confirmation page, and this call, which records an opt-in the signed-in person made in *your* product (turning a "Product updates" switch back on, re-ticking a newsletter box).

It is deliberately different from an upsert: one recipient per call, and a `consent` block that says where and when the person opted in. That block is stored on the recipient as its `consent` record and returned on every recipient read, so you can show your auditors who opted in, how and when.

What happens, by the recipient's current status:

| Status before | Result | `status` in the response | Webhook |
| - | - | - | - |
| `unsubscribed` | Active again | `resubscribed` | `mailing_list.resubscribed` |
| Not on the list, or [erased](https://docs.shipstar.ai/api-reference/mailing-lists/erase-recipients.md) earlier | Added as active; a hashed opt-out left by an erase is cleared | `added` | `mailing_list.resubscribed` if a hash was cleared |
| `removed` (you took them off) | Active again | `reactivated` | — |
| `active` | Nothing to change; `name`, `attributes` and the consent record are still applied | `already_active` | — |

Matching is by `external_id` first, then by email. Sending a new `email` for an existing `external_id` changes the address in place (and rotates that person's unsubscribe link). Activating a recipient counts against the list's plan cap exactly like an upsert.

> [!TIP]
>
> Call this from the code path where the person flips the switch, not from your nightly sync. Your sync should keep using upsert and treat `skipped_unsubscribed` as the person's final word until they opt in again — and should subscribe to the `mailing_list.resubscribed` webhook so an opt-in made on Shipstar's confirmation page flips your own flag too. See [Hearing about unsubscribes and resubscribes](https://docs.shipstar.ai/guides/sync-mailing-list.md#hearing-about-unsubscribes-and-resubscribes).

## Authentication

This endpoint requires an API token passed as a Bearer token in the `Authorization` header.

```bash theme={null}
Authorization: Bearer YOUR_API_TOKEN
```

## Path Parameters

**list\_id** `string` *required*

The mailing list's unique identifier (UUID).

## Body

At least one of `email` and `external_id`. Without an `email`, an unknown `external_id` is a 404 — there is nothing to add.

**external\_id** `string`

Your own id for this person, up to 255 characters. Matched first.

**email** `string`

Email address (case-insensitive). Required to add someone who is not on the list; changes the address of an `external_id`-keyed recipient.

**name** `string`

Display name, up to 200 characters. Applied when sent.

**attributes** `object`

Up to 20 keys with string, number, boolean or null values; replaces the stored map when sent.

**consent** `object` *required*

Where and when the person opted in on your side.

**Consent object**

**source** `string` *required*

Where they opted in, in your words — e.g. `Product updates switch, account settings`. Up to 200 characters.

**recorded\_at** `string`

When they did it (ISO 8601). Defaults to now.

**ip** `string`

Their IP address at the time, if you have it.

**user\_agent** `string`

Their browser user agent at the time, if you have it.

## Request

```bash cURL theme={null}
curl -X POST "https://api.shipstar.ai/api/v1/email/lists/a1b2c3d4-e5f6-7890-abcd-ef1234567890/recipients/resubscribe" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "usr_42",
    "email": "sam@example.com",
    "consent": {
      "source": "Product updates switch, account settings",
      "recorded_at": "2026-11-13T17:06:12Z",
      "ip": "203.0.113.5",
      "user_agent": "Mozilla/5.0"
    }
  }'
```

```javascript JavaScript theme={null}
const listId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const response = await fetch(`https://api.shipstar.ai/api/v1/email/lists/${listId}/recipients/resubscribe`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    external_id: 'usr_42',
    email: 'sam@example.com',
    consent: {
      source: 'Product updates switch, account settings',
      recorded_at: new Date().toISOString(),
      ip: request.ip,
      user_agent: request.headers['user-agent']
    }
  })
});

const result = await response.json();
```

```python Python theme={null}
import requests
from datetime import datetime, timezone

list_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
response = requests.post(
    f'https://api.shipstar.ai/api/v1/email/lists/{list_id}/recipients/resubscribe',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'external_id': 'usr_42',
        'email': 'sam@example.com',
        'consent': {
            'source': 'Product updates switch, account settings',
            'recorded_at': datetime.now(timezone.utc).isoformat(),
            'ip': request.client.host,
            'user_agent': request.headers.get('user-agent'),
        },
    },
)

result = response.json()
```

## Response

**status** `string` *required*

`resubscribed`, `added`, `reactivated` or `already_active` — see the table above.

**recipient** `object` *required*

The recipient as [List Recipients](https://docs.shipstar.ai/api-reference/mailing-lists/list-recipients.md) returns it, now `active`, including the `consent` record just written:

**consent**

**via** `string` *required*

`api` for this call; `email_link` when the person used the button on the unsubscribe page

**source** `string` *required*

Your `consent.source`, or `unsubscribe_page`

**recorded\_at** `string` *required*

ISO 8601

**ip** `string`

As sent, or the visitor's address on the unsubscribe page

**user\_agent** `string`

As sent, or the visitor's browser on the unsubscribe page

```json 200 theme={null}
{
  "status": "resubscribed",
  "recipient": {
    "id": "5b2f8c1e-4d3a-4f6b-9e2d-1a2b3c4d5e6f",
    "email": "sam@example.com",
    "name": "Sam Lee",
    "external_id": "usr_42",
    "attributes": {"plan": "pro"},
    "status": "active",
    "status_changed_at": "2026-11-13T17:06:13Z",
    "consent": {
      "via": "api",
      "source": "Product updates switch, account settings",
      "recorded_at": "2026-11-13T17:06:12Z",
      "ip": "203.0.113.5",
      "user_agent": "Mozilla/5.0"
    },
    "is_active": true,
    "created_at": "2026-09-01T08:00:00Z",
    "updated_at": "2026-11-13T17:06:13Z"
  }
}
```

## Errors

Error bodies carry a stable `code` next to the human-readable `detail`.

| Status | `code` | Meaning |
| - | - | - |
| 400 | `recipient_cap_exceeded` | Activating this recipient would exceed the list's plan cap; the body also has `active_count`, `limit` and `incoming` |
| 401 | — | Invalid or expired API token |
| 404 | — | Mailing list not found in the token's project |
| 404 | `recipient_not_found` | `external_id` only, and nobody on the list has it |
| 409 | `external_id_conflict` | The email belongs to a recipient with a different `external_id` |
| 409 | `email_conflict` | The new email is already another recipient's address on this list |
| 422 | `invalid_email` | The email address failed validation |
| 422 | — | Invalid request body (no identifier, missing `consent.source`, oversize attributes) |

## Rate Limits

This endpoint is limited to 30 requests per minute per IP.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.