Guide for business owners and developers
The SMS API, explained simply
What is an SMS API for?
The SMSGELY dashboard is ideal when a person sends messages: a shop owner announcing a sale, or a school office sending a notice to a guardians’ group. But many messages should be sent automatically, at the moment something happens in your own system. An API (application programming interface) is the doorway that lets your website, mobile app, ERP or billing software ask SMSGELY to send an SMS without anyone opening the dashboard.
Your software sends a short, secure request saying “send this text to this number from this sender”. SMSGELY checks it, stores it, reserves the cost from your wallet and delivers it through the same pipeline used by the dashboard, so API messages appear in the same delivery reports.
Typical use cases
- One-time passwords (OTP). Verify a phone number at sign-up or confirm a login or payment.
- Order updates. Tell customers when an order is received, shipped, delivered or cancelled. Store owners can follow the WooCommerce guide.
- Alerts and reminders. Appointment reminders for clinics, fee reminders for schools, low-stock or server alerts for your own team.
- Website forms. Get an SMS when someone submits an enquiry; see the WordPress guide.
- Bulk sends from your own system. Send personalised messages to up to 1,000 recipients per request with the bulk endpoint, optionally scheduled for later.
What you need before you start
- An SMSGELY account with a topped-up wallet. Register here; prices are on the pricing page.
- An API key. Create one in Dashboard → Developer → API keys. The full key is shown only once, so copy it into a safe place immediately. SMSGELY stores only a hashed version.
- A sender ID. Either an approved masking sender ID with your brand name, or the platform’s non-masking sender.
One request, one SMS
This is all it takes to send a message. Replace the placeholder key and sender with your own; developers can find the same example in JavaScript, PHP and Python in the send SMS docs.
curl https://<api-url-from-your-dashboard>/sms \
-H "Authorization: Bearer smsgely_abcd1234ef_YOUR_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-confirmed" \
-d '{
"to": "01712345678",
"message": "Your order #1042 is confirmed. Thanks, ShopBD",
"sender": "YOURBRAND",
"client_reference": "order-1042"
}'The response arrives immediately with status queued, the number of parts and the encoding (gsm7 for plain English, unicode for Bangla). The cost shown above is only an illustration. The message then moves through the statuses described below.
Key concepts
Authentication and scopes
Every request carries your key in the Authorization: Bearer header. Each key has scopes that limit what it can do: sms:send, sms:read, contacts:read, contacts:write and reports:read. A website that only sends messages needs only sms:send. You can also restrict a key to your server’s IP addresses. Read more in authentication.
Idempotency: no accidental duplicates
Networks fail, and software retries. If a request carries an Idempotency-Key header and is repeated with the same key and body within 24 hours, SMSGELY returns the original result instead of sending a second SMS. This is how you avoid texting a customer twice about the same order. Details are in the API reference.
Statuses
A message moves from queued to processing, submitted (accepted by the provider and charged), sent and ideally delivered. It may also end as failed or rejected (not charged), cancelled, or unknown when the provider’s answer was unclear. See message status and the plain-language table in the SMS guide.
Webhooks
Instead of repeatedly asking “has it been delivered yet?”, your server can receive a signed notification whenever a status changes or a campaign completes. Set them up in Dashboard → Developer → Webhooks and follow the webhooks guide to verify signatures.
Errors and limits
Problems come back as clear error codes, such as INSUFFICIENT_BALANCE when the wallet is low or MASKING_NOT_APPROVED when a masking ID is still pending. Each key also has a per-minute rate limit. The full list is in errors.
Where to go next
Developers should continue with the developer documentation. Business owners can share this page with their developer, and read the SMS API security checklist to make sure keys are handled safely.
Get your API key
Create an account, top up your wallet and generate a scoped API key from the dashboard in a few minutes.