# Send Your First Message

Description: Send one SMS through Surge's shared demo number in under five minutes.
Related: /docs/overview/what-is-surge, /docs/registration/api-walkthrough, /docs/receiving, /sdks/typescript, /api-reference/endpoint/messages/create

Use this route when the goal is to prove the Surge integration works before carrier registration or phone-number purchase.

## Inputs You Need

- `SURGE_API_KEY`
- an account ID like `acct_01j...`
- a recipient number in E.164 format like `+18015551234`

## Request Contract

- Method: `POST`
- URL: `https://api.surge.app/accounts/{account_id}/messages`
- Required body fields:
  - `to`
  - `body`

Do not send a `from` number for the first test. New accounts use the shared demo number automatically.

## Recommended Implementation Order

1. Load the API key from an environment variable.
2. Read the account ID from your Surge dashboard or stored tenant record.
3. Send one message with only `to` and `body`.
4. Persist the returned message ID and conversation ID.
5. Confirm the recipient device receives the SMS.

## Expected Success

- HTTP success with a message object whose `id` starts with `msg_`
- nested `conversation.id` and `conversation.phone_number`
- delivery to the recipient within about 60 seconds

## Failure Cases To Handle

- `403` with `error.type = "demo_message_limit"`: the account exhausted its 25 demo sends; move to registration and a dedicated number
- invalid recipient formatting: normalize to E.164 before sending
- missing account ID: treat this as a setup error, not a retryable API failure

## When To Leave This Page

- For production readiness: `/docs/registration/api-walkthrough.md`
- For inbound handlers and delivery webhooks: `/docs/receiving.md`
- For language-specific idioms: `/sdks/typescript`, `/sdks/python`, `/sdks/ruby`, or `/sdks/elixir`