Palmframe API

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
}
FieldTypeDescription
objectstringAlways "subscriber".
idstringUnique identifier.
emailstringThe subscriber's email address. Unique within your publication.
namestring | nullOptional display name.
statusstring"subscribed" or "unsubscribed".
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 timestamp of the last update.
unsubscribed_atstring | nullWhen the subscriber unsubscribed, or null if still subscribed.

List subscribers

GET /subscribers
Query parameterTypeDescription
statusstringFilter by subscribed or unsubscribed. Omit to return all.
querystringFilter by matching email address.
limitintegerPage size, 1–100. Defaults to 25.
cursorstringPagination 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 fieldTypeDescription
emailstringRequired. The subscriber's email address.
namestringOptional display name.
statusstring"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 fieldTypeDescription
namestringNew display name.
statusstring"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.

On this page