# NextMsg

> NextMsg is a one-way messenger: AI agents, scripts, CI jobs and servers send short text messages to a person's phone with one HTTP request. The person only reads; there is no reply channel. Use it to tell a human that something finished, failed or needs their attention.

The human installs the NextMsg app, which gives them a personal **send key** (`snd_live_…`). Ask them for it (or read it from an environment variable such as `NEXTMSG_KEY`) and keep it secret: anyone with the key can send to their inbox. No account, OAuth or SDK is needed.

## Send a message

Plain text body:

```
curl -d 'Deploy finished' https://api.nextmsg.app/p/$NEXTMSG_KEY
```

JSON body (preferred when you want a channel):

```
POST https://api.nextmsg.app/p/{send_key}
Content-Type: application/json

{"message": "Build **failed** on `main`: 3 tests failing", "channel": "ci"}
```

With the key in a header instead of the URL:

```
POST https://api.nextmsg.app/v1/send
Authorization: Bearer {send_key}
Content-Type: application/json

{"message": "Research done: 12 sources summarized", "channel": "research"}
```

Success: HTTP 200 `{"success": true, "id": "<uuid v7>", "status": "queued"}`. The push usually arrives within a few seconds; offline devices receive it for up to 7 days.

## Fields and limits

- `message` (required for JSON): 1–640 characters (Unicode code points; an emoji may count as several). Leading and trailing whitespace is trimmed.
- `channel` (optional): lowercase `a-z`, `0-9`, `-`, `_`, 1–32 characters; default `general`. For plain-text bodies pass it as a query parameter: `?channel=ci`.
- Formatting rendered in the app: `**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``. Notification banners show plain text. Links are not clickable; there are no titles or attachments.
- Request body: at most 16 KiB.
- Write short, specific messages: what happened, where, and what the person should do. Lead with the outcome ("Build failed on main" rather than "Hello! I wanted to let you know…").

## Errors

- 400: invalid message (empty, over 640 characters, non-string, JSON that isn't an object) or invalid channel. The body is `{"error": "..."}`.
- 401: missing, malformed, unknown or rotated send key.
- 402: the free plan's monthly limit (100 messages) is reached; the person can upgrade in the app.
- 413: request body too large.
- 429: rate limited. Wait and retry with backoff; don't loop.

## Examples

- GitHub Actions: `curl -s -d "Build failed on ${{ github.ref_name }}" "https://api.nextmsg.app/p/${{ secrets.NEXTMSG_KEY }}?channel=ci"`
- Claude Code hook (`~/.claude/settings.json`): run the curl command from a `Stop` or `Notification` hook.
- Python: `requests.post(f"https://api.nextmsg.app/p/{key}", json={"message": "Training finished", "channel": "ml"})`

## More

- Website: https://nextmsg.app
- Privacy: https://nextmsg.app/privacy