​

Before you start

• Create an API key in the Rewrite dashboard.
• Keep the key server-side only.
• Use a valid destination number in E.164 format, for example +5511999999999.
• If you want deterministic test behavior, use Sandbox.

​

Send your first SMS

curl -X POST "https://api.rewritetoday.com/v1/messages" \
  -H "Authorization: Bearer rw_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg:quickstart:2026-05-06T18:30" \
  -d '{
    "to": "+5511999999999",
    "content": "Rewrite: your verification code is 123456",
    "tags": {
      "flow": "quickstart"
    }
  }'

{
  "ok": true,
  "data": {
    "id": "748395130237498500",
    "createdAt": "2026-05-06T18:30:00.000Z",
    "analysis": {
      "characters": 39,
      "encoding": "gsm7",
      "segments": {
        "concat": 153,
        "count": 1,
        "reason": "fits",
        "single": 160
      }
    },
    "sandbox": false
  }
}

​

Common next steps

• Read the created resource later with GET /messages/{id}.
• Send batches with POST /messages/batch.
• Add webhooks to receive message.sent, message.delivered, message.failed, message.received, message.batch, and sms.otp.
• Use templates when you need locale-aware template reads and template-backed sends.
• Use Sandbox magic numbers to force deterministic outcomes while testing.

​

Troubleshooting

• 400 INVALID_JSON_BODY: request body, phone number, or route-specific validation failed.
• 401 INVALID_OR_MISSING_API_KEY: bearer token is missing or invalid.
• 403 API_KEY_MODE_MISMATCH: your API key mode does not match the current project mode.
• 403 PROJECT_SUBSCRIPTION_REQUIRED or PROJECT_BILLING_PAYMENT_REQUIRED: project is blocked from sending.
• 429 RATE_LIMITED: back off and honor the retry headers.