Payload reference
Everything a sender can say, and the limits that apply.
title
string
120 chars. Required unless the body is plain text, which becomes the title.
body
string
2,000 chars. Shown under the title; links are detected.
priority
enum
low · normal · high · critical. Default normal.
url
url
Primary button. Opens in the browser or the app that owns the link.
url_label
string
24 chars. Default "Open".
actions
array
Up to 2. Each { label ≤ 20, url }. A { label, post } action is accepted and travels with the payload, to the detail and to webhooks, but the tap that performs the POST is not built yet.
group
string
64 chars. Identical group within 10 minutes collapses into one card with a count. Default: the title.
image
url
A picture for this one notification, in place of the source's icon.
fields
object
Up to 6 keys, each a printable name of up to 64 characters with a value of up to 2,000. Shown as rows on the notification.
total
8 KB. Larger payloads return 413.
How priority meets Reach
Reach is the ceiling you set per source. Priority can only move down from it: low never sounds and is always groupable; normal delivers at the source's Reach; high is never grouped away and pins to the top of the inbox for an hour; critical may break through quiet hours and Focus only if the source's switch and the account's master switch are both on. Critical never groups.
Rate limits
60 sends a minute per key, bursts of 10 a second. Above that the API returns 429 with a Retry-After header. Grouping absorbs legitimate bursts, so hitting the limit is almost always a bug on the sender's side.
Errors
Every error is JSON with one error code; 422 adds field. A 200 answers { "ok": true, "id": "ntf_…", "receipt": "rcpt_…", "grouped": false, "held": false }.
400
bad_json. Not JSON, and not readable as text.
401
unknown_key. No source has this key or token.
402
trial_used. The first 10 notifications are free; this one is held 7 days under Not delivered and released when you subscribe.
410
key_rotated. The key was rotated more than 24 hours ago, or the source was deleted.
422
invalid_field, naming the field.
429
rate_limited, with Retry-After in seconds; or daily_cap after 100,000 sends in a day.
503
sending_paused, with Retry-After. Retry later.
Authentication
The URL key (k_ and 14 random characters, about 70 bits) is enough for a personal inbox. SDKs and MCP use the source's bearer token instead: Authorization: Bearer ylk_… against POST youlmk.com/v1/notify.