Subscribers

A subscriber is one recipient of your notifications: usually one user of your product. Every trigger, message, preference and inbox feed in Notifly hangs off a subscriber, and each subscriber belongs to exactly one environment.

The subscriber ID

You choose the identifier. Use the ID your own system already has for the user (a database primary key, for example) so a trigger never needs a lookup first. It is the subscriberId field, and it is the only required one.

A subscriberId made of letters, digits and _, :, . or - is accepted wherever a trigger names a recipient, as is an email-shaped value. Surrounding whitespace is trimmed.

Subscriber fields

On an update, send null for a field to clear it. Provider credentials such as push device tokens are stored per subscriber too; see Subscriber credentials.

Create subscribers

There are three ways in, and all of them end up in the same place.

Inline in a trigger. Pass a subscriber object instead of a bare ID in to. The subscriber is created or updated as part of the trigger, so a product with no sync job can still send to a brand-new user:

curl -X POST https://api.notifly.io/v1/events/trigger \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<workflow-id>",
    "to": { "subscriberId": "user-42", "email": "ada@example.com", "firstName": "Ada" },
    "payload": { "body": "Welcome aboard" }
  }'

Through the API. POST /v2/subscribers creates a subscriber, or updates it if the subscriberId already exists. Add ?failIfExists=true to get a 409 instead of an update:

curl -X POST https://api.notifly.io/v2/subscribers \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberId": "user-42",
    "email": "ada@example.com",
    "locale": "en-US",
    "data": { "plan": "pro" }
  }'

To import many at once, POST /v1/subscribers/bulk takes a subscribers array of up to 500 per request.

In the dashboard. Open Subscribers in the sidebar and choose Add subscriber. The page also lists every subscriber in the environment.

Find, update and delete

GET /v2/subscribers searches the environment. Filter by email, phone, name or subscriberId (matching is case sensitive), and page through results with the after and before cursors and a limit (10 by default). The dashboard's Subscribers page offers the same four filters.

curl "https://api.notifly.io/v2/subscribers?email=ada@example.com&limit=10" \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY"

• GET /v2/subscribers/{subscriberId} retrieves one subscriber.
• PATCH /v2/subscribers/{subscriberId} updates the fields you send and leaves the rest.
• DELETE /v2/subscribers/{subscriberId} removes the subscriber.

In the dashboard, click a subscriber to open its profile. The tabs are Overview, Credentials, Preferences, Subscriptions and Activity Feed; the row menu offers Copy identifier, View activity and Delete subscriber.

What deleting removes

Deletion is a hard delete, not a flag. It removes the subscriber record together with that subscriber's messages, notifications, jobs, execution details, preferences, channel endpoints and connections, and topic subscriptions. Anything already queued for the subscriber fails instead of being delivered. A delete through the API is recorded in the organization's audit log.

Related

• Preferences. Each subscriber can switch workflows and channels on or off; see Per-user preferences.
• Topics. Group subscribers and fan a single trigger out to all of them; see Topics.
• Inbox. A subscriber's in-app notifications are their feed; see In-app inbox.
• Reference. Create a subscriber and the rest of the Subscribers operations in the API reference.