Developers

API reference

Base URL https://api.textvolley.com/v1. JSON over HTTPS, bearer-token auth, idempotency keys and signed webhooks.

Authentication

Send your secret key in the Authorization: Bearer header. Keys are scoped per project and region (EU, APAC, MENA, LATAM).

Send a message

curl -X POST https://api.textvolley.com/v1/messages/sms \
  -H "Authorization: Bearer $TV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+33612345678","from":"Acme","text":"Votre code: 482913"}'

Response 202 Accepted:

{ "id": "msg_9f2c71", "status": "queued", "route": "whatsapp",
  "price": { "amount": 0.124, "currency": "EUR" } }

Mass SMS broadcasts

Send one campaign to up to 1,000,000 recipients per request. Use {{first_name}} merge fields, schedule in the recipient's time zone, throttle per second, and opt-outs (STOP) are suppressed automatically.

POST /v1/broadcasts
{ "name": "Spring sale", "sender": "TextVolley",
  "list_id": "lst_42", "text": "Hi {{first_name}}, 20% off today. STOP to opt out",
  "send_at": "2026-04-02T09:00:00", "local_time": true,
  "throttle_per_second": 500 }

→ 202 { "id": "bc_71a", "recipients": 248310, "segments": 248310,
        "estimate": { "amount": 9932.40, "currency": "EUR" } }

Endpoints

POST /v1/messages/sms	SMS & RCS
POST /v1/messages/whatsapp	WhatsApp Business
POST /v1/verify/voice	Voice OTP
POST /v1/messages/email	Transactional Email
POST /v1/post/letters	Postal Letters
POST /v1/fax	Online Fax
POST /v1/broadcasts	Mass SMS broadcast
POST /v1/lists	Upload contact list (CSV / JSON)
GET /v1/broadcasts/:id/report	Broadcast delivery report
GET /v1/messages/:id	Message status
GET /v1/pricing/:country	Live route pricing

Webhooks

Delivery events are POSTed to your callback_url, signed with HMAC-SHA256 in the TV-Signature header.

{ "type": "message.delivered", "id": "msg_9f2c71",
  "carrier": "Orange France", "latency_ms": 1984 }

Errors

400 invalid_number
401 invalid_key
402 insufficient_balance
422 sender_not_registered
429 rate_limited