# MultiMessage

> Personal text outreach that actually follows up. MultiMessage exposes a REST API (v1) so third-party platforms
> and AI agents can send texts, read replies, check the remaining monthly text
> quota, and upgrade the pricing tier on demand.

- Base URL: https://multimessage.me
- OpenAPI 3.0 spec: https://multimessage.me/api/v1/openapi.json
- Endpoint reference: https://multimessage.me/api-reference
- Human quickstart: https://multimessage.me/developers
- Discovery index (no auth): GET https://multimessage.me/api/v1

## Authentication

Create an API key in the web app (https://multimessage.me/app), then send it on every request:

    Authorization: Bearer mm_live_...

Keys are account-scoped and revocable. Rate limit: 120 requests/minute per key.

Integrating platforms managing MANY accounts use an operator-issued PLATFORM
key (`mm_platform_...`) instead, adding `X-MM-Account: <account id>` on
GET /api/v1/usage and POST /api/v1/plan (its only permitted endpoints besides
GET /api/v1/accounts, which lists the account ids the key is authorized for —
store ids, never per-account secrets). Anything else returns 403 with code
`platform_key_scope`; an unlinked account id returns 404. POST /api/v1/plan
responses include `applied`: true means the plan is in effect now; false means
complete payment at `checkout_url` first.

## Endpoints

- GET  /api/v1                             — discovery index (no auth)
- GET  /api/v1/usage                       — plan, texts used/remaining this month, reset date
- GET  /api/v1/me                          — account summary + usage + tiers + poll cursor
- GET  /api/v1/tiers                       — pricing tiers (no auth)
- POST /api/v1/plan     {"plan": "..."}    — upgrade/downgrade the tier on demand
- POST /api/v1/messages {"address","body","client_ref?"} — send a text (idempotent on client_ref)
- GET  /api/v1/messages?since=CURSOR&wait=SECONDS — new messages + status changes; wait long-polls
- GET  /api/v1/messages/ID                 — one message (delivery status)
- GET  /api/v1/threads                     — conversation list
- GET  /api/v1/threads/ADDRESS/messages    — one conversation (any number format accepted)

## Quota ("how many texts are left?")

    GET /api/v1/usage
    -> {"plan": "growth", "texts_used": 412, "texts_cap": 2500,
        "texts_remaining": 2088, "can_send": true,
        "period": "calendar_month_utc", "resets_at": "2026-08-01T00:00:00Z"}

When the cap is reached, sends return 402 with code "cap_reached" — upgrade via
POST /api/v1/plan. With an active subscription the switch is immediate and
prorated; otherwise the response contains a checkout_url to complete payment.

## Sending

    curl -X POST https://multimessage.me/api/v1/messages \
      -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
      -d '{"address": "+17065551212", "body": "Hi!", "client_ref": "order-1042"}'

Retries with the same client_ref never double-send. Every send response includes
updated usage. Poll GET /api/v1/messages with the returned cursor (add
wait=25 to long-poll) to receive replies and delivery updates.

## Errors

All errors are JSON: {"error": "<human reason>", "code": "<machine code>"}.
Codes: invalid_api_key (401) · rate_limited (429) · invalid_request,
unknown_plan, invalid_address (400) · no_subscription, cap_reached, no_plan
(402) · no_route, exempt_account (409) · not_found (404) · billing_disabled
(503) · stripe_error (502).

## Pricing tiers

- starter: $65/mo — 1,000 texts/month — For getting started with personal outreach
- growth: $99/mo — 2,500 texts/month — For growing your follow-up volume
- pro: $199/mo — 6,000 texts/month — For high-volume outreach
- custom: need more? contact todd@innersitesolutions.com

## Contact

todd@innersitesolutions.com · InnerSite Solutions LLC