> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent SMS lines

> Send a text message from a provisioned agent line and retry safely

# 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.

```bash theme={null}
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:

```json theme={null}
{
  "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.