Paperplane

Your agent can't approve its own deploy

Sat, 01 Aug 2026 00:00:00 GMT

A blocking approval only means something if the thing being approved can’t approve itself. So the rule on Paperplane’s backend is simple: a personal access token can send an ask, poll it, and read its result — but it can never be the thing that answers it.

Why a token isn’t enough

The token an agent holds to send an ask is, cryptographically, the same kind of credential that could be used to answer one. If sending and answering used the same check, an agent — or anything holding its token — could ask itself a question and approve it, and you’d never know the “approval” wasn’t a person.

So answering is deliberately session-only: it requires a signed-in human, tapping a button in the app, on a device that authenticated with a password or an OAuth sign-in. A pplt_… token, however many scopes it carries, is rejected on that route.

What this actually stops

An agent can’t grant itself permission by racing its own question.
A leaked or overly-broad token can page you, but can’t act on your behalf when you’re the thing being asked.
The audit trail (answeredBy on every resolved ask) always names a person, never a service.

What it doesn’t stop

It’s not a defense against a compromised phone, or against you tapping Approve on something you didn’t read. The guarantee is narrower and more useful than that: whatever asked the question isn’t the same thing that gets to answer it.

See make your agent wait for the mechanics, and scoped agent tokens for what a token can and can’t do more broadly.

Make your agent wait for you

Sat, 01 Aug 2026 00:00:00 GMT

An agent that can act without asking is fast and occasionally wrong in ways you find out about later. paperplane_ask is the other option: the agent sends a question, your phone shows buttons, and the tool call doesn’t return until you tap one — or the timeout fires.

The call

{
  "title": "Deploy staging to production?",
  "message": "12 files changed, all checks green.",
  "options": [
    { "id": "approve", "label": "Approve", "tone": "positive" },
    { "id": "deny", "label": "Deny", "tone": "destructive" }
  ],
  "timeoutSec": 300
}

Omit options and you get a default Approve/Deny pair. timeoutSec runs 5 seconds to 24 hours; without defaultOptionId, an expired ask resolves as timeout with no option chosen — treat that as a denial, not a green light.

What happens while it waits

The agent polls in the background — starting at 2 seconds, backing off ×1.5, capped at 15 seconds — so a fast answer costs almost nothing and a slow one doesn’t hammer the server. You see a normal notification with buttons; tapping one ends the poll on the next check.

What comes back

{
  "status": "answered",
  "optionId": "approve",
  "optionLabel": "Approve",
  "answeredBy": "<username>",
  "elapsedSec": 41
}

answeredBy is who tapped it, which matters the moment more than one person can answer a channel’s asks.

See scoped agent tokens for why the agent can’t answer its own question, and tool-call timeout recovery for what to do if your MCP client gives up before the person does.

Get a push notification when your coding agent finishes

Sat, 01 Aug 2026 00:00:00 GMT

Not every notification needs an answer. When you just want to know a job finished — a long test run, a build, a migration — paperplane_send_event is the plain version of paging you: no buttons, no wait, just a push.

The call

{
  "title": "Tests finished",
  "message": "482 passed, 0 failed, 3 skipped — 14m runtime.",
  "nature": "critical"
}

Set nature to error, failure, failed, critical or pending — or priority to high, crit, critical or urgent — and it’s promoted from a plain notification to an alert you can acknowledge or resolve, badged until you do. Anything else is a message you read and move past.

Setup

Add paperplane-mcp to your MCP client config once:

{
  "mcpServers": {
    "paperplane": {
      "command": "npx",
      "args": ["-y", "paperplane-mcp"],
      "env": { "PAPERPLANE_TOKEN": "pplt_..." }
    }
  }
}

From there, any agent that speaks MCP — Claude Code, Claude Desktop, Cursor — can page you without you asking it to check in.

When to reach for `paperplane_ask` instead

If the next step actually depends on your answer — approve, pick a path, confirm something destructive — use paperplane_ask instead. It’s the same channel, but it blocks the agent until you’ve actually decided, rather than notifying you and moving on regardless.

A revocable, scoped token for your agent

Sat, 01 Aug 2026 00:00:00 GMT

Handing an agent your Paperplane sign-in would mean handing it everything: your account, every channel, every other token. A personal access token is narrower on purpose.

