Send a notification

Queue a notification for every browser connected to a recipient.

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, then answers before anything is sent. 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, urgency and ttl, encoded as JSON, must fit in 3,000 bytes (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

urgency

stringoptional

A delivery hint for the push service. See urgency and TTL.

Rules: very-low, low, normal or high
Default: normal

ttl

integeroptional

How long the push service keeps the message while the device is offline.

Rules: 0–2,419,200 seconds
Default: 86,400

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

stringrequired

The notification's id. Pass it to Get a notification to read its attempts.

Rules: UUID

status

stringrequired

The request was accepted for sending. Each attempt then gets its own status.

Rules: Always queued

attempts

integerrequired

The number of connected browsers the notification was queued for.

Rules: 1 or more

mode

stringrequired

The mode of the key that created the notification.

Rules: live or test

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.

Errors#

Code	HTTP	When
VALIDATION_ERROR	400	The 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; or `Idempotency-Key` is empty or longer than 255 characters.
UNAUTHORIZED	401	The `Authorization` header is missing, or the key is malformed, unknown or revoked.
QUOTA_EXCEEDED	402	The free monthly allowance is used up and the credit balance cannot cover this send. Nothing is sent or stored.
FORBIDDEN	403	A 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_SUSPENDED	403	The key's project is suspended.
IDEMPOTENCY_CONFLICT	409	The `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_RECIPIENT	422	No recipient with that name exists in the key's project, or it has no connected browsers. Nothing is stored or charged.
RATE_LIMITED	429	The key, project or account went over its per-minute limit. Wait for `Retry-After` seconds.
INTERNAL_ERROR	500	Something 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"}