Simplepush

Appearance

Topics ​

A topic is a named bucket of devices. Sending a notification or task to a topic fans out to every device holding that topic.

bash
sp notify -t family --title "Dinner" --content "Ready at 7"
sp task -t eng-oncall --title "Build red on main" -c "Ack,Mute"

A topic value is a string of up to 255 characters with no whitespace. Anyone who knows the value can hold the topic, so an unguessable value acts as the capability: share it with the people who should receive.

Sending to your own devices needs no topic at all: just omit the topic.

Membership ​

  • Personal accounts: people join a topic by entering its value in the app. Whoever holds the value receives, and by default may also send. This is the friends-and-family flow: trust travels with the value.
  • Organizations: an admin manages membership with sp org topics. Members are assigned and never join by themselves.

Sending to a shared topic requires the sender to hold it: a personal send to a topic you're not a member of is rejected with 403 not_topic_holder.

Limits: a free account can create 1 topic, a paying account 20. A topic can have up to 10 holders but only up to 3 freemium users.

Write-protected topics ​

By default any holder can also publish. Write-protection inverts that: everyone still receives, but publishing requires a sender token. That makes a topic safe to share widely — many receivers, a short list of authorized senders. Paying accounts can write-protect up to 2 topics; set it up in the app under the topic's settings, which issues the sender token.

Senders present the token on every publish, via the Topic-Auth-Token header (or the topicAuthToken JSON field):

bash
curl -X POST https://api.simplepu.sh/v1/notifications \
  -H "API-Token: $SP_API_TOKEN" \
  -H "Topic: announcements" \
  -H "Topic-Auth-Token: $SENDER_TOKEN" \
  -H "Title: Maintenance window" \
  -H "Content: Saturday 02:00-04:00 UTC"

Publishing without a valid token fails with 401 write_protection_token_required / write_protection_token_invalid.

Encryption ​

Topic sends support end-to-end encryption: the key is derived from (password, topic-value), so everyone who shares the password and the topic can decrypt, and the server never can. Pass -p "secret@your-topic" on the CLI or a [password, topic] pair in the SDKs. Org topics encrypt under the org's master key instead. Details in Encryption.