The token

Minted in the app under Settings → Developer tokens, shown once as pplt_ followed by 64 hex characters. Paperplane stores only its SHA-256 hash — a lost token can’t be recovered, only replaced.

{
  "mcpServers": {
    "paperplane": {
      "command": "npx",
      "args": ["-y", "paperplane-mcp"],
      "env": {
        "PAPERPLANE_TOKEN": "pplt_...",
        "PAPERPLANE_DEFAULT_CHANNEL": "Builds"
      }
    }
  }
}

Six scopes

events:write, channels:read, messages:read, messages:write, tickets:read, tickets:write. A token minted in the app carries all six; nothing stops you from asking for a narrower one for a script that should only ever send events.

What no token can do

Regardless of scope, a personal access token can never create or delete a channel, rotate an endpoint key, manage membership, run message retention, or mint or revoke another token. Those stay session-only — a signed-in human, in the app. The same rule is what makes an agent unable to approve its own deploy: answering an ask is session-only too.

Housekeeping

Up to 20 active tokens per account, an optional expiry from 1 to 3,650 days, and lastUsedAt visible in the app so a stale token is easy to spot. Revoking one is immediate — the next request with it gets a 401, and the MCP connector fails fast on that with a clear stderr message rather than a confusing mid-conversation error.

When your agent's tool call times out but you haven't answered

Sat, 01 Aug 2026 00:00:00 GMT

paperplane_ask can legitimately take minutes — that’s the point, it’s waiting on you. But most MCP clients impose their own tool-call timeout, shorter than the timeoutSec you set. If the client’s clock runs out first, you’ll see a client-side timeout error, not the ask’s actual result.

The ask doesn’t know the client gave up

Nothing about that timeout reaches Paperplane’s backend. The ask keeps waiting exactly as configured, on the server, independent of whatever the MCP client decided to do. If you tap Approve two minutes after the client stopped waiting, the ask still resolves to answered — the client just never heard about it.

Recovering it

// paperplane_check_ask
{ "channel": "Builds", "messageId": "msg_8a2f..." }

// → non-blocking read, any time after
{ "status": "answered", "optionId": "approve", "answeredBy": "<username>" }

paperplane_check_ask is a plain read — no polling, no wait. Call it with the messageId from the original paperplane_ask call (visible in your own conversation, or found via paperplane_list_messages) and you get whatever the ask has resolved to right now: pending, answered, or timeout.

The practical rule

Set timeoutSec shorter than you’d like to wait, not as long as you can stand — a client-side timeout is worse than a slightly early timeout status, because a client timeout gives you no result to act on at all. If you don’t control the client’s own limit, keep paperplane_check_ask as your fallback path rather than re-asking, which would send a second notification for the same decision.

Paperplane currently sends no MCP progress notifications on a pending ask, so a client that extends its own timeout on progress updates gets no help here — plan around the hard timeout, not around progress.

ntfy alternative

Sat, 01 Aug 2026 00:00:00 GMT

ntfy gets more right than most alternatives on this list. It’s free, it’s open source, you can self-host it in one container or use the public instance, and — this is the one worth being upfront about — it already has action buttons: an http action fires a webhook when you tap the notification, the same shape as a Paperplane callback.

So the honest comparison isn’t “Paperplane has buttons and ntfy doesn’t.” It’s narrower: ntfy’s action doesn’t carry a cooldown or a logged trigger history the way a Paperplane callback does, and there’s nothing past that single tap — no lifecycle, no blocking question an agent can wait on, no shared board for the follow-up. If a topic needs an account-free, self-hosted pub/sub channel with a webhook button, ntfy already does that, for free.

What it doesn’t do is the part built for agents: paperplane_ask blocking a tool call until a human taps an option, with a token that can page you but can’t answer its own question. If that’s what you’re after, that gap is the whole reason to look at Paperplane instead.

See make your agent wait for how the blocking ask works.

Pushbullet alternative

Sat, 01 Aug 2026 00:00:00 GMT

Pushbullet’s core product is mirroring — notifications, links, files, copy-paste, moving between your own phone and laptop. Its API for sending a custom push is a secondary feature bolted onto that, which is why people using it for machine alerts tend to hit the free tier’s push cap and then face a subscription meant for a different use case.

