FWD SMS API
===========

Base URL: https://sms.fwd.dev
Dashboard: https://sms.fwd.dev/
Human docs: https://sms.fwd.dev/docs/

AUTHENTICATION
--------------
Application API keys are created in the dashboard. Send one as:

Authorization: Bearer fwd_sms_...

Twilio-compatible clients may use HTTP Basic Auth with the API key as the password:

AC_account_sid:fwd_sms_... (legacy compatibility only; AC_account_sid is a path placeholder)

API keys are application-scoped. Never expose them in browser code or source control.

ACCOUNT MANAGEMENT API
----------------------
Create an account-wide management key from the dashboard. It uses the `sms:manage` scope and can manage every application owned by the account.

GET /v1/applications
POST /v1/applications
PATCH /v1/applications/:applicationId
PUT /v1/applications/:applicationId/phone-numbers
GET /v1/applications/:applicationId/webhooks
POST /v1/applications/:applicationId/webhooks
DELETE /v1/applications/:applicationId/webhooks/:webhookId

Create application request:
{"name":"menu.miami","description":"Client menu management"}

Replace phone routes request:
{"phoneNumbers":["+13055550123","+13055550124"]}

Create webhook request:
{"name":"Production events","url":"https://example.com/webhooks/sms","events":["message.received","message.delivered"]}

SEND MESSAGE
------------
POST /v1/messages
Content-Type: application/json

Request:
{"to":"+13055550123","body":"Hello from FWD SMS"}

Response: 201
{"id":"msg_...","object":"message","status":"queued","to":"+13055550123","from":"+13053220816","body":"Hello from FWD SMS","gatewayId":"SM..."}

TWILIO-COMPATIBLE SEND
----------------------
POST /2010-04-01/Accounts/:accountSid/Messages.json
Content-Type: application/x-www-form-urlencoded

Fields:
To: E.164 destination number
Body: message text, maximum 1600 characters
From: accepted for compatibility but always uses the FWD shared sender

WEBHOOK EVENTS
--------------
message.received
message.sent
message.delivered
message.failed

Webhook requests are POST JSON and are signed using the webhook signing secret.

Example event:
{"id":"evt_...","type":"message.received","createdAt":"2026-01-01T00:00:00.000Z","data":{"id":"msg_...","status":"received","from":"+13055550123","to":"+13053220816","body":"..."}}

Webhook URLs must use HTTPS. Signing secrets are shown once when a webhook is created.

LIMITS AND SAFETY
-----------------
- Phone numbers must use E.164 format.
- Message bodies are limited to 1600 characters.
- The From number is fixed and cannot be selected by API clients.
- No production credential belongs in this document.