Skip to documentation content

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

bash
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

Fields accepted by the send endpoint
FieldRequiredValue
titleYesNon-empty text, up to 120 characters.
bodyYes

Non-empty text, up to 4,096 characters. Use JSON newline escapes for line breaks.

imageUrlNo

An HTTPS image URL, up to 2,048 characters. One image per message.

urlNo

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

bash
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:

json
{
  "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.