There’s no per-source channel model: a push from your CI pipeline and a push from your monitoring rule land the same way a shared link does, with no thread, no lifecycle, and no button that fires a webhook back at your infrastructure. It’s also a single-user tool — sharing means syncing your own devices, not inviting a teammate into a channel.

If what you actually want is “mirror my phone’s notifications to my laptop,” Pushbullet does that well and Paperplane doesn’t try to. If you want a channel per system with buttons that do something and an agent that can wait on your answer, that’s a different tool.

See the API contract for how a Paperplane channel works.

Pushcut alternative

Sat, 01 Aug 2026 00:00:00 GMT

Pushcut’s strength is specific: a notification can trigger an Apple Shortcuts automation directly on your phone, no server round-trip required. If your workflow already lives in Shortcuts and you’re iOS-only, that’s a real capability Paperplane doesn’t have at all — Paperplane’s callbacks fire a webhook you host, not a Shortcut on your device.

What Pushcut doesn’t have is a model for systems. It’s built around notification templates you configure once, not a channel per source that reads like a thread of everything that system has said. There’s no ack/resolve lifecycle, no ticket board to defer something onto, and — since it’s a personal automation tool rather than a developer inbox — no concept of an AI agent blocking on your approval before it continues.

If you want deep on-device automation and don’t need Android, Pushcut is the better fit. If you want a cross-platform inbox organized by source, with an agent that can genuinely wait for you, that’s the gap Paperplane fills.

See the API contract for how a channel’s endpoint works, or make your agent wait for the blocking ask.

Pushover alternative

Sat, 01 Aug 2026 00:00:00 GMT

Pushover does one thing and has done it for over a decade: a token, a user key, and a POST turns into a push notification. It’s cheap, it’s everywhere, and it isn’t going to disappear.

Where it stops is where Paperplane starts. Pushover has no notion of an agent that blocks on your answer — it can repeat an emergency-priority alert until you acknowledge it via a separate API call, which is close to a lifecycle but isn’t buttons on the notification. It has no way to attach a labelled webhook that fires when you tap it. And it has nothing for AI agents specifically — no MCP connector, no concept of a token that can page you but can’t answer its own question.

If your need is “get a reliable ping from a script,” that gap doesn’t matter and Pushover wins on price and maturity alone. If you want an agent to ask you something and actually wait for a human, or a notification with real buttons wired to your infrastructure, that’s the part Pushover doesn’t have.

See make your agent wait for the blocking-ask mechanics, or the API contract for the full payload.

Get notified when a cron job or systemd service fails

Sat, 01 Aug 2026 00:00:00 GMT

Cron’s default is to email every run’s output to a local mail spool nobody reads. The fix is the same either way: check the exit code, and only notify on failure.

Cron

Wrap the job in a small script rather than editing the crontab line itself — easier to test and to reuse:

#!/usr/bin/env bash
set -euo pipefail

if ! /usr/local/bin/nightly-backup.sh; then
  curl -sS -X POST "https://<host>/events/<username>/Backups" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Nightly backup failed",
      "message": "'"$(hostname)"' — see /var/log/backup.log",
      "priority": "High",
      "nature": "error"
    }'
  exit 1
fi

Point cron at the wrapper, not the underlying command:

0 3 * * * /usr/local/bin/backup-with-alert.sh

systemd

A oneshot service can use OnFailure= to trigger a second unit only when the first one fails — no wrapper script needed:

# /etc/systemd/system/backup.service
[Unit]
Description=Nightly backup
OnFailure=notify-paperplane@%n.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/nightly-backup.sh

# /etc/systemd/system/notify-paperplane@.service
[Unit]
Description=Notify Paperplane that %i failed

[Service]
Type=oneshot
ExecStart=/usr/bin/curl -sS -X POST "https://<host>/events/<username>/Backups" \
  -H "Content-Type: application/json" \
  -d '{"title":"systemd unit failed","message":"%i","priority":"High","nature":"error"}'

%i and %n expand to the failed unit’s name, so one notify-paperplane@ template covers every service you attach it to.

Get a phone notification when a GitHub Actions run fails

Sat, 01 Aug 2026 00:00:00 GMT

GitHub’s own notification settings bury a CI failure in an inbox with everything else. A curl step at the end of the job sends it straight to a channel of its own.

