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. The sender is created with status not_started; call the verify endpoint to register and activate it. (The Txtly dashboard does this automatically when you create a sender.)

Parameters

Parameter	Type	Description
`name`required	`string`	Display name for the sender (e.g. "Acme Alerts")
`senderId`required	`string`	The sender ID value. Format depends on senderType: alphanumeric (1-11 chars), phone number (E.164), or short code (4-6 digits).
`senderType`	`string`	One of: alphanumeric_id (default), long_code, toll_free, short_code
`country`	`string`	ISO 3166-1 alpha-2 country code (default "AU")
`defaultMessageType`	`string`	Default 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",
  "country": "AU",
  "providerRef": null,
  "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.

Example Response

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

Get Sender

GET

/v1/sms/senders/{id}

Retrieve a single SMS sender identity by ID.

Path Parameters

Parameter	Type	Description
`id`required	`string (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

Parameter	Type	Description
`name`	`string`	Updated display name
`defaultMessageType`	`string`	"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

Register the sender's alphanumeric sender ID with the provider and activate it. Sender IDs activate immediately in supported countries, so the response status is active (or failed, with a rejectionReason). Re-verifiable from any non-active, non-suspended status.

Example Request

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

Example Response

Registration is performed synchronously — the response reflects the final outcome. Australian alphanumeric sender IDs activate immediately:

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "Acme Alerts",
  "senderId": "AcmeAlerts",
  "senderType": "alphanumeric_id",
  "status": "active",
  "defaultMessageType": "transactional",
  "country": "AU",
  "providerRef": "arn:aws:sms-voice:ap-southeast-2:123456789012:sender-id/AcmeAlerts/AU",
  "rejectionReason": null,
  "createdAt": "2026-04-12T10:00:00Z",
  "updatedAt": "2026-04-12T10:00:05Z"
}

If registration fails, the sender moves to failed with the reason in rejectionReason; you can retry by calling verify again. Verifying an already-active sender is a no-op that returns the sender. Suspended senders cannot be re-verified (400).

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 register and activate it.
pendingTransient. Sender IDs activate synchronously, so a sender normally moves straight to active; re-verify a pending sender to activate it.
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.