> ## Documentation Index
> Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Send your first SMS with Vobiz

> Send an SMS through the Vobiz Messaging API in four steps - get your credentials, pick a messaging number, call POST /messages, and track delivery by webhook or by polling.

This guide sends one SMS and shows you where its delivery status lands. It takes about five minutes if you already have an account.

<Steps>
  <Step title="Get your credentials">
    Sign in to the [Vobiz Console](https://console.vobiz.ai). Your **Auth ID** (`MA_…`) and **Auth Token** are on the dashboard. Send them as the `X-Auth-ID` and `X-Auth-Token` headers on every request.
  </Step>

  <Step title="Get a messaging number">
    List the numbers on your account that can send messages:

    ```bash cURL theme={null}
    curl "https://api.vobiz.ai/api/v1/sms/numbers" \
      -H "X-Auth-ID: MA_XXXXXXXX" \
      -H "X-Auth-Token: YOUR_AUTH_TOKEN"
    ```

    Use a number from the `numbers` array as `from`. If the list is empty, [buy a number](/docs/sms/numbers) or use the console under **SMS & RCS → Numbers**.

    <Note>
      US numbers need a registered [10DLC campaign](/docs/sms/compliance/us-10dlc-campaigns) or [toll-free verification](/docs/sms/compliance/us-toll-free) before they can send at scale. Each number's `registration.status` in the list above tells you where it stands.
    </Note>
  </Step>

  <Step title="Send the message">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://api.vobiz.ai/api/v1/sms/messages" \
        -H "X-Auth-ID: MA_XXXXXXXX" \
        -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "from": "+14155550100",
          "to": ["+14155550123"],
          "channel": "sms",
          "text": "Your verification code is 482913",
          "idempotencyKey": "otp-482913-user-77"
        }'
      ```

      ```python Python theme={null}
      import requests

      resp = requests.post(
          "https://api.vobiz.ai/api/v1/sms/messages",
          headers={
              "X-Auth-ID": "MA_XXXXXXXX",
              "X-Auth-Token": "YOUR_AUTH_TOKEN",
          },
          json={
              "from": "+14155550100",
              "to": ["+14155550123"],
              "channel": "sms",
              "text": "Your verification code is 482913",
              "idempotencyKey": "otp-482913-user-77",
          },
      )
      print(resp.status_code, resp.json())
      ```

      ```javascript Node theme={null}
      const resp = await fetch("https://api.vobiz.ai/api/v1/sms/messages", {
        method: "POST",
        headers: {
          "X-Auth-ID": "MA_XXXXXXXX",
          "X-Auth-Token": "YOUR_AUTH_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          from: "+14155550100",
          to: ["+14155550123"],
          channel: "sms",
          text: "Your verification code is 482913",
          idempotencyKey: "otp-482913-user-77",
        }),
      });
      console.log(resp.status, await resp.json());
      ```
    </CodeGroup>

    A `201` returns the message:

    ```json Response (201) theme={null}
    {
      "id": "9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01",
      "accountId": "MA_XXXXXXXX",
      "direction": "out",
      "channel": "sms",
      "from": "+14155550100",
      "to": "+14155550123",
      "text": "Your verification code is 482913",
      "mediaUrls": null,
      "status": "sent",
      "conversationId": "c7d1e9a3-2b4f-4a6c-8d5e-1f3a9b7c2e04",
      "createdAt": "2026-10-12T10:30:00Z",
      "updatedAt": "2026-10-12T10:30:00Z"
    }
    ```

    `sent` means the network accepted the message. Keep the `id`.

    <Warning>
      This call sends a real message and is billed per segment. Use your own numbers while you test.
    </Warning>
  </Step>

  <Step title="Track delivery">
    Poll the message until `status` becomes `delivered` or `failed`:

    ```bash cURL theme={null}
    curl "https://api.vobiz.ai/api/v1/sms/messages/9b2e1c40-8a3d-4f5e-9c1a-7d6b2e8f4a01" \
      -H "X-Auth-ID: MA_XXXXXXXX" \
      -H "X-Auth-Token: YOUR_AUTH_TOKEN"
    ```

    The response adds a `statusHistory` array with every state the message passed through. For production, subscribe to [webhooks](/docs/sms/webhooks) instead of polling, so delivery receipts and replies are pushed to your server.
  </Step>
</Steps>

<Check>
  You have sent an SMS and read its delivery status. The reply, if the recipient answers, lands in a [conversation](/docs/sms/conversations) with `direction: "in"`.
</Check>

## Next steps

<CardGroup cols={2}>
  <Card title="Retry safely" icon="rotate" href="/docs/sms/api/messages/send-message">
    Always send an `idempotencyKey`. A retry with the same key returns the original message instead of sending again.
  </Card>

  <Card title="Preview the cost" icon="calculator" href="/docs/sms/api/messages/cost-preview">
    See the segment count and price for a message before you send it.
  </Card>

  <Card title="Send to India" icon="flag" href="/docs/sms/compliance/india-dlt">
    Add your DLT entity, header and template IDs to every message to Indian numbers.
  </Card>

  <Card title="Go rich with RCS" icon="sparkles" href="/docs/sms/channels/rcs">
    Buttons, branding and SMS fallback from a verified RCS sender.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.