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.
| Way | Request | Best for |
|---|---|---|
| 1. Key in the URL | POST /p/<key> | Scripts, cron jobs, quick tests. The shortest command to paste. |
| 2. Key in a header | POST /v1/send | CI, servers, apps. The key stays out of logs and shell history. |
| 3. Open a link | GET /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_KEYOr 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_KEYUse 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/sendThe 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.
3. Open a link: GET /p/<key>/<message>
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=homeEncode 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 whenContent-Typeisapplication/json, or when the body is a JSON object, as withcurl -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 isgeneral. - 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:
| Code | Meaning | What to do |
|---|---|---|
| 400 | Empty or too long message, invalid channel, or malformed JSON | Fix the request; retrying won't help |
| 401 | Missing, malformed or revoked send key | Copy the current key from the app |
| 402 | The free plan's 100 messages this month are used up | Upgrade to Pro in the app, or wait for the next month (UTC) |
| 413 | Body larger than 16 KiB | Send a shorter message |
| 429 | Too many requests in a short time, or Pro's fair-use 5,000 a day reached | Wait and retry with backoff; don't loop |
| 500 | Server error; the message was not saved | Retry 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_humantool. 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.