# NextMsg Full API Reference

> 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 (iOS or Android), 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:

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

JSON body (preferred when you want a channel):

```http
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:

```http
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 upon reconnecting.

## 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 Bad Request: invalid message (empty, over 640 characters, non-string, JSON that isn't an object) or invalid channel. The body is `{"error": "..."}`.
- 401 Unauthorized: missing, malformed, unknown or rotated send key.
- 402 Payment Required: the free plan's monthly limit (100 messages) is reached; the person can upgrade in the app.
- 413 Payload Too Large: request body exceeds 16 KiB limit.
- 429 Too Many Requests: rate limited. Wait and retry with backoff; don't loop.

## Integration Examples

### GitHub Actions
```yaml
- name: Notify NextMsg
  if: failure()
  run: |
    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 to notify your phone when a task is finished.

### Python
```python
import requests

requests.post(
    f"https://api.nextmsg.app/p/{send_key}",
    json={"message": "Training finished: accuracy 98.4%", "channel": "ml"}
)
```

### Node.js / TypeScript
```typescript
await fetch(`https://api.nextmsg.app/p/${sendKey}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Production deployment complete", channel: "deploy" })
});
```

## Model Context Protocol (MCP)

NextMsg provides an official MCP stdio server package: `@nextmsg/mcp`.
AI agents in Claude Desktop, Cursor, and Antigravity can use the `notify_human` tool directly instead of executing terminal curl commands.

### Claude Desktop Configuration
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "nextmsg": {
      "command": "npx",
      "args": ["-y", "@nextmsg/mcp"],
      "env": {
        "NEXTMSG_KEY": "snd_live_..."
      }
    }
  }
}
```

### Tool Definition: `notify_human`
- `message` (string, required): 1–640 Unicode characters.
- `channel` (string, optional, default "general"): 1–32 lowercase alphanumeric characters.
The send key is read only from the `NEXTMSG_KEY` environment variable, never from tool arguments, so it never enters the model context.

Usage: one notification per outcome (finished, failed, needs input) or when the user asks, never progress updates; don't use it to answer a user who is actively chatting; never include secrets, tokens or personal data (the text appears on the lock screen); if sending fails, tell the user in the conversation instead of retrying.

## OpenAPI 3.1 Specification

Machine-readable OpenAPI 3.1 documentation is available at:
- `https://api.nextmsg.app/openapi.json`

Use this URL to automatically import NextMsg into LangChain, CrewAI, AutoGen, or OpenAI Custom GPT Actions.

## Links

- [NextMsg Website](https://nextmsg.app): Official website and download links
- [OpenAPI Specification](https://api.nextmsg.app/openapi.json): Full OpenAPI 3.1 JSON schema
- [MCP Package](https://www.npmjs.com/package/@nextmsg/mcp): `@nextmsg/mcp` on npm
- [Privacy Policy](https://nextmsg.app/privacy): What is stored, why, and for how long