The step

- name: Notify Paperplane
  if: failure()
  run: |
    curl -sS -X POST "${{ secrets.PAPERPLANE_ENDPOINT }}" \
      -H "Content-Type: application/json" \
      -H "X-Paperplane-Endpoint-Key: ${{ secrets.PAPERPLANE_KEY }}" \
      -d '{
        "title": "CI failed on main",
        "message": "'"${{ github.workflow }}"' · ${{ github.sha }}",
        "priority": "High",
        "nature": "error"
      }'

PAPERPLANE_ENDPOINT is the full channel URL from Channel → Details; PAPERPLANE_KEY is that channel’s endpoint key, if you set one. priority: High and nature: error promote this from a message you scroll past to an alert you have to acknowledge or resolve.

Only on success, too

Drop if: failure() for if: always() and branch on ${{ job.status }} in the message if you also want a quiet confirmation when a deploy job succeeds — useful for anything long enough that you’ve stopped watching the terminal.

Add a button

A Paperplane callback fires a plain, unauthenticated GET/POST — GitHub’s re-run API needs a bearer token, so you can’t point a callback straight at api.github.com. Put a small relay in between (a Cloudflare Worker route or similar) that holds the GitHub token and calls the re-run API when hit:

"callback": [
  { "label": "Re-run", "webhook": "https://your-relay.example.com/rerun/RUN_ID" }
]

See the API contract for the full callback shape and its cooldown.

Route Grafana alerts to your phone

Sat, 01 Aug 2026 00:00:00 GMT

Grafana’s alerting webhook payload carries a full alert group — labels, annotations, state, a commonLabels block — not a flat title/message. Rather than fight Grafana’s templating for an exact match, point it at a small relay that reshapes the payload and forwards it.

The relay

A few lines is enough — this one runs on Cloudflare Workers, but any small HTTP handler works the same way:

export default {
  async fetch(request, env) {
    const alert = await request.json();
    const first = alert.alerts?.[0];
    const firing = alert.status === 'firing';

    await fetch(`https://<host>/events/<username>/Grafana`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        title: `${firing ? 'Alert' : 'Resolved'}: ${alert.commonLabels?.alertname ?? 'Grafana'}`,
        message: first?.annotations?.summary ?? alert.message ?? 'No summary provided',
        priority: firing ? 'High' : 'Low',
        nature: firing ? 'error' : undefined,
        dataJson: JSON.stringify(alert.commonLabels ?? {}),
      }),
    });

    return new Response('ok');
  },
};

Wiring it up

Alerting → Contact points → Add contact point, type Webhook.
Set the URL to your relay, not directly to Paperplane.
Attach the contact point to a notification policy scoped to whichever alert rules should reach your phone — not everything Grafana tracks needs to page you.

Why a relay instead of Grafana’s own templating

Grafana can template the webhook body directly in newer versions, which avoids the extra hop if you’re comfortable with its templating syntax. The relay is the more durable recipe here: it doesn’t depend on which Grafana version you’re running, and it’s the same pattern you’d reuse for any tool — like Stripe — whose webhook payload doesn’t already match Paperplane’s shape.

Notify your phone from any shell script

Sat, 01 Aug 2026 00:00:00 GMT

If a script can run curl, it can reach your phone. This is the whole integration — everything else in the recipes section is this same request, reshaped for a specific tool’s webhook format.

The one-liner

curl -X POST "https://<host>/events/<username>/<Channel%20Name>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Job finished","message":"'"$(hostname)"' at '"$(date -Is)"'"}'

title and message are the only required fields. Everything else — priority, nature, dataJson, callback — is optional on the same payload; see the API contract for the full list.

A reusable function

Drop this in .bashrc or a shared script library and every job just calls notify:

notify() {
  local title="$1" message="$2" nature="${3:-}"
  curl -sS -X POST "https://<host>/events/<username>/Scripts" \
    -H "Content-Type: application/json" \
    -d "$(printf '{"title":%s,"message":%s%s}' \
      "$(jq -Rn --arg t "$title" '$t')" \
      "$(jq -Rn --arg m "$message" '$m')" \
      "${nature:+,\"nature\":\"$nature\"}")"
}

