# Subscribers

URL: https://notifly.io/docs/subscribers

> Subscribers are the recipients of every Notifly notification. Create, identify, search, update and delete them in the dashboard, REST API or a trigger.

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](https://notifly.io/docs/getting-started#environments).

## 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

| Field                   | Notes                                                                                                                                                 |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subscriberId`          | Required. Unique within the environment.                                                                                                              |
| `firstName`, `lastName` | Strings.                                                                                                                                              |
| `email`                 | Must be a valid email address. Used by email steps.                                                                                                   |
| `phone`                 | String. Used by SMS steps.                                                                                                                            |
| `avatar`                | A URL or identifier for the subscriber's avatar.                                                                                                      |
| `locale`                | A valid locale such as `en-US`. Selects the language for [translations](https://notifly.io/docs/workflows#translations-i18n).                                                |
| `timezone`              | A valid IANA time zone such as `America/New_York`.                                                                                                    |
| `data`                  | A free-form JSON object for your own attributes. Templates read it as `subscriber.data.<field>`, and [step conditions](https://notifly.io/docs/step-conditions) can test it. |

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](https://notifly.io/docs/api#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:

```bash
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:

```bash
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.

```bash
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](https://notifly.io/docs/security#audit-log).

## Related

* **Preferences.** Each subscriber can switch workflows and channels on or off; see [Per-user preferences](https://notifly.io/docs/channels#per-user-preferences).
* **Topics.** Group subscribers and fan a single trigger out to all of them; see [Topics](https://notifly.io/docs/workflows#topics).
* **Inbox.** A subscriber's in-app notifications are their feed; see [In-app inbox](https://notifly.io/docs/inbox).
* **Reference.** [Create a subscriber](https://notifly.io/docs/api-reference/subscribers/SubscribersController_createSubscriber) and the rest of the Subscribers operations in the [API reference](https://notifly.io/docs/api-reference).
