Send Bulk SMS via API: 200,000 Month-End Alerts in Batches

If you need to send bulk SMS via API at month-end, send the 200,000 alerts in batches rather than one call per customer. For alerts where each customer gets their own content, such as a balance, a debit or a premium due date, use the V2 template send operation: at the time of writing, a single template send request accepts up to 15,000 recipients. For one identical message to many people, use the plain V2 send operation, where at the time of writing a single v2 send request accepts up to 10,000 recipients. Then store every id the response returns with the request it came from, so you can track delivery status afterwards.
Those two caps reflect how the API behaves today. They are not a documented commitment, so confirm the current limits with Arkesel before you size a production job. Batching is general engineering practice, not an Arkesel requirement: fewer requests means fewer things to retry, log and reconcile when something goes wrong half-way through.
What do you need to get right when you send bulk SMS via API at month-end?
A typical month-end job at a bank, insurer or fintech sends one alert per customer: a statement summary, a debit notice, a premium reminder. It has to finish inside a fixed window, and weeks later someone in audit or customer service will ask whether a particular customer received theirs.
That gives you three requirements to design for:
- Finish on time. The run has to complete inside the window you promised customers.
- Survive a partial failure. If the job stops at customer 87,000, you need to restart without sending the first 87,000 a second copy.
- Prove delivery. Every message needs a record you can match to a customer and a final status.
A holiday promotion follows the same pattern, except that everyone on the list gets the identical message. It uses a different API operation and, for Nigerian numbers, a different billing consideration. Our guide to holiday SMS campaigns covers the campaign planning side.
Method 1: one API call per recipient
The most direct approach is a loop that sends one request per customer. According to Arkesel’s published API specification, the V1 send-sms operation sends to a single phone number or to several numbers, separated by commas in the ‘to’ parameter. You can also loop over the V2 send operation with one recipient per request.
The two versions handle your key differently. Version 1 passes the api_key as a query parameter, while version 2 passes the API key as a header parameter. As a general precaution, prefer the header: a key carried in a URL can end up in web server and proxy logs, and a month-end loop writes a lot of those.
Error handling matters more in a loop than anywhere else, because every customer is a separate chance to fail. The V1 API’s documented statuses include insufficient balance, invalid phone number, and a hold when an SMS contains a spam word and waits for approval. Treat each one differently:
- Insufficient balance: stop the run. Every later call will fail the same way until you top up, so retrying only fills your logs.
- Invalid phone number: log the customer and move on. Resending will not fix the number; your source data needs correcting.
- Spam-word hold: do not resend. Review the wording that triggered the hold before your next run.
A loop is fine for a few hundred messages, a one-off script or a test. At 200,000 it is the slowest option, because every customer costs a full network round trip, and it produces 200,000 separate requests to track. For a first walk-through of authentication and a working request, see how to send SMS through the Arkesel API.
Method 2: concurrent workers sending in parallel
If you put the recipients on a queue and let several workers send at the same time, the run gets shorter, but it is still one request per customer, so you still have 200,000 requests to log and retry. It also raises the rate at which you call the API.
The SMS API applies rate limiting to incoming requests, and no figure is published. Treat that as a reason to keep concurrency modest, back off when a request errors, wait a little longer before each retry, and talk to Arkesel about your throughput needs before a large month-end run rather than discovering the ceiling on the night.
The V2 status list in the API spec documents six responses: successfully sent, authentication failed, insufficient balance, inactive gateway, validation errors and internal error. Build your back-off around failed requests in general rather than waiting for one particular response. Not every failure is worth retrying, though. An authentication failure or an insufficient balance needs a person to act, and a validation error means the data needs fixing, so retrying any of these just repeats the failure.
Retries also carry a risk that matters more than speed. If a request times out, you do not know whether the API accepted it. Resending blindly can give a customer the same debit alert twice, which sends worried customers to your support team. Record each request before you send it, and check what went out before you resend anything that timed out.
One practical step for any large job: Arkesel API keys support sub-keys so a user can limit or monitor usage. Giving the month-end job its own key keeps its usage separate from your day-to-day traffic, such as login codes. Our article on multiple API keys explains how they work.
Method 3: batch requests on the V2 API
Batching puts many recipients into one request. For a run this size it is the better default on general engineering grounds: at current caps a 200,000-alert job becomes 14 to 20 requests, plus any splits you make by send time, instead of 200,000, and each request returns its results together.
Per-customer alerts: template send
The V2 template send operation sends variable SMS, where each recipient carries its own values and every recipient must use the same variable keys. In practice, every customer in one request shares the same message structure, for example a name, an amount and a date, while the values differ per customer. The Arkesel API documentation shows the exact format for the variables.
In a template send, one callback URL and one scheduled date apply to every message in that request. If some alerts must go out at a different time, for example debit notices in the morning and premium reminders in the afternoon, put them in separate requests. Before you schedule any of them, read the note on collecting ids for scheduled requests in the checklist below.
At the time of writing, a single POST /api/v2/sms/template/send request accepts up to 15,000 recipients. For more on writing messages that use each customer’s details well, see our guide to personalising bulk SMS.
One identical message: send and contact-group send
When every recipient gets the same text, such as a holiday greeting or a branch closure notice, use the plain V2 send operation. The V2 send endpoint takes its recipients as an array of mobile numbers, so one request can address many recipients. At the time of writing, that request accepts up to 10,000 recipients.
If the list already lives in your Arkesel account, the V2 API has a separate operation that sends one SMS request to a saved contact group. Its request carries one message for the whole group, which suits a promotional message to a stored list.
How many recipients can I send to in one SMS API request?
At the time of writing, a single v2 send request accepts up to 10,000 recipients and a single template send request accepts up to 15,000. Treat both as current limits rather than guaranteed ones, as noted at the start of this guide.
For a 200,000-alert run, that works out as follows:
- Template send (per-customer alerts): at least 14 template send requests. Thirteen full requests of 15,000 cover 195,000 customers, and a fourteenth carries the last 5,000.
- Plain send (identical message): at least 20 send requests of 10,000 each.
These are minimums. Splitting by send time, as the template send section explains, can add requests, and so can splitting by product line if your teams want separate records.

