---
title: Sending · BuzzKit
description: One POST sends to a subscriber, a topic or a segment and lands on every device.
canonical: https://buzzkit.dev/features/sending
last-updated: 2026-09-02
---

# One call, every device. Target by id, topic or segment.

A send is one POST to /v1/messages: a title, a body and who it is for, by your own ids, a topic or a segment. BuzzKit resolves who is reachable, delivers with your own Apple and Firebase credentials and records every attempt.

## Target the way you already think

Address up to a thousand subscribers by your own ids, everyone opted into a topic, every member of a segment, or an inline expression on the send itself. A topic combines with any of them, so preferences still apply.

```
POST /v1/messages
{
  "segment": "active-pro",
  "topic": "gym-reminders",
  "title": "Leg day",
  "body": "Let’s go. 6:00 with Maya.",
  "deepLink": "app://workouts/legs",
  "ttlSeconds": 3600
}
```

## The full notification, not a subset

Everything Apple and Firebase accept is on the request: subtitle, badge, sound, image, thread and collapse ids, interruption level, relevance score, up to four action buttons and a deep link. Raw fields cover anything provider-specific.

```
POST /v1/messages
{
  "to": "user_42",
  "title": "Rest day is over",
  "body": "Your next workout is ready.",
  "badge": 1,
  "sound": "default",
  "interruptionLevel": "time-sensitive",
  "actions": [
    { "id": "snooze", "title": "Snooze" },
    {
      "id": "start",
      "title": "Start workout",
      "foreground": true
    }
  ],
  "deepLink": "app://workouts/next"
}
```

## Idempotent by design

Send an idempotency key with every request. A replay returns the original message and sends nothing, and the same key with a different body is refused.

```
POST /v1/messages
Idempotency-Key: workout-2026-08-20-user_42

202 Accepted
Idempotent-Replayed: true
{
  "id": "msg_…",
  "status": "queued"
}
```

## Capabilities

- **Reachability resolved.** Subscriptions, preferences and the channel switch are checked before queueing.
- **Expiry that holds.** A time to live from one minute to 28 days, honored by the providers.
- **Counts you can trust.** Pending, sent, failed and invalid, recounted from the ledger at completion.
- **Send policy.** Quiet hours and a daily cap per tenant, with an override for alerts.
- **Cancel in time.** A scheduled message can be canceled until the moment it releases.
- **Live Activities too.** A sibling endpoint drives iOS Live Activities and reports per token.

## Questions

### How many subscribers can one send target?

A direct send takes up to a thousand ids. A topic or segment send has no fixed limit, since fan-out runs in pages of five hundred subscriptions that chain themselves.

### What happens if the same request is sent twice?

With an idempotency key, the second request returns the original message and sends nothing. Without one, two messages are created.

### Can I send a silent push?

Yes. A data-only message is a silent push, and the raw APNs and FCM fields cover content-available and priority.

## Related

- [Segments](https://buzzkit.dev/features/segments.md): Saved expressions over attributes and events, evaluated fresh at send time.
- [Scheduling](https://buzzkit.dev/features/scheduling.md): Hold a message for a moment, in one timezone or in every subscriber’s own.
- [Delivery](https://buzzkit.dev/features/delivery.md): A durable queue, progressive retries, and a ledger of every attempt to every device.

## Start

- [Start sending](https://buzzkit.dev/dashboard)
- [API Reference](https://docs.buzzkit.dev)
- [BuzzKit on GitHub](https://github.com/buzzkit-dev/buzzkit)