Require staff approval before submitting an IllyVoIP SMS batch

If staff must review messages before they are sent, place that approval in your own application before calling the IllyVoIP SMS API. The approved item should identify the exact recipients, sender and message. This guide does not describe a built-in Portal staff-approval queue, and your approval does not replace IllyVoIP’s account or communication review.

Use a backend with authorized account API access and keep X-Api-Key out of browser code. The API base is https://api.illyvoip.com. Check HTTP status and the JSON result. Examples below are request templates, not records of completed transactions.

SMS submissions can incur charges. Use the standard IllyVoIP sender or a custom sender approved and available for this account. Recipient eligibility, content review, encoding and current service limits still apply. Store an Idempotency-Key with the exact request before submission; preserve both after an uncertain response.

1. Build a reviewable batch

Import the intended recipients into a private batch record. Keep the source row IDs, normalized international numbers, purpose and eligibility information needed for review. Remove or flag duplicates deliberately and separate invalid or suppressed recipients before approval. Do not show a recipient count as if every imported row is already eligible to receive an SMS.

1. Choose the permitted sender and exact message text.
2. Show the complete text, including links and punctuation, to the reviewer.
3. Show the intended unique-recipient count and the excluded rows with reasons.
4. Review encoding, segment implications and current pricing before dispatch.
5. Give the batch an immutable version and record who may approve it.

A calculated cost preview is not a reservation. If the workflow needs a spending guard, implement a reviewed dispatch limit in your application and check actual returned charges. Do not assume a recipient count alone measures SMS cost.

2. Bind approval to the frozen version

Persist the approved version, approver, timestamp and exact submission manifest. Include account/environment, sender, ordered recipients, message text and any personalization that will change the actual payload. Authorize approval and sending on the backend. A hidden browser checkbox is not an approval record.

Any edit to the approved content or recipients creates a new version requiring review. Do not silently regenerate personalized text after approval. Immediately before dispatch, recheck the current permission and recipient-suppression state. If it changed, stop the affected unsent work and review the revised manifest rather than altering an already dispatched request.

3. Divide approved work into stable submissions

Choose a bounded submission size within the current SMS API limits. For messages with different personalized text, create separate submissions because one request’s message applies to its recipient list. Use small requests initially so acceptance and recipient mapping are easy to inspect.

POST to /api/v1/sms/messages with a template such as:

{
  "from": "IllyVoIP",
  "to": ["+12025550123"],
  "message": "Your requested update is ready. Sign in to your customer account to view it."
}

This documentation number is not a real recipient to contact. Save each exact payload and its own idempotency key before a worker sends it. Claim each submission atomically so two workers cannot both create new send attempts for the same approved intent. Reconcile a worker crash using that saved submission identity.

4. Record partial acceptance accurately

1. Inspect HTTP and API success before updating the ledger.
2. Save queued_message_ids, queued_count, invalid_numbers, duplicates_removed and returned cost information.
3. Confirm each queued ID’s recipient through the status endpoint’s to field when mapping is uncertain.
4. Track queued, delivered, failed, invalid, suppressed and unsent rows separately.
5. Process verified delivery webhooks or bounded status reads without submitting the batch again.

A successful batch can contain rejected recipients. Correcting a rejected number is a newly reviewed intent; it does not justify resending every accepted recipient. Delivery is also separate from approval: an approver can authorize a message that later fails delivery.

5. Handle cancellation and uncertain sends

Cancel only work that your ledger can establish has not been dispatched. Stop new worker claims before marking remaining items canceled. A queued SMS is not recalled by canceling your application’s batch. If a response was lost, keep the original body and key and reconcile that request; changing the key can create another paid submission.

Test approval followed by an edit, two simultaneous workers, partial acceptance, a crash after queue admission and cancellation during dispatch. The review screen should state how many messages are already accepted and how many remain unsent. Keep the audit record private and retain only the recipient data needed by your business process.

Related guides

• Send an SMS with the IllyVoIP API and track delivery
• Send a CSV recipient list with Python and IllyVoIP
• Explain your activity in Communication reviews

Reference

Current instructions and technical reference: IllyVoIP API documentation.

Reviewed 13 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.