Topics

Subscribe or unsubscribe a contact from a topic

The two directions behave differently, and the asymmetry is deliberate: consent needs proof, withdrawal of consent does not.

subscribed: true does NOT subscribe anyone. It parks the contact at pending and returns a confirmation_url; nothing is mailed on this topic until somebody opens it. There is no parameter to skip that step. A caller asserting a subscription is not evidence that the mailbox holder agreed — anyone can type an address into a form — and treating the assertion as consent is the exact failure double opt-in exists to prevent. Sendly does not send the confirmation email; you do, from your own verified domain, because it is your relationship with the contact and your sending reputation.

subscribed: false records the opt-out immediately. Requiring somebody to confirm that they want to stop is a dark pattern, and it is also the fastest route to a spam report.

Requires the topics:write scope — Create and edit topics, and change what your contacts are subscribed to — this decides who your campaigns reach.

post/api/v1/topics/{id}/subscriptions

Request

  • Base URL: https://api.sendly.now
  • URL: https://api.sendly.now/api/v1/topics/{id}/subscriptions
  • Auth: one of:
    • HTTP bearer
    • API key in cookie better-auth.session_token
    • OAuth 2 (authorization code, authorization URL https://app.sendly.now/api/auth/oauth2/authorize, token URL https://app.sendly.now/api/auth/oauth2/token, scopes: topics:write)

Path parameters

idstring uuid required

Resource id.

Request body

contact_idstring uuid required
subscribedboolean required

True asks to subscribe, which starts a DOUBLE OPT-IN: the contact is parked at pending and a confirmation link is sent. There is no way to skip that from the API — a subscription an API caller asserts is not evidence the mailbox holder agreed, and treating it as consent is exactly what double opt-in exists to stop. False records an unsubscribe, which takes effect immediately.

Response

The resulting subscription

confirmation_urlstring nullable required

Present only when this call started a double opt-in. Sendly does NOT send the confirmation email — you do, from your own verified domain, because it is your relationship with the contact and your sending reputation. The subscription stays pending, and is NOT mailed, until someone opens this link.

confirmed_atstring date-time nullable required
contact_idstring required
status'pending' | 'subscribed' | 'unsubscribed' required

subscribed: mail them about this. unsubscribed: do not. pending: a confirmation link was sent and has NOT been clicked — never treat this as consent, which is the whole point of double opt-in.

topic_idstring required

Changes

No recorded changes to this operation across all 1 revision of this API.