Should I send SMS one at a time or in batches?
For 200,000 alerts, batch them. Sending one at a time suits small jobs and tests, concurrent workers speed up a loop without reducing the number of requests, and batch requests cut the request count the most.
| One call per recipient | Concurrent workers | V2 batch requests | |
|---|---|---|---|
| Requests for 200,000 alerts | 200,000 | 200,000, spread across workers | At least 14 template send or 20 send requests, at the time of writing |
| Speed | Slowest: one round trip per customer | Faster, but rate limiting still applies | Fewest round trips |
| What one failed request affects | One customer | One customer, though failures can arrive together when workers retry at once | Every recipient in that request, so log each request’s recipients |
| Personalisation | Per call | Per call | Template send: per-recipient values; plain send: identical text |
| Reconciliation | One response to store per customer | One response to store per customer | One response per request; store every id it returns with the request it came from (the spec’s template-send example lists recipient and id pairs) |
| Best for | Tests, scripts, small runs | Teams already built around a queue | Month-end alerts and large campaigns |
Before you build, read the batch and template operations in the API docs, or talk to support to confirm current recipient limits and throughput needs for your run.
How do I know which messages in a bulk send were delivered?
Store the ids your send responses return, then match delivery statuses to them. For an immediate send, a V2 send response returns an id for each recipient, which identifies that message during delivery notification. For template send, Arkesel’s published API specification includes an example template-send response whose data array lists recipient and id pairs.
Save every id your send responses return with the request it came from, before you do anything else with the response. For template send, the spec shows ids only in an example, so confirm with Arkesel how template-send ids correspond to recipients before you rely on them as audit evidence. A small live template batch to numbers your team controls, covered in the testing section below, lets you see the response shape first.
From there, three sources of status work together:
- The per-recipient report. The platform normally updates a message’s delivery status within about one minute of delivery, and you can see it per recipient. Arkesel does not send failure alerts, so your job has to look for failed statuses itself.
- Delivery callbacks. Callbacks report statuses such as DELIVERED, SUBMITTED, PROHIBITED, QUEUED, NOT_DELIVERED and EXPIRED.
- Batch lookups. The Batch SMS Report operation accepts a minimum of 1 and a maximum of 1000 SMS UUIDs per request. That limit applies to looking up message ids, not to sending. For a large run, work through your stored ids in chunks to recheck messages still showing SUBMITTED or QUEUED.

