# Senders

List the SMS and RCS senders of a project and create new ones from the API, then register each of them in the dashboard for the countries you send to.

**Language:** en
**Audience:** developer
**TLDR:** GET /v1/project/{project}/channel/sms/sender and /channel/rcs/sender list the senders with their registers and acceptedCountries; any token on the project can read them. POST to the same paths creates one with PROJECT_SENDER_WRITE: SMS takes from (up to 11 characters, or a valid international number), RCS takes name, brand, useCase and an optional smsSender fallback of the same organization. A new sender has no registrations: register it per country in the dashboard. 451: the SMS name may not be used.
**Search keywords:** sender, senders, create sender, add sender, new sender, sms sender, rcs sender, rcs agent, create agent, sender id, alias, from, list senders, PROJECT_SENDER_WRITE, sender scope, 451, unavailable for legal reasons, sender name not allowed, protected brand, sender already used, sender limit, too many senders, sms fallback, fallback sender, smsSender, useCase, agentCategory, messagePrefix, unregisteredBypassRouteOptOut, substitute number, register sender, sender registration, cnmc, Spain alias
**Related pages:** /platform-api/product-api/project-setup/channel-readiness, /platform/en/channels/sms/senders-registration, /platform/en/channels/rcs/senders-verification, /platform/en/channels/rcs/sms-fallback, /platform/en/channels/countries/spain
**Docs index (every page):** https://staging-instasent-docs-nextjs.oscar-284.workers.dev/llms.txt
**This zone's index:** https://staging-instasent-docs-nextjs.oscar-284.workers.dev/platform-api/product-api/llms-full.txt
**This page:** https://staging-instasent-docs-nextjs.oscar-284.workers.dev/platform-api/product-api/project-setup/senders/ (HTML) · https://staging-instasent-docs-nextjs.oscar-284.workers.dev/platform-api/product-api/project-setup/senders.md (Markdown)

A sender is the identity your messages are sent with: the name or number a contact sees on an SMS, or the brand agent that writes to them over RCS. Every campaign, flow and direct message in a project goes out from one, so a project with no sender cannot send on that channel at all, which is exactly what the `add-sender` and `add-agent` steps of [channel readiness](/platform-api/product-api/project-setup/channel-readiness) report.

This page covers what the Product API does with senders: it lists the ones a project has, and it creates new SMS and RCS senders. What comes after creation, registering the sender in each country that asks for it, is done in the dashboard, and the last section says what that involves and how to follow it from the API.

## Listing senders

