Senders

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 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.

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.

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 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.

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" }'

fromstringrequired

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.

messagePrefixstring

Text placed before every message sent from this sender.

unregisteredBypassRouteOptOutbooleandefault: 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.

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 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.

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"
  }'

namestringrequired

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.

brandstringrequired

The brand the agent speaks for. Up to 100 characters.

useCasestringrequired

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 before choosing.

agentCategorystringdefault: 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.

smsSenderstring

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.

defaultRegisterstring

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.

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, and what to expect meanwhile in Coverage & 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 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.

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 or choose the default in the dashboard.

To follow the registrations from the API:

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 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.