Our guide to SMS delivery reports explains what each status means and when a resend makes sense.
Handling delivery webhooks on a large run
Delivery-status webhooks are dispatched in batches every ten minutes, so a webhook can take up to about ten minutes to arrive. Design your reconciliation around that: do not mark a customer as unreached just because no callback has arrived a few minutes after the send.
Three habits keep webhook handling reliable at this volume:
- Deduplicate. Each delivery callback carries an X-Arkesel-Webhook-Id header that the receiver should store to detect duplicate callback deliveries. Store it and skip any id you have already processed.
- Check freshness. When verifying a callback signature, reject timestamps older than five minutes. This protects against replayed callbacks; it says nothing about how quickly delivery happens.
- Leave the secret alone mid-run. When a webhook secret is rotated, the previous secret stays valid for 24 hours and callbacks carry signatures for both secrets during that window. That makes rotation safe in general, but changing secrets during a month-end run adds an avoidable variable, so schedule it for a quiet day.
Can I test a bulk SMS job without being charged?
Yes, for the V2 send operation: set the sandbox field to true in the request. Sandbox sends are not billed, are not forwarded to the mobile networks, and appear only in the SMS history report. The sandbox simulates real API behaviour, including delivery callbacks, without spending live credit, so you can rehearse your batching, id storage and webhook handling end to end. The sandbox is documented on the V2 send endpoint; confirm with Arkesel whether template send requests can run in it, and otherwise test them with a small live batch to numbers your team controls.
Then work through this list before the real run:
- Check your balance. The V2 API includes a Check balance operation, so make it the first step of the job.
- Set a low balance alert. Low balance alerts notify you by email or webhook when credit falls below a threshold you set, which gives you warning before a run stops half-way.
- Check the sender ID. The sender ID field accepts 11 characters at most, including spaces, and longer values cause messages to fail.
- Normalise numbers. The SMS send API accepts recipient numbers with a leading + as well as the 233 form, so pick one format and apply it across your list.
- Estimate segments. SMS is billed per segment, and one non-GSM character switches a message to Unicode and drops capacity per segment from 160 characters to 70 (67 once concatenated), multiplying the charge. GSM is the standard SMS character set. Check your templates before the run, and see current pricing for rates.
- Decide how you will collect ids before you schedule. A V2 send request can be scheduled by adding a scheduled_date field, and the documentation gives the date format. A scheduled request may not return ids when you submit it. If you need to reconcile the job, confirm with Arkesel how to collect ids for scheduled messages first. If you cannot get that answer before the run, trigger the requests from your own job scheduler at the send time instead, so each one is an immediate send.
Sending month-end alerts to Nigerian numbers
In Nigeria, transactional messages are delivered through the DND route after the sender ID is whitelisted, which takes about 4-6 weeks and applies to Nigerian-registered businesses. DND stands for Do Not Disturb. If you plan to send month-end alerts to Nigerian customers, start the whitelisting well before your first run. If your business is not registered in Nigeria, ask Arkesel how your alerts will be routed. Our article on Nigeria DND and sender IDs explains what goes wrong when the route is not set up.
Promotional campaigns follow different billing. On a promotional campaign, an unreachable number still costs the sender: credit is charged for every number uploaded, including Nigerian numbers that DND blocks from receiving the message. Clean your list before a holiday campaign to Nigerian numbers. If you are unsure which category a message falls into, read our guide to transactional vs promotional SMS, and see the SMS API in Nigeria page for local details.
Frequently asked questions
How should I send 200,000 SMS through an API?
Batch requests on the V2 API. Template send handles per-customer alerts at up to 15,000 recipients per request at the time of writing, and plain send handles identical messages at up to 10,000. Both need far fewer requests than a loop or a pool of workers.
Is there a rate limit on the SMS API?
Yes. The API applies rate limiting to incoming requests. Keep concurrency modest, back off and retry when a request errors, and confirm your throughput needs with Arkesel before a large run.
How long does delivery status take to appear?
The per-recipient report normally updates within about one minute of delivery. Delivery webhooks arrive in batches every ten minutes, so allow for that delay in any process that waits on a callback.
Related Articles
Plan your month-end run
The SMS API ships copy-paste code samples in cURL, Python, Node.js and PHP, and there are no official SDK client libraries, so start from the code samples in the developer documentation and adapt them to your batching and id storage. If your customers are in Ghana, the SMS API in Ghana page covers local details.
Create a free account and rehearse your month-end job before the real send: run plain V2 sends in the sandbox, and test template sends with a small live batch to numbers your team controls unless Arkesel confirms they can run in the sandbox. If you want to talk through limits or timing for a large run, Arkesel support runs by email and live chat from 06:00 to 22:00 UTC, so contact the team during those hours, ahead of the month-end window rather than on the night.





