> For the complete documentation index, see [llms.txt](https://user.netmera.com/netmera-developer-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://user.netmera.com/netmera-developer-guide/api-documentation/recipes/sending-push-to-tagged-audience.md).

# Sending a Push Campaign to a Tagged Audience

This recipe shows how to group users with a tag, send a push notification to everyone who carries that tag, and read the delivery statistics of the send. Tags turn a business rule that lives in your own system, such as a purchase, a plan, or an interest, into an audience that Netmera can target without sending user lists with every request.

## When to Use

This recipe fits campaigns where your backend decides who belongs to the audience, for example customers who completed a first purchase or members of a loyalty tier. The audience is defined once with a tag and reused in any number of sends.

## Prerequisites

* REST API key of the application
* External IDs (`extId`) of the users, set by the SDK or by `registerUsers`
* A tag name for the audience, for example `loyalty-gold`

## Step 1: Tag the Users

Send the tag name and the external IDs of the users to `tagUsers`. A single request accepts a maximum of 1000 unique external IDs; split larger audiences across multiple requests.

```bash
curl https://restapi.netmera.com/rest/3.0/tagUsers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-netmera-api-key: <API_KEY>' \
  --data '{
  "tag": "loyalty-gold",
  "extIds": ["user_1001", "user_1002", "user_1003"]
}'
```

{% hint style="info" %}
Tags can also be applied when a user is registered. The `registerUsers` endpoint accepts a `tags` array on every registration entry.
{% endhint %}

**Expected result:** The request returns HTTP 200 with no response body.

## Step 2: Send the Push Notification to the Tag

Send the message to `sendBulkNotification` and set the tag in the `target` object. `platforms` selects the channels that receive the message.

```bash
curl https://restapi.netmera.com/rest/3.0/sendBulkNotification \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-netmera-api-key: <API_KEY>' \
  --data '{
  "message": {
    "title": "Gold Member Offer",
    "text": "Enjoy early access to the new collection.",
    "platforms": ["IOS", "ANDROID"]
  },
  "target": {
    "tag": "loyalty-gold"
  }
}'
```

To combine tags, use the operator form in `target.tag`, for example `{ "$and": ["loyalty-gold", "newsletter"] }`, `$or` or `$not`.

The response contains the `notificationKey` of the created notification:

```json
{
  "notificationKey": 1000
}
```

**Expected result:** HTTP 200 with a `notificationKey`. Note it for the next step.

## Step 3: Read the Delivery Statistics

Pass the `notificationKey` to `getPushStats` to read the result of the send.

```bash
curl 'https://restapi.netmera.com/rest/3.0/getPushStats?notificationKey=1000' \
  --header 'X-netmera-api-key: <API_KEY>'
```

The response contains the delivery `status`, for example `SENDING` or `FINISHED`, and a `stats` array with the `sent`, `failed` and `clicked` counts per platform. Call the endpoint again until the status is `FINISHED` to read final numbers.

**Expected result:** Per-platform counts for the notification.

## Verification Checklist

* The tag name is identical in `tagUsers` and in `target.tag`
* Each `tagUsers` request contains at most 1000 external IDs
* `platforms` lists every platform that should receive the message
* The `notificationKey` returned by `sendBulkNotification` is recorded
* `getPushStats` reports the status `FINISHED` before the counts are used

## Related Pages

For all targeting options, see the Send bulk notification page in the REST API documentation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://user.netmera.com/netmera-developer-guide/api-documentation/recipes/sending-push-to-tagged-audience.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.