SMS Senders

Manage SMS sender identities (origination numbers and alphanumeric IDs). A sender must be verified and active before it can be used to send messages.

Add Sender

POST
/v1/sms/senders

Register a new SMS sender identity. After creation, call the verify endpoint to begin the verification process.

Parameters

ParameterTypeDescription
namerequiredstringDisplay name for the sender (e.g. "Acme Alerts")
senderIdrequiredstringThe sender ID value. Format depends on senderType: alphanumeric (1-11 chars), phone number (E.164), or short code (4-6 digits).
senderTyperequiredstringOne of: alphanumeric_id, long_code, toll_free, short_code
countryrequiredstringISO 3166-1 alpha-2 country code (e.g. "AU", "US")
defaultMessageTypestringDefault message type: "transactional" (default) or "promotional"

Example Request

curl -X POST https://api.txtly.com.au/v1/sms/senders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Alerts",
    "senderId": "AcmeAlerts",
    "senderType": "alphanumeric_id",
    "country": "AU",
    "defaultMessageType": "transactional"
  }'

Example Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Acme Alerts",
  "senderId": "AcmeAlerts",
  "senderType": "alphanumeric_id",
  "status": "not_started",
  "defaultMessageType": "transactional",
  "transactionalOnly": false,
  "country": "AU",
  "rejectionReason": null,
  "createdAt": "2026-04-12T10:00:00Z",
  "updatedAt": "2026-04-12T10:00:00Z"
}

List Senders

GET
/v1/sms/senders

List all SMS sender identities for the current team.

Get Sender

GET
/v1/sms/senders/{id}

Retrieve a single SMS sender identity by ID.

Path Parameters

ParameterTypeDescription
idrequiredstring (UUID)Sender identity ID

Update Sender

PATCH
/v1/sms/senders/{id}

Update mutable fields of a sender identity. The sender ID, type, and country cannot be changed after creation.

Parameters

ParameterTypeDescription
namestringUpdated display name
defaultMessageTypestring"transactional" or "promotional"

Delete Sender

DELETE
/v1/sms/senders/{id}

Delete an SMS sender identity. Cannot be deleted if it has been used to send messages.

Verify Sender

POST
/v1/sms/senders/{id}/verify

Start or restart the verification process for a sender identity. The sender must be in not_started, failed, or rejected status.

Example Request

curl -X POST https://api.txtly.com.au/v1/sms/senders/d290f1ee-.../verify \
  -H "Authorization: Bearer YOUR_API_KEY"

Sender Types

Each sender type has specific format requirements for the sender ID:

  • alphanumeric_id1-11 characters, letters, digits, and spaces. Must contain at least one letter. Displayed as the sender name on the recipient's device (not replyable).
  • long_codeStandard phone number in E.164 format (e.g. +61412345678). Supports two-way messaging.
  • toll_freeToll-free phone number in E.164 format. Higher throughput than long codes.
  • short_code4-6 digit short code. Highest throughput, typically used for high-volume messaging.

Sender Status Lifecycle

Senders go through a verification lifecycle before they can be used:

  • not_startedInitial state after creation. Call the verify endpoint to begin.
  • pendingVerification in progress with the carrier/provider.
  • activeVerified and ready to send messages.
  • failedVerification failed. Can be retried via the verify endpoint.
  • rejectedRejected by the carrier. Check rejectionReason for details. Can be retried.
  • suspendedSuspended by the carrier or platform. Contact support to resolve.