Send API

Updated November 18, 2026

One HTTP request sends a push to your phone. There are three ways to make it. All three use the same send key, the same limits and the same responses. Pick the one that fits where you send from.

WayRequestBest for
1. Key in the URLPOST /p/<key>Scripts, cron jobs, quick tests. The shortest command to paste.
2. Key in a headerPOST /v1/sendCI, servers, apps. The key stays out of logs and shell history.
3. Open a linkGET /p/<key>/<message>Bookmarks, iOS Shortcuts, tools that can only call a URL.

The base URL is https://api.nextmsg.app. Your send key is in the app under Settings and starts with nextmsg_live_. The examples below read it from the NEXTMSG_KEY environment variable.

1. Key in the URL: POST /p/<key>

Send the message as the request body. Plain text works without any headers:

curl -d 'Deploy done ๐Ÿš€' https://api.nextmsg.app/p/$NEXTMSG_KEY

Or send JSON with a channel:

curl -H 'Content-Type: application/json' \
  -d '{"message": "Backup **failed** on db-1", "channel": "backups"}' \
  https://api.nextmsg.app/p/$NEXTMSG_KEY

Use single quotes: inside double quotes your shell treats ! and $ specially. To send a file or command output, use --data-binary @file.txt, which keeps line breaks.

2. Key in a header: POST /v1/send

The same body, with the key in an Authorization: Bearer header instead of the URL. Proxies, web server logs and shell history record URLs, but not headers, so this is the safer choice anywhere the request is logged.

curl -H "Authorization: Bearer $NEXTMSG_KEY" \
  -d 'Deploy done ๐Ÿš€' https://api.nextmsg.app/v1/send

The same in JavaScript (Node.js 18+, Deno, Bun, Cloudflare Workers, browsers):

await fetch("https://api.nextmsg.app/v1/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NEXTMSG_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ message: "Report ready", channel: "jobs" })
});

And in Python, with only the standard library:

import json, os, urllib.request

req = urllib.request.Request(
    "https://api.nextmsg.app/v1/send",
    data=json.dumps({"message": "Training finished", "channel": "ml"}).encode(),
    headers={"Authorization": f"Bearer {os.environ['NEXTMSG_KEY']}",
             "Content-Type": "application/json"},
)
urllib.request.urlopen(req, timeout=10)

In GitHub Actions, the NextMsg Notify action sends the key this way and masks it in logs.

The message is the last part of the URL. Opening the link sends it, so it works from a browser bookmark, an iOS Shortcut (Get Contents of URL), a home automation hub or any tool that can only call a URL:

https://api.nextmsg.app/p/YOUR_KEY/Garage%20door%20opened?channel=home

Encode the message for a URL: a space is %20, a line break %0A. Shortcuts and most tools do this for you.

A link is only sent when someone, or something you set up, actually opens it. Previews by chat apps and AI crawlers, link checkers and the browser preloading the address while you type do not send anything. Still, treat the link like a password: it contains your key, and it ends up in your browser history.

Message and channel

  • Plain text body: the whole body is the message. Set the channel with ?channel= in the URL.
  • JSON body: {"message": "...", "channel": "..."}. It is read as JSON when Content-Type is application/json, or when the body is a JSON object, as with curl -d '{...}'. Other fields are ignored.
  • Message: 1 to 640 characters (Unicode code points: a simple emoji is one, a flag or combined emoji several). The app renders **bold**, *italic*, ~~strike~~ and `code`. Links show as plain text and can't be tapped. Terminal color codes and invisible characters are removed.
  • Channel: optional, 1 to 32 characters from a-z, 0-9, - and _ (uppercase is lowercased). It groups messages into tabs in the app. The default is general.
  • Body size: up to 16 KiB.

Responses

A successful send returns HTTP 200:

{"success": true, "id": "019a8f2e-โ€ฆ", "status": "queued"}

The push usually arrives within a few seconds. "stored" instead of "queued" means the message is saved but the push couldn't be queued. The app picks it up the next time it syncs, so don't send it again. If your phone is offline, messages wait on the server for up to 72 hours.

Errors return JSON with an error field explaining what went wrong:

CodeMeaningWhat to do
400Empty or too long message, invalid channel, or malformed JSONFix the request; retrying won't help
401Missing, malformed or revoked send keyCopy the current key from the app
402The free plan's 100 messages this month are used upUpgrade to Pro in the app, or wait for the next month (UTC)
413Body larger than 16 KiBSend a shorter message
429Too many requests in a short time, or Pro's fair-use 5,000 a day reachedWait and retry with backoff; don't loop
500Server error; the message was not savedRetry once after a few seconds

Add -f to curl to make it exit with an error on any of these, or -fsS to stay quiet on success.

Limits

The free plan includes 100 messages a month. Pro is a one-time purchase with unlimited messages (fair use 5,000 a day). Short bursts are capped at 100 messages per 10 seconds per inbox. The key can only send to your inbox: it can't read messages or change anything.

If a key leaks, make a new one in the app under Settings. You can stop the old key at once, or keep it working for a short grace period while you update your scripts.

Other ways to send

  • AI agents: the @nextmsg/mcp server gives Claude, Cursor and other MCP clients a notify_human tool. From a terminal: npx @nextmsg/mcp "Build complete" --channel ci.
  • GitHub Actions: NextMsg Notify, uses: nextmsg-app/notify-action@v1.
  • OpenAPI: the machine-readable spec is at api.nextmsg.app/openapi.json, for Custom GPT actions and agent tool builders.
  • Recipes: the guides for cron jobs, servers, AWS and AI agents.