# Alphanumeric sender IDs

Send one-way international SMS from your brand name instead of a phone number, with a daily limit and per-country behaviour.

A sender ID lets your texts arrive from a name such as `ACME` instead of a number, the way banks and airlines send alerts. There is no number to buy, no monthly fee and no US registration. The trade-off: recipients cannot reply, and sender IDs do not work for the US, Canada or Puerto Rico.

## When to use one

| Use a sender ID for | Use a phone number for |
| --- | --- |
| One-way alerts, codes and notices abroad | Two-way conversations |
| Recipients outside North America | Recipients in the US, Canada or Puerto Rico |
| Text only | MMS |

## Create the name

`POST /v1/sms/sender-ids` with a `senderId`. It is usable at once.

```bash cURL
curl -X POST https://api.pozy.ai/v1/sms/sender-ids \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "senderId": "ACME" }'
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/sms/sender-ids", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ senderId: "ACME" }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.id, data.isActive);
```
```python Python
import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/sms/sender-ids",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={"senderId": "ACME"},
    timeout=30,
)
print(resp.json())
```

Rules for the name:

- 3 to 11 characters: letters, digits and spaces, with at least one letter.
- It must be your own brand. Names that imitate well-known brands or institutions (banks, payment providers, delivery companies, government bodies) are rejected with `422`.
- Names are not exclusive. Other workspaces can register the same name. Billing and delivery receipts always follow the workspace that sent the message.

`DELETE /v1/sms/sender-ids/{id}` deactivates a name. Creating the same name again brings it back.

## Send from it

Pass the name as `from` on the normal send endpoint:

```bash
curl -X POST https://api.pozy.ai/v1/sms/messages \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "ACME", "to": "+34612345678", "text": "Your Acme verification code is 482913" }'
```

Each segment bills at the destination's normal SMS rate. Delivery is reported with `message.delivered` and `message.failed`, like any SMS. See [Send SMS](https://pozy.ai/docs/telephony/sms).

## How countries display it

| Behaviour | Examples |
| --- | --- |
| Shows the name as sent | Most of Europe and many other markets |
| Replaces the name with a number to guarantee delivery | Some countries |
| Requires the name to be registered with local carriers first | India and the United Arab Emirates, among others. Contact support@pozy.ai for these. |

## Daily limit

Texts sent from sender IDs count against a daily limit that resets at midnight UTC. When it is reached, sends from a sender ID answer `429` until the reset. Texts from your phone numbers are not affected.

`GET /v1/sms/sender-ids` returns your names. Write to support@pozy.ai to raise your sender ID limit, with what the texts are for, who receives them and roughly how many you send a day. `POST /v1/sms/sender-ids/limit-request` is not available yet and answers `403` with `code: "feature_not_available"`.

## Limits

| Limit | Value |
| --- | --- |
| Name length | 3 to 11 characters |
| Active names per workspace | 1,000 |
| Replies | Not possible |
| MMS | Not available |
| Destinations | Not the US, Canada or Puerto Rico |

## Errors

| Status | Code | Cause | Fix |
| --- | --- | --- | --- |
| `403` | `alpha_destination_not_supported` | `to` is in the US, Canada or Puerto Rico | Send from a [phone number](https://pozy.ai/docs/telephony/buy-a-number) |
| `403` | `mms_not_supported` | `mediaUrls` on a sender ID send | Remove the media |
| `429` | `alpha_daily_limit_reached` | Today's sender ID limit is reached | Wait for midnight UTC, or write to support@pozy.ai to raise your sender ID limit |
| `403` | `sender_id_limit_reached` | The workspace has 1,000 active names | Contact support |
| `422` | | The name imitates another brand or institution | Use your own brand name |
| `402` | | No payment method on file | Add a payment method |

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/sms/sender-ids`](https://pozy.ai/docs/api/listSmsSenderIds) | List alphanumeric sender IDs |
| [`POST /v1/sms/sender-ids`](https://pozy.ai/docs/api/createSmsSenderId) | Create an alphanumeric sender ID |
| [`DELETE /v1/sms/sender-ids/{id}`](https://pozy.ai/docs/api/deleteSmsSenderId) | Delete an alphanumeric sender ID |
| [`POST /v1/sms/messages`](https://pozy.ai/docs/api/sendSms) | Send an SMS/MMS |