Skip to content

API reference / Send a notification

Send a notification

Queue a notification for a recipient's browsers, now or at a scheduled time.

POST/v1/notifications
Auth API key: Authorization: Bearer sk_live_… or sk_test_…

Creates a notification and one attempt per connected browser of the recipient, following its delivery policy, then answers before anything is sent. With sendAt or delay it is stored as scheduled and released later instead. See Sending notifications for the full walkthrough.

Request#

Headers#

Authorization
stringrequired
Your API key. The key decides the project and whether the send is live or a test.
Rules
Bearer sk_live_… or Bearer sk_test_…
Content-Type
stringoptional
The body is always read as JSON.
Rules
application/json
Idempotency-Key
stringoptional
Makes retries safe: the same key with the same body returns the original result instead of sending again. See Idempotency.
Rules
1–255 characters

Body#

A JSON object of at most 16,384 bytes. Unknown fields are rejected. Every field except recipient, priority, urgency, ttl, sendAt and delay, encoded as JSON, must fit in 3,000 bytes, counted after priority defaults are added (size limits). Each field is explained in message options.

recipient
stringrequired
The recipient's name in the key's project.
Rules
^[a-z0-9][a-z0-9_-]{0,39}$
title
stringrequired
The bold first line of the notification.
Rules
1–120 characters
body
stringoptional
The text under the title.
Rules
At most 480 characters
url
stringoptional
Opened when the person clicks the notification.
Rules
https URL with a domain name, at most 1,024 characters
icon
stringoptional
Small image beside the text.
Rules
https URL with a domain name, at most 512 characters
badge
stringoptional
Monochrome icon for the Android status bar.
Rules
https URL with a domain name, at most 512 characters
image
stringoptional
Large picture inside the notification, where the system shows one.
Rules
https URL with a domain name, at most 512 characters
actions
object[]optional
Buttons on the notification. See Actions and clicks.
Rules
At most 2, with unique ids
actions[].id
stringrequired
Reported back as actionClicked when the button is clicked.
Rules
^[a-z0-9][a-z0-9_-]{0,31}$
actions[].title
stringrequired
The button label.
Rules
1–40 characters
actions[].url
stringoptional
Opened when this button is clicked. Without it, the notification's url opens.
Rules
https URL with a domain name, at most 1,024 characters
tag
stringoptional
A notification with the same tag replaces the previous one instead of stacking.
Rules
1–64 characters
requireInteraction
booleanoptional
Keep the notification on screen until the person acts, where supported.
Default
false
silent
booleanoptional
Show without sound or vibration.
Default
false
priority
stringoptional
How urgently the notification is delivered. urgent also sets requireInteraction: true and low sets silent: true unless you set them. Wins over urgency when both are sent. See Priority.
Rules
low, normal, high or urgent
Default
high
urgency
stringoptional
Deprecated: use priority. Used only when priority is missing: very-low and low mean low, normal means normal, high means high.
Rules
very-low, low, normal or high
ttl
integeroptional
How long the push service keeps the message while the device is offline. For a scheduled notification it counts from sendAt.
Rules
0–2,419,200 seconds
Default
86,400
sendAt
stringoptional
Release the notification at this time instead of now. Cannot be combined with delay. See Scheduling.
Rules
ISO 8601 with a time zone offset, 10 seconds to 3 days ahead
delay
integeroptional
Release the notification this many seconds from now. Cannot be combined with sendAt.
Rules
10–259,200 seconds
data
objectoptional
Your own JSON object, passed to the notification and never shown.
Rules
At most 1,024 bytes as JSON

Response#

A new notification is answered with 202 Accepted, whether it is sent now or scheduled. A repeated request with the same Idempotency-Key and the same body is answered with 200 OK and the original result, and nothing new is sent.

id
stringrequired
The notification's id. Pass it to Get a notification to read its attempts.
Rules
UUID
status
stringrequired
queued: the attempts were created and each one now gets its own status. scheduled: nothing is created or charged until sendAt.
Rules
queued or scheduled
attempts
integerrequired
The number of attempts created now, one per connected browser. With the first delivery policy it is 1, and fallback attempts are added later. 0 for a scheduled notification.
Rules
0 or more
mode
stringrequired
The mode of the key that created the notification.
Rules
live or test
sendAt
string | nullrequired
When a scheduled notification will be released. null when it was sent at once.
Rules
ISO 8601, UTC
NoteWith a sk_test_… key the response looks the same, but nothing is sent and nothing is counted: each attempt is recorded as accepted straight away.

A scheduled notification is answered like this:

⫻

202 Accepted

HTTP/1.1 202 AcceptedContent-Type: application/jsonX-Request-Id: req_0199b1c27a4e7c3d9f1e2b6a8d4c5e11
{  "id": "0199b1c2-7a4e-7c3d-9f1e-2b6a8d4c5e10",  "status": "scheduled",  "attempts": 0,  "mode": "live",  "sendAt": "2026-10-05T18:00:00.000Z"}
NoteQUOTA_EXCEEDED is checked when the attempts are created. For a scheduled notification that is at release time: if the balance cannot cover it then, the notification is dropped instead of sent. See Scheduling.

Errors#

CodeHTTPWhen
VALIDATION_ERROR400The body is not valid JSON, is over 16,384 bytes, breaks a field rule or has an unknown field; the notification is over 3,000 bytes; sendAt or delay is out of range, or both are sent; or Idempotency-Key is empty or longer than 255 characters.
UNAUTHORIZED401The Authorization header is missing, or the key is malformed, unknown or revoked.
QUOTA_EXCEEDED402The free monthly allowance is used up and the credit balance cannot cover this send. Nothing is sent or stored. Not returned for scheduled notifications, which are checked at release.
FORBIDDEN403A live key was sent from a browser: the request carries an Origin header. Call the API from your server, or use a test key.
PROJECT_SUSPENDED403The key's project is suspended.
IDEMPOTENCY_CONFLICT409The Idempotency-Key was already used with a different body. A concurrent request with the same key and body waits for the first and gets its replay instead.
INVALID_RECIPIENT422No recipient with that name exists in the key's project, or it has no connected browsers. Nothing is stored or charged.
RATE_LIMITED429The key, project or account went over its per-minute limit. Wait for Retry-After seconds.
INTERNAL_ERROR500Something failed on Push's side. Retry with the same Idempotency-Key.

Example#

curl https://api.meslzy.com/push/v1/notifications \  -H "Authorization: Bearer $PUSH_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "recipient": "ops",    "title": "Deploy finished",    "body": "api@4f2c1a is live in production",    "url": "https://example.com/deploys/4f2c1a"  }'

⫻

202 Accepted

HTTP/1.1 202 AcceptedContent-Type: application/jsonX-Request-Id: req_0199b1c27a4e7c3d9f1e2b6a8d4c5e11
{  "id": "0199b1c2-7a4e-7c3d-9f1e-2b6a8d4c5e10",  "status": "queued",  "attempts": 2,  "mode": "live",  "sendAt": null}