Skip to content
SMSendDevelopers
Toggle colour theme

API reference

Sender IDs

The names and numbers your account may send from.

Check is_sendable, never status

A sender can be APPROVED by SMSend and still not be registered with any operator, in which case it cannot carry traffic. Sending with it succeeds at submission and then fails every individual message after each has burned its full retry budget. The is_sendable flag already combines both conditions — do not reconstruct it from status.

List sender IDs

GET/public/v1/sender-ids

Returns every sender registered to the account, ordered by value, with whether each one can currently be used.

Required scope SENDER_IDS_READ

Request

curl https://api.smsend.net/public/v1/sender-ids \
  -H "Authorization: Bearer $SMSEND_API_KEY"
<?php

$senderIds = Http::withToken(getenv('SMSEND_API_KEY'))
    ->get('https://api.smsend.net/public/v1/sender-ids')
    ->json('data.sender_ids');

// Check is_sendable, not status: an approved sender that is not yet
// registered with an operator cannot carry traffic.
$usable = array_filter($senderIds, fn (array $sender) => $sender['is_sendable']);
const response = await fetch('https://api.smsend.net/public/v1/sender-ids', {
  headers: { Authorization: `Bearer ${process.env.SMSEND_API_KEY}` },
})

const { data } = await response.json()

// Check is_sendable, not status: an approved sender that is not yet
// registered with an operator cannot carry traffic.
const usable = data.sender_ids.filter((sender) => sender.is_sendable)
import os
import requests

sender_ids = requests.get(
    "https://api.smsend.net/public/v1/sender-ids",
    headers={"Authorization": f"Bearer {os.environ['SMSEND_API_KEY']}"},
).json()["data"]["sender_ids"]

# Check is_sendable, not status: an approved sender that is not yet
# registered with an operator cannot carry traffic.
usable = [sender for sender in sender_ids if sender["is_sendable"]]

Responses

200The account's sender IDs.
{
  "data": {
    "sender_ids": [
      {
        "sender_id": "01K3F6ABCDEFGHJKMNPQRSTVWX",
        "value": "PRESTIGE",
        "type": "ALPHANUMERIC",
        "status": "APPROVED",
        "is_sendable": true,
        "reason": null
      },
      {
        "sender_id": "01K3F6ABCDEFGHJKMNPQRSTVWY",
        "value": "MABANQUE",
        "type": "ALPHANUMERIC",
        "status": "APPROVED",
        "is_sendable": false,
        "reason": null
      },
      {
        "sender_id": "01K3F6ABCDEFGHJKMNPQRSTVWZ",
        "value": "+22625000000",
        "type": "NUMERIC",
        "status": "REJECTED",
        "is_sendable": false,
        "reason": "Le justificatif de propriété de la marque est manquant."
      }
    ]
  }
}

Possible errors

CodeStatusMeaning
UNAUTHORIZED401No key, a malformed key, a wrong secret, a revoked or expired key, or a suspended account. All indistinguishable by design.
INSUFFICIENT_SCOPE403The key is valid but does not carry the scope this endpoint requires. The scope is named in the detail.
RATE_LIMITED429The key's request limit was exceeded. Wait for the interval in Retry-After.
INTERNAL_ERROR500An unexpected failure on SMSend's side. Quote the request id to support.

Statuses

ValueMeaning
PENDING
Submitted and awaiting review.
APPROVED
Approved by SMSend. Still needs operator registration before it can send.
REJECTED
Refused during review. The reason field explains why.
REVOKED
Withdrawn after having been approved.

Types

The type is derived from the value rather than declared when the sender is registered.

ValueMeaning
ALPHANUMERIC
Contains non-numeric characters — a brand name such as PRESTIGE. Recipients cannot reply to it.
NUMERIC
A long number, eight digits or more. Can receive replies.
SHORT_CODE
A short number, fewer than eight digits.