Guides

Sources

A source is where a group of messages comes from, such as “GitHub Alerts” or “Backups”. Give each script its own, and you can tell messages apart at a glance and quiet one sender without touching the rest.

Every account starts with Inbox, which needs no setup. Create more in Ripple, or from code with a full-access API token, as this page shows.

Create a source

A new source needs only a name:

curl https://api.ripplepush.com/v1/sources \
  -H "Authorization: Bearer $RIPPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "GitHub Alerts"}'

Ripple answers 201 Created with the new source and its sourceId. The same request can set any of its settings.

A name can be up to 64 characters and needn't be unique. Names can change, but the ID never does, so keep the ID in your scripts. “Inbox” is taken, in any capitalization.

Note

Creating a source isn't idempotent: the same request sent twice makes two sources. If a request times out, list your sources before trying again.

Get its send key

Next, give your script a key that sends only to this source:

curl -X POST https://api.ripplepush.com/v1/sources/src_abc123/send-key \
  -H "Authorization: Bearer $RIPPLE_KEY"

The response has the key, and a sendAddress with the key in it for tools that only take a URL. Ask again and you get the same key.

If a key may have leaked, POST /v1/sources/{sourceId}/send-key/reset replaces it, and the old key stops working at once.

Tip

A source created in Ripple opens with a send command, new key included, ready to run.

How many you can have

An account can keep up to 100 sources, counting any in Trash, and create up to 30 a minute. Inbox counts toward neither. Past those limits, Ripple answers 409 source_limit_reached or 429 source_creation_rate_limited. Deleting a source for good frees its place.

Find your sources

List every source with its settings and counts:

curl https://api.ripplepush.com/v1/sources \
  -H "Authorization: Bearer $RIPPLE_KEY"

Inbox comes first, then the rest from oldest to newest, all on one page. Inbox's kind is system; every source you make is custom. Use Inbox's sourceId when a list or search should show only Inbox's messages.

Each source also reports how it's doing:

Field	What it counts
`unreadCount`	Unread messages, not counting archived or snoozed ones. A thread counts once.
`importantUnreadCount`	How many of those are Important
`quietUnreadCount`	How many of those are Quiet
`snoozedCount`	Its messages waiting in Snoozed
`lastMessageAt`	When it last accepted a message, or `null` if it never has. A good way to spot a script that has gone silent.

To read one source, use GET /v1/sources/{sourceId}.

Change a source's settings

Send only what you want to change in a PATCH. Everything else stays as it is:

curl -X PATCH https://api.ripplepush.com/v1/sources/src_abc123 \
  -H "Authorization: Bearer $RIPPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Builds", "defaultAlert": "quiet"}'

To clear a setting, send it as null.

Setting	What it does
`label`	The source's name
`iconSymbol`	The icon's symbol name
`iconColor`	The icon's color
`imageUrl`	An `https://` image to show instead of an icon
`defaultAlert`	The alert for messages that don't choose one
`defaultSound`	The sound for messages that don't choose one
`defaultLink`	The link for messages that don't include one

A source shows an icon or an image, not both. To switch, clear the one it has.
The colors are red, orange, yellow, green, teal, blue, indigo, purple and pink. A new source without an image gets one of your least-used colors unless you choose one, and null keeps the neutral tile.
The sounds are the twelve a message can choose, listed in Send messages. A defaultSound of null plays the account's sound. With sounds turned off in Ripple's settings, every source stays silent.
Inbox takes icon, color, image and default changes, but keeps its name.

Mute, disable or mark read

When a script gets noisy, or you want to retire it for a while, post to one of these addresses with no body:

Address	Does
`/v1/sources/{sourceId}/mute`	Keeps saving its messages, without notifications. `/unmute` turns them back on.
`/v1/sources/{sourceId}/disable`	Stops it accepting messages; sends get `403 source_disabled`. `/enable` lets them in again.
`/v1/sources/{sourceId}/read`	Marks all its messages read

Messages that arrive while a source is muted aren't notified after you unmute it. Inbox can't be muted or disabled.

Remove a source

To move a source to Trash, send a DELETE with no body:

curl -X DELETE https://api.ripplepush.com/v1/sources/src_abc123 \
  -H "Authorization: Bearer $RIPPLE_KEY"

Its messages stay where they are. To move them to Trash with it, add ?deleteMessages=true. Inbox can't be removed.

The source stays in Trash for 30 days, and you can restore it until then. The response's deletedAt lets a later restore or permanent deletion act only on this removal.

The API reference has every source operation in full.