[`GET /v1/project/{project}/channel/sms/sender` - The project's SMS senders, each with its registers and the countries it can deliver to.](/platform-api/product-api/reference)

[`GET /v1/project/{project}/channel/rcs/sender` - The project's RCS senders (agents), each with its per-country registers and the countries it can deliver to.](/platform-api/product-api/reference)

Any Product API token with access to the project can read both lists; no extra scope is needed. Each sender carries its `registers`, one per country, and `acceptedCountries`, the countries it can deliver to right now. The SMS list also returns the project's default SMS sender in `metadata.defaultSender`.

Both lists accept [query string filtering](/platform-api/further-reading/query-filter) for filtering, sorting and pagination.

## Creating an SMS sender

[`POST /v1/project/{project}/channel/sms/sender` - Create an SMS sender in the project. Requires `PROJECT_SENDER_WRITE`.](/platform-api/product-api/reference)

```bash
curl -X POST "https://api.instasent.com/v1/project/$INSTASENT_PROJECT/channel/sms/sender" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "from": "MyShop" }'
```

- `from` — `string`, required
  The sender name recipients see. Letters, digits, spaces and `-`, `_`, `.`. An alphanumeric name takes up to 11 characters. A name made only of digits must be a valid international phone number, written without the leading `+`. It **cannot be changed once the sender exists**: to use a different name, create another sender.
- `messagePrefix` — `string`
  Text placed before every message sent from this sender.
- `unregisteredBypassRouteOptOut` — `boolean`, default: `false`
  What happens in a country whose regulator blocks the sender because it has no accepted registration there. With `false`, the message is still sent, from a substitute number, so the recipient sees a sender other than yours. With `true`, the message is blocked instead. It changes nothing in countries without a regulator in force. See [After creating a sender](#after-creating-a-sender).

The response is `201` with the new sender in `entity`, in the same shape the list returns. Keep its `id`: it is how a [campaign draft](/platform-api/product-api/campaigns/creating-a-draft) or an RCS sender's fallback refers to it.

## Creating an RCS sender

[`POST /v1/project/{project}/channel/rcs/sender` - Create an RCS sender (agent) in the project. Requires `PROJECT_SENDER_WRITE`.](/platform-api/product-api/reference)

```bash
curl -X POST "https://api.instasent.com/v1/project/$INSTASENT_PROJECT/channel/rcs/sender" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyShop",
    "brand": "MyShop",
    "useCase": "multi_use",
    "smsSender": "5f3a9b2c4d1e0f00112233ab"
  }'
```

- `name` — `string`, required
  The agent's name: what the dashboard shows as **Display name**, the name a contact sees for your brand in their messaging app. Keep it within 40 characters, the limit the dashboard applies.
- `brand` — `string`, required
  The brand the agent speaks for. Up to 100 characters.
- `useCase` — `string`, required
  The kind of messages the agent sends: `otp`, `transactional`, `promotional` or `multi_use`. These are the dashboard's **Verification codes (OTP)**, **Transactional**, **Promotional** and **Mixed**. It **cannot be changed later**, and it limits what the agent may send: an `otp` or `transactional` agent cannot send promotional messages, so use `multi_use` when you combine both. Some countries restrict the agent type; check yours in [Countries](/platform/en/channels/countries) before choosing.
- `agentCategory` — `string`, default: `non_conversational`
  How the agent's messages are billed, the dashboard's **Billing category**. Leave it out: `non_conversational`, billed per message, is the category available today. It cannot be changed later.
- `smsSender` — `string`
  The `id` of the SMS sender to fall back to when a contact cannot receive RCS. It must belong to the same organization; one from another organization is refused with `422` on `smsSender`. Every campaign built on this RCS sender starts with it as its SMS fallback, and it can still be changed per campaign. How fallback works is in [SMS fallback](/platform/en/channels/rcs/sms-fallback).
- `defaultRegister` — `string`
  One of the sender's own registers. A new sender has none, so leave it out.

The response is `201` with the new sender in `entity`. It does not echo `smsSender`; the pairing is visible on the RCS sender's sheet in the dashboard.

## Errors

| Status | When                                                                                                                                                                                                            | What to do                                                                                            |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `403`  | The token lacks `PROJECT_SENDER_WRITE`, or the project already has as many senders as its subscription allows. RCS senders are counted on their own against the same allowance as SMS senders.                  | Add the scope to the token, or archive a sender you no longer use or move to a plan that allows more. |
| `422`  | A field is invalid: `from` is already used in the project or has the wrong format, a required field is missing, or `smsSender` belongs to another organization. `errors.fields` names the field.                | Fix the field and resubmit.                                                                           |
| `451`  | SMS only: the name in `from` may not be used, either because it is protected (for example, a name reserved to protect a brand) or because it is made of digits that are not a valid international phone number. | Choose another name. If the protected name is your own brand, contact support.                        |
| `429`  | Each endpoint accepts 10 requests an hour per organization, on every plan.                                                                                                                                      | Wait for `X-RateLimit-Reset`. See [Rate limits](/platform-api/product-api/rate-limits).               |

## After creating a sender

**A new sender has no registrations.** Registering it in a country, with your company's legal profile and the documents that country asks for, is done in the dashboard, and that step decides where the sender can deliver.

- **SMS.** In countries that require no registration, the sender can send as soon as it exists; `acceptedCountries` lists them. Where a country does require one, request it from the sender's sheet under **Settings → Project → Channels → SMS**, with **Request country**. While it is being filed we look for the best route to get messages through, and the recipient may see a different sender. The full flow is in [SMS senders & registration](/platform/en/channels/sms/senders-registration), and what to expect meanwhile in [Coverage & delivery](/platform/en/channels/sms/coverage-and-delivery).
- **Spain.** An alphanumeric sender has to be registered with the CNMC. Until the regulator has accepted it, the message goes out from a substitute number, or is blocked if you created the sender with `unregisteredBypassRouteOptOut: true`. The two ways to register and the alias rules are on the [Spain](/platform/en/channels/countries/spain) page.
- **RCS.** An RCS sender cannot send to any country until that country's register is approved. Add each country from the sender's sheet under **Settings → Project → Channels → RCS**, complete the agent profile, organization and compliance data, and submit it for review. The whole process is in [RCS senders & verification](/platform/en/channels/rcs/senders-verification).

Creating a sender does **not** make it the project's default. A campaign draft that names no sender takes the project's default for the channel, so either pass the new sender's `id` as `sender` in the [draft](/platform-api/product-api/campaigns/creating-a-draft) or choose the default in the dashboard.

To follow the registrations from the API:

- [Channel readiness](/platform-api/product-api/project-setup/channel-readiness) returns the countries each sender reaches today and the ones it ought to be registered for.
- The registration progress and per-country checklist endpoints, described on the same page, say what a country's paperwork still asks of a sender.
- [Attention](/platform-api/product-api/project-setup/attention) reports a registration that was rejected or is waiting on a review.

## Scope

Creating senders needs `PROJECT_SENDER_WRITE`, shown in the dashboard's token settings as **Create SMS and RCS senders**. It is a scope of its own and it only creates: it does not edit, archive or register a sender, which all stay in the dashboard. Reading senders needs no scope beyond access to the project. See [Tokens and scopes](/platform-api/product-api/guide#tokens-and-scopes).

---

This is one page of the Instasent documentation. For the complete machine-readable index of every guide and API reference, fetch https://staging-instasent-docs-nextjs.oscar-284.workers.dev/llms.txt — start there for full context.