HTTP API
Send one JSON request to a listener's send URL. Anything that can make an HTTP request can use this API. Start with Getting started if you do not have a listener yet.
Send a message
curl -X POST "https://push.palmpush.com/send/<listener-token>" \
-H "Content-Type: application/json" \
-d '{"title":"Build finished","body":"Ready to ship."}'Use the full URL from Copy URL in the app, or replace <listener-token>
with the value from Copy id. Listener ID and listener token mean the same
value. No separate API key or authorization header is required.
Request fields
| Field | Required | Value |
|---|---|---|
title | Yes | Non-empty text, up to 120 characters. |
body | Yes | Non-empty text, up to 4,096 characters. Use JSON newline escapes for line breaks. |
imageUrl | No | An HTTPS image URL, up to 2,048 characters. One image per message. |
url | No | An absolute website or app link, up to 2,048 characters. Opened when the notification is tapped. |
Leading and trailing whitespace is trimmed. Omit optional fields when unused; do not send empty strings. These text limits use JavaScript string length, so some characters, including many emoji, count as two units.
The field limits are separate from the push provider's total payload limit. A 4,096-character body is not guaranteed to fit. See payload size and errors.
Images and links together
curl -X POST "https://push.palmpush.com/send/<listener-token>" \
-H "Content-Type: application/json" \
-d '{"title":"Build finished","body":"Open the build details.","imageUrl":"https://www.palmpush.com/favicon/web-app-manifest-512x512.png","url":"https://www.palmpush.com/docs"}'imageUrl controls the attachment. url controls the tap destination. You can
use either field on its own, or both together. A listener avatar is configured
in the app and is added for that device automatically; it is not a send field.
Read Images, Links and tap actions, and listener avatars for their behavior and requirements.
Line breaks
Send plain text and encode line breaks as \n inside JSON strings:
{
"title": "Build finished",
"body": "The deployment completed.\n\nEnvironment: production\nStatus: ready"
}History preserves these line breaks. HTML and Markdown are not rendered as formatted message content. A notification's visible text area is controlled by iOS.
Read the response
The response contains listener and delivery. Important delivery fields are:
sentCount: requests accepted by push providers, not confirmed device receipt.failedCount: failed delivery attempts.deliveryEnabled: whether delivery for the whole listener was enabled.mutedSubscriptionCount: device subscriptions muted for this listener.errors: provider error details, when present.
HTTP 200 means the API completed without a reported delivery failure. It can
also mean a send was intentionally skipped: for example, a disabled listener
returns deliveryEnabled: false and sentCount: 0. Check the delivery fields
when your integration needs to know whether anything was accepted.
Errors
400: invalid token format or request fields.404: the listener does not exist.413: the request or provider payload is too large.502: a push provider rejected some or all delivery attempts.
An error response includes error.message. Provider failure responses also
include delivery results. Some devices may have succeeded even when the HTTP
status is 502; check sentCount before retrying, as a retry can create duplicate
messages. The API does not silently shorten text to fit a provider limit.
See Troubleshooting for what to check next. For code integration, use the JavaScript guide.