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

# SMS overview

> Send, schedule, and track SMS messages with Dugble

Dugble provides one API for sending application-to-person SMS messages. Each send validates the destination and sender ID, calculates the message segment count, and queues delivery atomically.

## Before you send

You need:

* A Dugble team and a team token with the `sms:send` permission
* An approved sender ID for the destination country
* A supported recipient number in E.164 format
* A non-empty message body

<Note>
  Keep team tokens on your server. Never expose them in browser or mobile application code.
</Note>

## Send an SMS

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/sms \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: verification-user-42" \
  --data '{
    "to": "+233201234567",
    "from": "Dugble",
    "body": "Your verification code is 123456.",
    "metadata": {
      "user_id": "user_42"
    }
  }'
```

A successful request returns `202 Accepted`:

```json theme={null}
{
  "success": true,
  "data": {
    "object": "sms",
    "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
  }
}
```

Store the Dugble message ID with your application record so you can retrieve the latest delivery state later.

## Recipient and content rules

* `to` must be a supported E.164 number such as `+233201234567`.
* `from` must match an approved sender ID and can be at most 11 characters.
* `body` is required and can contain up to 1,600 Unicode characters.
* `metadata` is optional and must be valid JSON.

## Message segments

Dugble determines whether the message uses GSM-7 or UCS-2 encoding and calculates the number of SMS segments required. The retrieve response includes the resulting `segments` value.

Longer messages may use multiple billable segments even though they are submitted through one API request.

## List and filter messages

Use `GET /sms` to retrieve message history. The endpoint supports `limit` and `offset`, plus filters that can be combined:

| Parameter    | Description                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `status`     | Exact normalized SMS status.                                                                   |
| `sender`     | Exact sender identity matching the message's `from` value.                                     |
| `start_date` | Include messages created at or after this RFC 3339 timestamp.                                  |
| `end_date`   | Include messages created at or before this RFC 3339 timestamp. Must not precede `start_date`.  |
| `search`     | Case-insensitive partial match across recipient, sender, message body, or provider message ID. |

```bash theme={null}
curl --get https://api.dugble.com/sms \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --data-urlencode "status=delivered" \
  --data-urlencode "sender=Dugble" \
  --data-urlencode "start_date=2026-08-01T00:00:00Z" \
  --data-urlencode "search=verification"
```

## Track a message

```bash theme={null}
curl --request GET \
  --url https://api.dugble.com/sms/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 \
  --header "Authorization: Bearer $DUGBLE_API_KEY"
```

The `last_event` field contains the latest normalized delivery state.

<CardGroup cols={2}>
  <Card title="Sending SMS" icon="message" href="/docs/sms/sending-sms">
    Learn the request fields and recommended sending workflow.
  </Card>

  <Card title="Sender IDs" icon="signature" href="/docs/sms/sender-ids">
    Understand sender approval and country-specific identity.
  </Card>

  <Card title="Schedule SMS" icon="clock" href="/docs/sms/schedule-sms">
    Send later, reschedule, or cancel a scheduled SMS.
  </Card>

  <Card title="Delivery status" icon="signal-bars" href="/docs/sms/delivery-status">
    Interpret normalized delivery states and failures.
  </Card>

  <Card title="SMS analytics" icon="chart-line" href="/docs/sms/analytics">
    Review delivery rates and country-level performance.
  </Card>
</CardGroup>