Skip to main content

​
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, and any destination outside the line’s sending limits.
An accepted request returns HTTP 202 after the message is saved to the outbound queue:
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. This command sends SMS only. To send RCS from the same line, use POST /api/v2/communications/rcs/messages.

​
Sending limits

Every line has limits that protect you from runaway or costly sending. Apostra checks them again immediately before each text goes to the carrier, so they apply to every message the line sends.
  • Destinations. A line texts only ordinary North American (+1) telephone numbers. It does not text premium-rate numbers (such as the 900 area code), short codes, or numbers in other countries. The request is refused with 400 and nothing is queued.
  • Rate. A line sends at most 10 texts a minute. Extra texts stay queued and go out as soon as the line is under the limit; nothing is lost.
  • Daily spend. A line has a daily spend limit, which by default allows about 500 single-segment texts per UTC day. A long or non-Latin text uses more than one segment and counts as several. A text that would exceed the limit is not sent and is not retried later, so the recipient never gets a stale message the next day. The limit resets at 00:00 UTC.
A text that is refused before it reaches the carrier, for example because the recipient opted out after it was queued, counts toward neither limit. Contact Apostra if a line needs different limits.

​
Errors and retries

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.

​
When someone texts your line

A text message sent to your line reaches the storefront agent it is assigned to. The agent reads the message as a brief, composes against your catalogue, and texts back one short summary of what it drafted. Replies need the Seller Account to be enrolled in agent phone lines. While it is not enrolled, texts to the line stay queued and get no reply; once Apostra enrolls it, the agent answers the queued texts that are less than 15 minutes old. Ask Apostra to verify enrollment if a provisioned line does not reply. Each text is composed on its own. The agent is given that one message and nothing else — not the sender’s earlier texts, and not the draft it replied with last time. Texting “tell me more about the second one” starts a fresh brief that has never seen the first reply, so a follow-up should restate what it needs. Threading a text conversation is not built yet. The reply is a draft. Texting a line never places, approves, or changes a media buy, never changes account settings, and never returns account data. Whoever texted still signs in to act on anything the agent drafted. Apostra treats the message text, the sending number, and anything either one claims as untrusted input, so a text cannot grant itself authority your Seller Account has not already given a signed-in person. The reply is one carrier segment: at most 160 GSM-7 characters, restricted to characters that encode in a single septet, and it always ends with the opt-out keyword. A storefront or product name too long to fit is shortened rather than split across segments. One inbound message produces at most one reply. The reply is queued in the same outbound queue your own POST /communications/messages calls use, so it is subject to the same consent, line-status, and carrier checks. If the line is retired or the sender opts out while the agent is still working, the reply is never queued. Some texts get no reply at all, and are not retried:
  • a text more than 15 minutes old by the time the agent reaches it, for example one that queued during an outage, so nobody receives a late answer to a stale question;
  • a blank text, or one containing only spaces;
  • a text to a line whose storefront has been archived or replaced, or runs in adapter mode, which cannot take a direct brief;
  • a text from a number that opted out, even if the opt-out arrived after the text did, as long as it arrived before the agent started on it;
  • a text from a number that has already had 5 agent replies from the line in the last 15 minutes, or to a line that has sent 60 agent replies in the last hour. These limits stop two automatic responders from texting each other indefinitely; a person holding a short conversation stays well under them.
Whether agent phone lines are on is checked when the agent picks a text up, not when the text arrives. Turning them off therefore also stops replies to texts still waiting. While they are off, texts stay queued; turning them on answers a text that is still inside the 15-minute window.

​
How texts are kept

Apostra keeps the words of each text sent to your line, and the number that sent it, in encrypted form for 30 days after the text arrives. After 30 days, Apostra deletes both, except that a text the agent is still working on or waiting to answer keeps them until the agent has finished with it. Apostra keeps the record that a text arrived, when, and what happened to it, but never the words or the sending number in readable form. Apostra also groups the ordinary texts one number sends to one line into a single conversation record for your Seller Account. The record notes when each text arrived; it holds neither the words nor the sending number. Opt-out, opt-in and help keywords are not added to it, and neither is a text that arrives after its number has opted out. A text recorded before its number opted out stays in the record, even if the opt-out means the agent never answers it. The record is not shown anywhere yet, and the agent does not read it, so each text is still composed on its own.

​
Opt-out keywords

Apostra keeps its own consent record for each line and sending number, and applies these keywords before any agent sees the message:
  • STOP, UNSUBSCRIBE, CANCEL, END, or QUIT opts that number out. The agent is not given the message, any message still queued from that number is dropped, and POST /communications/messages to that number returns 400.
  • START or UNSTOP opts the number back in.
  • HELP or INFO is handled as a control message rather than a brief.
An opted-out number receives no agent reply and no API-sent message from that line until it opts back in. Carrier-level blocking is not a substitute for this record, and a delivery failure never re-opens consent.