SMS senders

The sender is the name or number the recipient sees as the origin of your SMS. In the A2P Messaging API it is not a free-text field: every message goes out from a sender registered in your account, the same senders you see in the dashboard under SMS > Senders. Registering them is what lets each message arrive under your brand, and in the countries that ask for it, what lets us file that brand with the regulator or the operators.

The per-country rules — which countries accept any alphanumeric sender, which replace it with a number, which require a registration first — are the same for the dashboard and the API, and are documented once:

Senders are required

A request names its sender in one of two ways:

• sender — the id of one of your senders. This is the recommended form: it is stable if the sender is renamed, and unambiguous. An id that doesn't exist returns 422.
• from — the sender's name: 3 to 11 characters when alphanumeric, 3 to 14 digits when numeric. It has to match one of your registered senders by name.

When both are sent, sender wins, and the from in the response is the sender's canonical name.

A from that matches none of your senders is refused with 422, and nothing is sent or charged. The error is reported on the from field:

{ "errors": { "fields": { "from": ["The sender is not registered in this project, register it before sending"] } } }

In a bulk request the same check runs per item: a refused item is reported in errors and the rest are sent.

Register the sender in each country that requires it

Creating the sender in your account is the first step. Countries with a regulator in force, such as Spain, also need an accepted registration of the sender for that country, which you request and follow in the sender's sheet with your company's legal profile. Which countries ask for it, how the sheet shows each one, and what happens while a registration is pending are in SMS coverage.

Send the alias exactly as you filed it

Where a sender is filed with a regulator, the check against that registry is literal — character by character, capitals included. Nothing is normalised on the way.

If you filed PEDRO and your request carries Pedro, that check reads your alias as not filed, with all the consequences of not being filed — even though the procedure went through and was approved.

It is worth a line in your integration, because it is the hardest failure to diagnose from the outside: the register shows as approved, the regulator has your alias, and the messages still don't arrive as they should. Sending by sender id avoids it; if you build from from a database field or a template, make sure it reproduces the filed spelling.

Choosing blocking over substitution

Some senders would rather not go out at all than go out with the recipient seeing a different sender — a brand where the name is the point, or traffic where an unexpected sender would raise a support case of its own.

The sender carries a field for that: unregisteredBypassRouteOptOut. With it on, in a country whose regulator is in force, that sender never takes an alternative route — the block applies as it stands, and the message is reported as blocked by regulation.

Two limits worth knowing before you set it:

• It changes nothing where there is no regulator, and nothing before a regulator's rules take effect. It isn't a global "never substitute my sender" switch.
• It doesn't change what is billed — see What is billed.

It lives on the sender, not on the account, on purpose: on an account with the wildcard route, the Wildcard Sender carries all of that account's unregistered traffic, so the choice belongs with the sender that carries it.

What is billed

A message refused with 422 — for its sender or its destination country — is not sent and not charged.

Once a message has been accepted, a message blocked from a registered sender of your own is not billed, while a blocked transit message is. Delivery reports tell you the outcome per message — see DLRs.