Frequently Asked Questions
Common questions about the Agile Telecom SMS API. For additional support write to help@agiletelecom.com or open the wholesale portal.
Authentication
What authentication method should I use?
API Key authentication is recommended for all new integrations. Include your API key in the X-Api-Key header:
X-Api-Key: your_api_key_here
Basic Auth is also supported for legacy clients.
Where can I find my API key?
Sign in to the wholesale portal and open Settings → API Keys.
Can I have multiple API keys?
Yes. Create independent keys per environment or service. Each key can be revoked without affecting the others.
- Settings → API Keys
- Generate New Key
- Give it a descriptive name and copy the value immediately — you won't be able to view it again.
Is my API key sensitive?
Yes. Treat it like a password — never commit it to source control or expose it in client-side code. Revoke and rotate immediately if it leaks.
Sending SMS
What's the difference between "accepted" and "delivered"?
- Accepted — The platform has accepted the message for sending. Usually within seconds. Does not mean it reached the handset.
- Delivered — Confirmed by the operator and/or the handset via a delivery report. Asynchronous, may take longer.
Always use delivery reports to confirm actual delivery.
What's the maximum message length?
It depends on the encoding.
| Encoding | 1 part | Per-part in concatenation |
|---|---|---|
| GSM-7 | 160 chars | 153 chars |
| UCS-2 (Unicode) | 70 chars | 67 chars |
A single non-GSM character (e.g. an emoji) flips the whole message to UCS-2. See Sending SMS for the full table.
Can I schedule a message?
Yes. Use the scheduling field on a message with an ISO-like timestamp and timezone offset (e.g. 2026-05-20 08:30:00.000+0200). See Sending SMS.
Can I send to many numbers in a single call?
Yes. Add multiple numbers to destinations, or multiple message objects to messages[]. See Sending SMS.
What sender IDs can I use?
- Numeric — Digits-only short codes or long numbers (replyable if you own the number).
- Alphanumeric — Up to 11 characters (not replyable; may require pre-registration in some countries).
Delivery Reports
How do I receive delivery reports?
Set enableDelivery: true on your send request and configure a webhook URL in Settings → Webhooks on the wholesale portal. See Delivery Reports.
What should my webhook return?
200 OK within 10 seconds. Anything else is treated as failure and retried with exponential back-off for up to 24 hours.
What does each DLR status mean?
| Status | Meaning |
|---|---|
DELIVERED | Handset confirmed reception |
BUFFERED | Stored on the operator, not yet delivered |
EXPIRED | Validity period elapsed before delivery |
REJECTED | Operator rejected the message |
UNDELIVERABLE | Wrong number, blacklisted, opted-out |
UNKNOWN | No final state received within the validity window |
FAILED | Internal failure before submission |
Full reference in Delivery Reports.
Inbound SMS
How do I receive replies?
Rent a number from the wholesale portal and bind it to a webhook URL or email. See Inbound SMS.
My webhook keeps being retried — why?
Your endpoint must respond with exactly +OK (body only) within 30 seconds. Anything else triggers retries — up to 3 attempts, 15 minutes apart, then the message is discarded.
Error Codes
What do the HTTP status codes mean?
| Code | Meaning | Action |
|---|---|---|
200 | Accepted (check per-message statusCode) | Continue, expect DLRs |
400 | Bad request | Fix the payload |
401 | Invalid credentials | Check API key / Basic Auth |
403 | IP not whitelisted | Add IP to whitelist |
408 | Timeout | Retry with back-off |
413 | Payload too large | Split the batch |
429 | Rate limit exceeded | Exponential back-off |
5xx | Server error | Retry with back-off, alert if it persists |
Full mapping in Error Handling.
How should I handle rate limiting?
Implement exponential back-off with jitter starting from 1 second. Cap at a few minutes. Honour the Retry-After header when present. See Best Practices.
Network Services
Can I check credit before sending?
Yes. Use the Credit Check API — useful before large campaigns.
Can I validate numbers before sending?
Yes. Use MNP lookup to detect invalid or ported numbers. Cuts wasted sends and improves deliverability stats.
Compliance
How do I handle opt-out?
Implement STOP / UNSUBSCRIBE handling on the inbound webhook, persist the opt-out per phone number, and consult it before every marketing send. See Best Practices.
Is HTTP still supported?
No — from January 15th, 2026 plain HTTP connections are rejected. All API calls must be over HTTPS (TLS). GET requests and form-encoded POST requests are no longer accepted on the SMS endpoint — only POST with JSON over HTTPS.
Support
- Email: help@agiletelecom.com
- Wholesale portal: wholesale.agiletelecom.com
- SMS API console: wholesale.agiletelecom.com/services/sms