notify "Backup done" "$(hostname) — $(date)"
notify "Disk almost full" "/var at 94%" "critical"

jq -Rn --arg handles the JSON-escaping for you, so a message with quotes or newlines in it doesn’t break the payload — worth the one extra dependency the moment your messages aren’t hand-typed constants.

Get notified when a Stripe payment fails

Sat, 01 Aug 2026 00:00:00 GMT

Stripe webhooks POST Stripe’s own event shape — { "type": "invoice.payment_failed", "data": { "object": {...} } } — not something you can point at a Paperplane endpoint directly. The honest recipe is a small relay: receive the Stripe event, verify its signature, forward a Paperplane-shaped payload.

The relay

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export default async function handler(req, res) {
  const signature = req.headers['stripe-signature'];
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.rawBody, signature, process.env.STRIPE_WEBHOOK_SECRET);
  } catch {
    return res.status(400).send('Invalid signature');
  }

  if (event.type === 'invoice.payment_failed') {
    const invoice = event.data.object;
    await fetch('https://<host>/events/<username>/Billing', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        title: 'Payment failed',
        message: `${invoice.customer_email ?? invoice.customer} — $${(invoice.amount_due / 100).toFixed(2)}`,
        priority: 'High',
        nature: 'error',
        dataJson: JSON.stringify({ invoiceId: invoice.id }),
      }),
    });
  }

  res.status(200).send('ok');
}

Verifying stripe-signature matters here specifically: this endpoint is publicly reachable, and skipping verification means anyone who finds the URL can send you a fake “payment failed” page.

Add a resolve button

If you refund or retry the charge from a dashboard you host, attach a callback so the notification can trigger that directly — see the API contract for the shape, and cron/systemd for a simpler starting point if webhook signing feels like overkill for now.

Send Uptime Kuma alerts to your phone

Sat, 01 Aug 2026 00:00:00 GMT

Uptime Kuma’s default webhook payload is shaped for its own dashboard, not for Paperplane’s title/message fields — so the notification needs a custom body template, which Uptime Kuma supports natively.

Set up the notification

Settings → Notifications → Setup Notification, type Webhook.
Set the URL to your channel’s endpoint: https://<host>/events/<username>/Uptime.
Turn on Custom Body, and set the request body to match Paperplane’s payload, using Uptime Kuma’s template variables:

{
  "title": "{{ monitorJSON.name }} is {{ heartbeatJSON.status }}",
  "message": "{{ msg }}",
  "priority": "High",
  "nature": "pending"
}

If the channel has an endpoint key, add it as a custom header field if your Uptime Kuma version exposes one for webhook notifications — otherwise lock the channel down by IP or leave it open behind Uptime Kuma’s own network.
Attach the notification to each monitor you want on your phone, or set it as a default for new monitors.

Why `nature: pending`

An Uptime Kuma “down” event isn’t necessarily an error you can fix yet — it might resolve itself. pending still promotes it to an alert you have to acknowledge, without asserting it’s already a confirmed failure. Switch to error if you’d rather every down event page you as a hard failure from the start.

Uptime Kuma sends a second notification when the monitor recovers — that one lands as a plain message unless you also set nature/priority in a second template for the “up” case.

Paperplane

Your agent can't approve its own deploy

Why a token isn’t enough

What this actually stops

What it doesn’t stop

Make your agent wait for you

The call

What happens while it waits

What comes back

Get a push notification when your coding agent finishes

The call

Setup

When to reach for paperplane_ask instead

A revocable, scoped token for your agent

The token

Six scopes

What no token can do

Housekeeping

When your agent's tool call times out but you haven't answered

The ask doesn’t know the client gave up

Recovering it

The practical rule

ntfy alternative

Pushbullet alternative

Pushcut alternative

Pushover alternative

Get notified when a cron job or systemd service fails

Cron

systemd

Get a phone notification when a GitHub Actions run fails

The step

Only on success, too

Add a button

Route Grafana alerts to your phone

The relay

Wiring it up

Why a relay instead of Grafana’s own templating

Notify your phone from any shell script

The one-liner

A reusable function

Get notified when a Stripe payment fails

The relay

Add a resolve button

Send Uptime Kuma alerts to your phone

Set up the notification

Why nature: pending

When to reach for `paperplane_ask` instead

Why `nature: pending`