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

# SMS with your own number and per-country pricing

> Send SMS from the number you purchased (from): recipients see your line; price depends on destination country.

<Tip>
  **Your own number** means the SMS is sent from the **line you purchased** in the workspace. The recipient sees your area code or international number — not a generic platform sender. Pass **`from`** in the API or pick the line in the dashboard.
</Tip>

## Two ways to send SMS

|             | **Shared** (no `from`)                          | **Your own number** (with `from`)                       |
| ----------- | ----------------------------------------------- | ------------------------------------------------------- |
| Sender      | Platform shared line                            | **Your** purchased number                               |
| Price       | Fixed by send type (`full`, `standard`, `slow`) | **Per country** of the recipient                        |
| API field   | Omit `from`; use `options.speed`                | `from` required; `speed` **does not** apply             |
| Typical use | Bulk OTP, large campaigns                       | Brand with fixed area code, support, 2FA from your line |

Analogy: **shared** is mail with a generic carrier return address; **your own number** is mail with **your company name and address** on the envelope.

The number must be **ACTIVE**, SMS-enabled, purchased via [Phone numbers](/en/phone-numbers-api/como-funciona/quick-start).

***

## Send with your own number

```http theme={null}
POST /v1/sms/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

With E.164:

```json theme={null}
{
  "from": "+5511987654321",
  "to": ["5511999887766"],
  "type": "text",
  "payload": {
    "message": "Your order #8842 is out for delivery. Track: https://store.com/r/8842"
  }
}
```

With internal number ID (equivalent):

```json theme={null}
{
  "from": "clxx_phone_1",
  "to": ["5511999887766"],
  "type": "text",
  "payload": {
    "message": "Verification code: 739201. Do not share."
  }
}
```

**Response (202)**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 1,
    "messageIds": ["clsms_abc..."],
    "smsIds": ["clsms_abc..."]
  }
}
```

<Note>
  With `from` set, **`options.speed` is ignored**. Full, Standard, and Slow apply only to **shared** sends — with your line, price depends on the **destination country**, not send type.
</Note>

***

## How price is calculated

1. The API identifies the **country** from `to`.
2. Looks up the rate in `smsOwnNumber.rates` (`GET /v1/pricing`).
3. Debits credits (plan) or pay-as-you-go amount **per SMS** sent.

Example row in the public table:

```json theme={null}
{
  "country": "BR",
  "countryName": "Brasil",
  "callingCode": "55",
  "credits": 24,
  "paygCents": 3,
  "available": true,
  "unavailableReason": null
}
```

Country without a specific row → uses `smsOwnNumber.fallbackCountry` (e.g. `ZZ` for rest of world).

Query the full table:

```bash theme={null}
curl -s https://api.notifique.dev/v1/pricing | jq '.data.smsOwnNumber.rates[] | select(.country=="BR")'
```

Details: [Pricing API](/en/guides/precos/api-de-precos).

***

## Inbound SMS on your number

When the customer **replies** to your number, the message is stored as inbound:

```http theme={null}
GET /v1/sms/inbound?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
```

Webhook: `sms.received` / `sms.replied` — [Webhook events](/en/sms-api/como-funciona/eventos-do-webhooks).

***

## Common errors

| Situation                          | HTTP | `code`                      |
| ---------------------------------- | ---- | --------------------------- |
| Invalid or non-ACTIVE `from`       | 400  | `INVALID_FROM`              |
| Number without SMS enabled         | 400  | —                           |
| Destination not available in table | 400  | `DESTINATION_NOT_AVAILABLE` |
| Insufficient balance/credits       | 402  | `INSUFFICIENT_BALANCE`      |

***

## Next steps

* [SMS introduction](/en/sms-api/como-funciona/introducao): shared vs your own number
* [Quick Start](/en/sms-api/como-funciona/quick-start): first send
* [Phone numbers](/en/phone-numbers-api/como-funciona/quick-start): purchase a line with SMS