Agent SMS lines

A Seller Account enrolled in agent phone lines can send a text message from its assigned number with POST /api/v2/communications/messages. Existing API calls do not change. Ask Apostra to enable agent phone lines and assign a text number before using this command. There is no self-service number picker yet. The API credential needs interchange:write and must belong to the same Seller Account as the line. The destination must be an E.164 telephone number, such as +12025550101. Apostra rejects a recipient who has opted out of messages from that line.

curl -X POST "https://api.apostra.com/api/v2/communications/messages" \
  -H "Authorization: Bearer $INTERCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "df3b1f38-77ad-4e2e-ad67-594433cf1be7",
    "endpointId": "123",
    "to": "+12025550101",
    "text": "Your message"
  }'

Field	Required	Description
`requestId`	Yes	UUID for this intended message. Reuse it only to retry the same message.
`endpointId`	Yes	Apostra text-line ID, represented as a numeric string.
`to`	Yes	Recipient telephone number in E.164 format.
`text`	Yes	Message text, from 1 to 1,600 characters.

An accepted request returns HTTP 202 after the message is saved to the outbound queue:

{
  "data": {
    "message": {
      "outboxId": "91",
      "status": "pending",
      "duplicate": false
    }
  },
  "error": null
}

pending means Apostra has queued the message. It does not mean the carrier accepted it or the recipient received it. A retry with the same requestId, line, destination, and text returns the same outboxId with duplicate: true. Changing any of those fields while reusing the UUID returns 409.

Errors and retries

Status	Meaning	Action
`400`	A field is invalid, the line is inactive, or the recipient opted out.	Correct the request or use an active line. Do not text an opted-out recipient.
`401` or `403`	The credential is missing, invalid, or lacks `interchange:write`.	Use an authorised credential for this account.
`404`	The Seller Account is not enrolled in agent phone lines.	Ask Apostra to verify enrollment and provisioning.
`409`	The request UUID was already used with different message details.	Keep the original details or use a new UUID for a different message.
`503`	The service cannot safely protect or enqueue the message.	Retry the same request ID after the service recovers.

Apostra stores message content and recipient identity in protected form before carrier submission. This command does not currently provide a public status lookup endpoint. Keep the outboxId from the response for support and reconciliation.

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Agent SMS lines

Agent SMS lines

Errors and retries

​Agent SMS lines

​Errors and retries

Agent SMS lines

Errors and retries