Sender IDs

By the end of this page, your messages arrive from your brand name (ZERNIO) instead of a phone number, the way banks and airlines text. There is no number to buy, no monthly fee and no US carrier registration.

What a sender ID can do

Before you start

You need usage-based billing with a payment method on file.

Create the name once with POST /v1/sms/sender-ids, then pass it as from when sending.

Step 1: Create a sender ID

Call POST /v1/sms/sender-ids with senderId. The name is usable at once.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: sender } = await zernio.sms.createSmsSenderId({
  body: { senderId: 'ZERNIO' }
});
console.log(sender.id, sender.isActive);

Response (200):

{
  "id": "67b8c9d0e1f2a3b4c5d6e7f8",
  "senderId": "ZERNIO",
  "isActive": true
}

Names are vetted at creation. Names that impersonate well-known brands or institutions (payment providers, delivery carriers, banks, government) are rejected with 422.

Names are not exclusive. The same sender ID can be registered by any number of teams. Delivery receipts and billing always track the team that sent each message.

A team can hold up to 1,000 active sender IDs. Beyond that you get a 403 with code: "sender_id_limit_reached"; contact support to raise it.

GET /v1/sms/sender-ids lists your names with the daily budget.

DELETE /v1/sms/sender-ids/{id} deactivates one. Creating the same name again restores it.

Step 2: Send from it

Pass the sender ID as from on the regular send endpoint. Everything else is unchanged.

const { data: sent } = await zernio.sms.sendSms({
  body: {
    from: 'ZERNIO',
    to: '+34612345678',
    text: 'Your verification code is 482913',
  }
});
console.log(sent.id, sent.status);

Response (200):

{
  "id": "67c9d0e1f2a3b4c5d6e7f8ab",
  "conversationId": "66c3d2ae7b4f6c8d0e1f2a3c",
  "status": "sent"
}

Delivery works like any SMS. Track it with the message.delivered and message.failed webhooks.

Each segment bills at the destination country's SMS rate.

Country behavior

Most of Europe and many other markets display alphanumeric senders as they are.

Some countries substitute a numeric sender to guarantee delivery.

A few (India and the UAE, for example) require the name to be pre-registered with local carriers before it displays. Contact support if you need a registration-required destination.

Daily limits

Each team has a daily sender-ID message budget, shared across all its names and reset at midnight UTC:

Request a higher level with POST /v1/sms/sender-ids/limit-request, passing requestedCap and reason (your use case and audience).

Requests are reviewed within a business day, one at a time.

GET /v1/sms/sender-ids reports the current budget (cap, usedToday, level and any pendingRequest).

If it fails

A 403 with code: "alpha_destination_not_supported" means to is in the US, Canada or Puerto Rico. The message is refused before it reaches the carrier:

{
  "error": "Alphanumeric sender IDs cannot deliver to +13105551234",
  "type": "permission_error",
  "code": "alpha_destination_not_supported"
}

Send to those destinations from a phone number.

Other errors:

• 403 with code: "mms_not_supported": mediaUrls was attached.
• 429 with code: "alpha_daily_limit_reached": today's budget is spent.
• 402: no payment method is on file.

Every error uses the envelope in error handling.

Related

• Sending: the send endpoint, opt-outs and lookups.
• Phone numbers: what to send from for 2-way conversations or US recipients.
• Create an alphanumeric sender ID and Request a higher sender ID daily limit: every field.
• SMS rates: per-segment prices by destination.