Authentication

The Simplepush API uses your Simplepush key to authenticate requests. You get a random six-digit key after opening the Simplepush app for the first time. There is no registration process which means that you will get your key immediately after installing the app.

If you decide to purchase the subscription, you will be able to add multiple keys that identify your device. Those keys do not have to be random digits. Currently the only constraint is a minimum length of six digits.

You can also share keys between different devices. If a key is registered on multiple devices, push notifications sent to the key will be delivered to all devices that have the specific key in their list of keys.

Message API

Send an HTTPS request to https://simplepu.sh with the following paramters:

  • key (required) - The key that identifies your device(s)
  • message (required) - The message for your notification
  • title (optional) - An optional title for your notification
  • event (optional) - An optional event which modifies the behavior of your notification

The following examples show how to use our API with curl (a command-line tool to make HTTP requests).

POST Request

For POST requests you can choose between encoding the parameters and using JSON.

~ $ curl --data 'key=HuxgBB&title=title&msg=message&event=event' https://simplepu.sh

~ $ curl https://simplepu.sh -d '{"key": "HuxgBB", "title": "title", "msg": "message", "event": "event"}'


GET Request

The first request only sends a message while the second one sends both a title and a message.

The third request shows how to define an event.

~ $ curl https://simplepu.sh/HuxgBB/message

~ $ curl https://simplepu.sh/HuxgBB/title/message

~ $ curl https://simplepu.sh/HuxgBB/title/message/event/event


Actions

With Actions you can send actionable notifications. Actionable notifications are push notifications with action buttons where selecting an action has some immediate effect.

Simplepush Actions currently supports two different effects.

  • Feedback Actions have the effect of saving the selected action on the Simplepush backend. When you send an actionable notification you will receive a feedback id which gives you access to the information on the backend.
  • GET Actions have the effect of executing an HTTP GET request.

Actions can be selected directly from the notification center of your iOS and Android device or inside the app.

You can define up to 10 actions. Android will show a maximum of three actions in its notification center while all 10 will be shown inside the app.

Feedback Actions

The following sends an actionable notification with two actions.

~ $ curl https://simplepu.sh -d '{"key": "HuxgBB", "title": "title", "msg": "message", "actions": ["yes", "no"]}'

{"status":"OK","feedbackId":"5e885b1d33c547bbac78bda8cdaf7be7"}


After the action notification was sent and you received a feedback id, you can query the Feedback API to see if an action was selected.

~ $ curl https://simplepu.sh/1/feedback/5e885b1d33c547bbac78bda8cdaf7be7

{"success":true,"action_selected":"yes","action_selected_at":1646869812,"action_delivered_at":1646869812}


GET Actions

GET Actions will trigger HTTP GET requests when an action is selected.

~ $ curl https://simplepu.sh -d '{"key": "HuxgBB", "title": "title", "msg": "message", "actions": [{"name": "yes", "url": "https://your.domain/yes"}, {"name": "no", "url": "https://your.domain/no"}]}'


Attachments

Attachments can be used to embed pictures, videos, GIFs and even rtsp livestreams (still experimental) into push notifications.

Send a push notification with a picture, video and GIF attached:

~ $ curl https://simplepu.sh -d '{"key": "HuxgBB", "msg": "message", "attachments": ["https://upload.wikimedia.org/wikipedia/commons/e/ee/Sample_abc.jpg", "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4", "https://upload.wikimedia.org/wikipedia/commons/d/d3/Newtons_cradle_animation_book_2.gif"]}'


Send a push notification with a video attached that has a thumbnail:

~ $ curl https://simplepu.sh -d '{"key": "HuxgBB", "msg": "message", "attachments": [{"thumbnail": "https://upload.wikimedia.org/wikipedia/commons/e/ee/Sample_abc.jpg", "video": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4"]}'


Send a push notification with a video stream attached (experimental):

~ $ curl https://simplepu.sh -d '{"key": "HuxgBB", "msg": "message", "attachments": ["rtsp://rtspstream.com/pattern"]}'


Limitations

Freemium users are limited to 10 notifications per month. After those 10 free notifications all following notifications will be dropped.

The Feedback API allows for one request per second and feedback id.