# apumail SMS — agent-native SMS (send + receive verification codes)

> Send and receive SMS the same way apumail does email: push OTP/alerts,
> receive verification codes on a real number, extract the OTP automatically.
> PAID + account-gated. Operator console for humans: https://sms.apumail.com

## Auth (one-time human step, then fully headless)

1. A human signs in once at https://api.apumail.com/account ("Sign in with notlogin").
2. Mint an account API token: `POST https://api.apumail.com/api/v1/account/tokens {label}`
   → `acct_…` (shown ONCE). This is browser-cookie-gated (a token can't mint tokens).
3. The agent then drives everything with `Authorization: Bearer acct_…`. No browser after step 1.

## What you can do

- **Send an SMS with NO number** (recipients can't reply) — works immediately.
- **Rent a dedicated number** — receive codes AND reply on it.

Pricing: dedicated number **$18/yr** (USDC) · **$14.40/yr** ($PROWL) · every send **$0.07** (prepaid credit) · **receiving is free**.

## Path A — send-only (no number)

```bash
# 1. Check your prepaid balance
curl -sS -H "Authorization: Bearer $ACCT" https://sms.apumail.com/api/v1/sms/credit

# 2. Send (debits $0.07). 402 insufficient_credit if the balance is short — top up (below).
curl -sS -X POST -H "Authorization: Bearer $ACCT" -H "Content-Type: application/json" \
  -d '{"to":"+14155550123","text":"Your code is 123456"}' \
  https://sms.apumail.com/api/v1/sms/send
```

## Path B — dedicated number (receive + reply)

```bash
# 1. Quote a number (USDC list price) or the $PROWL rail
curl -sS -H "Authorization: Bearer $ACCT" "https://sms.apumail.com/api/v1/phones/available?country_code=US"
curl -sS -H "Authorization: Bearer $ACCT" https://sms.apumail.com/api/v1/phones/quote-usdc

# 2. Build an unsigned tx for in-wallet signing (owner_pubkey = your Solana wallet)
curl -sS -X POST -H "Authorization: Bearer $ACCT" -H "Content-Type: application/json" \
  -d '{"owner_pubkey":"<YOUR_SOL_ADDRESS>"}' https://sms.apumail.com/api/v1/phones/build-tx-usdc
# → sign tx_base64 with your wallet, submit to Solana, get the signature

# 3. Redeem the payment → buys the number + 1 paid year (token shown ONCE)
curl -sS -X POST -H "Authorization: Bearer $ACCT" -H "Content-Type: application/json" \
  -d '{"country_code":"US","tx_signature":"<SIG>"}' https://sms.apumail.com/api/v1/phones/pay-usdc

# 4. Operate it with the phone token
curl -sS -H "Authorization: Bearer $PHONE_TOKEN" "https://sms.apumail.com/api/v1/phone/$NUMBER/wait?timeout=120"
curl -sS -H "Authorization: Bearer $PHONE_TOKEN" https://sms.apumail.com/api/v1/phone/$NUMBER/latest   # → {message, otp}
curl -sS -X POST -H "Authorization: Bearer $PHONE_TOKEN" -H "Content-Type: application/json" \
  -d '{"to":"+14155551234","text":"reply"}' https://sms.apumail.com/api/v1/phone/$NUMBER/send
```

The `-prowl` twin of every step is 20% cheaper: `quote-prowl`, `build-tx-prowl`, `pay-prowl`.

## Top up prepaid send credit (funds all sends, 1:1 USD, min $5)

```bash
curl -sS -H "Authorization: Bearer $ACCT" "https://sms.apumail.com/api/v1/sms/credit/quote-usdc?amount_usd=10"
curl -sS -X POST -H "Authorization: Bearer $ACCT" -H "Content-Type: application/json" \
  -d '{"owner_pubkey":"<YOUR_SOL_ADDRESS>","amount_usd":10}' https://sms.apumail.com/api/v1/sms/credit/build-tx-usdc
# sign → submit → then:
curl -sS -X POST -H "Authorization: Bearer $ACCT" -H "Content-Type: application/json" \
  -d '{"amount_usd":10,"tx_signature":"<SIG>"}' https://sms.apumail.com/api/v1/sms/credit/pay-usdc
```

## MCP

Over MCP (`https://api.apumail.com/mcp`):
- Operate an already-bought number: `wait_for_sms`, `read_sms`,
  `extract_latest_sms_otp`, `send_sms`, `delete_phone_inbox` (args: number + phone-token).
- No number needed: `send_sms_no_number` (send-only) + `sms_credit_balance`,
  authed with an account token (`account_token: acct_…`).
Buying a number + topping up credit stay REST-only (they need an in-wallet signature).

## Endpoints (all reachable on this host)

- `POST   /api/v1/sms/send {to, text}` — send-only (no number). Debits credit.
- `GET    /api/v1/sms/sent` — send-only history.
- `GET    /api/v1/sms/credit` — balance. `.../credit/quote-{usdc,prowl}`, `.../credit/build-tx-{usdc,prowl}`, `.../credit/pay-{usdc,prowl}` — top up.
- `GET    /api/v1/phones/available?country_code=US` — number quote.
- `GET    /api/v1/phones/quote-{usdc,prowl}`, `POST .../build-tx-{usdc,prowl}`, `POST /api/v1/phones/pay-{usdc,prowl}` — buy a number.
- `GET    /api/v1/phone/:number` · `/latest` · `/wait` · `/sent` — read inbound + OTP. `POST /api/v1/phone/:number/send` — reply. `DELETE` — drop history.

Full email + SMS reference: https://api.apumail.com/llms.txt · JSON capabilities: https://api.apumail.com/api/v1/info