Audience
Manage the subscribers who receive your publication.
Subscribers make up your audience — the readers who receive your posts by email. Use these endpoints to add, list, update, and remove them.
The subscriber object
{
"object": "subscriber",
"id": "sub_abc123",
"email": "reader@example.com",
"name": "Jordan Reader",
"status": "subscribed",
"created_at": "2026-06-01T10:00:00.000Z",
"updated_at": "2026-06-01T10:00:00.000Z",
"unsubscribed_at": null
}| Field | Type | Description |
|---|---|---|
object | string | Always "subscriber". |
id | string | Unique identifier. |
email | string | The subscriber's email address. Unique within your publication. |
name | string | null | Optional display name. |
status | string | "subscribed" or "unsubscribed". |
created_at | string | ISO 8601 creation timestamp. |
updated_at | string | ISO 8601 timestamp of the last update. |
unsubscribed_at | string | null | When the subscriber unsubscribed, or null if still subscribed. |
List subscribers
GET /subscribers| Query parameter | Type | Description |
|---|---|---|
status | string | Filter by subscribed or unsubscribed. Omit to return all. |
query | string | Filter by matching email address. |
limit | integer | Page size, 1–100. Defaults to 25. |
cursor | string | Pagination cursor. See Pagination. |
curl "https://palmframe.com/api/v1/subscribers?status=subscribed&query=example.com" \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"{
"object": "list",
"data": [
{
"object": "subscriber",
"id": "sub_abc123",
"email": "reader@example.com",
"name": "Jordan Reader",
"status": "subscribed"
}
],
"pagination": {
"limit": 25,
"has_more": false,
"next_cursor": null
}
}Add a subscriber
POST /subscribers| Body field | Type | Description |
|---|---|---|
email | string | Required. The subscriber's email address. |
name | string | Optional display name. |
status | string | "subscribed" or "unsubscribed". Defaults to "subscribed". |
This endpoint is idempotent on email. Adding an email that already exists
does not create a duplicate — it returns the existing subscriber with 200 OK
and applies any name or status you provide (so you can re-subscribe or
rename an existing reader). A brand-new subscriber is returned with
201 Created.
curl -X POST https://palmframe.com/api/v1/subscribers \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
-H "Content-Type: application/json" \
-d '{ "email": "reader@example.com", "name": "Jordan Reader" }'{
"object": "subscriber",
"id": "sub_abc123",
"email": "reader@example.com",
"name": "Jordan Reader",
"status": "subscribed",
"created_at": "2026-06-01T10:00:00.000Z",
"updated_at": "2026-06-01T10:00:00.000Z",
"unsubscribed_at": null
}Retrieve a subscriber
GET /subscribers/{id}curl https://palmframe.com/api/v1/subscribers/sub_abc123 \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"Returns the subscriber object, or
404 not_found if no subscriber has that id.
Update a subscriber
PATCH /subscribers/{id}Send only the fields you want to change.
| Body field | Type | Description |
|---|---|---|
name | string | New display name. |
status | string | "subscribed" or "unsubscribed". |
curl -X PATCH https://palmframe.com/api/v1/subscribers/sub_abc123 \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
-H "Content-Type: application/json" \
-d '{ "status": "unsubscribed" }'Setting status to "unsubscribed" stamps unsubscribed_at; setting it back
to "subscribed" clears it. Returns the updated subscriber object.
Remove a subscriber
DELETE /subscribers/{id}curl -X DELETE https://palmframe.com/api/v1/subscribers/sub_abc123 \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"Returns 200 OK:
{
"object": "subscriber",
"id": "sub_abc123",
"deleted": true
}Delete vs. unsubscribe
Deleting a subscriber permanently removes them from your audience. To stop
emailing someone while keeping their record, set their status to
"unsubscribed" instead.