Email is the default channel. SMS is the urgency channel. When your AI agent needs to ping a real human in seconds — an outage, a fraud alert, an OTP, a shipping update — SMS is what actually gets read within a minute. This guide walks through wiring Claude, GPT or any tool-calling LLM to the Mailpro™ SMS API for both single sends and bulk campaigns.
TL;DR
- The Mailpro™ SMS API authenticates with
id_client+api_keyover HTTPS.- Use
/send/add_single.jsonfor a single SMS and/send/add.jsonfor bulk.- Numbers use international E.164 format (e.g.
+447700900123) or the equivalent00prefix — the API accepts both and stores the normalised form.- Every endpoint is documented in 20+ programming languages on our developer portal.
Where AI-driven SMS actually makes sense
Real-time alerts
Your monitoring pipeline detects a spike in 5xx errors. An AI agent reads the anomaly, classifies severity, and fires an SMS to the on-call engineer with context ("API v3 up 12× error rate last 5 min, affecting CRM endpoints") — not just a pager beep. Faster diagnosis, less alert fatigue.
OTPs and two-factor flows
The agent receives an "authenticate this user" request, generates a 6-digit code, stores it with an expiry, and sends it via SMS. The user types it back, the agent verifies. Today this is a custom flow; with the upcoming Verify/OTP endpoint (see our SMS API roadmap), it will be one API call.
Multi-channel fallback
Email didn't open within 2 hours, but it's urgent. The agent falls back to SMS — "Your appointment is in 1 hour" — using the same contact record from Mailpro™ v3. Cross-channel orchestration, driven by LLM reasoning.
Event-driven campaigns
Black Friday at noon: the agent picks the audience based on a freshness metric ("customers who opened any email in the last 14 days"), writes a 140-char offer, and fires a bulk campaign via /send/add.json. Offer live in under a minute, zero dashboard clicks.
Setup and SMS pricing model
id_client + api_key
Same auth pattern as the v2 email API. Find both in your Mailpro™ account under Settings → API access. The SMS API uses snake_case parameter names (id_client not IdClient) — a small difference from v2, worth flagging in your agent's system prompt.
Credits, country rates, test balance
SMS are not flat-priced: the cost per message depends on the destination country. Check your balance at any time:
curl "https://api.mailpro.com/sms/credit/get.json?id_client=YOUR_ID&api_key=YOUR_API_KEY"
Response:
{ "TotalCredits": 1476 }
For pricing by country, see Mailpro pricing.
Sandbox
No dedicated sandbox yet — test with small volumes using your real account. Start with /send/add_single.json sending to your own phone number before opening the tap to bulk.
Step-by-step: single SMS sent by an AI agent
1. Tool schema
tools = [{
"name": "send_sms",
"description": "Send a single SMS to a phone number via Mailpro.",
"input_schema": {
"type": "object",
"properties": {
"to": {"type": "string", "description": "International E.164 format, e.g. +447700900123"},
"message": {"type": "string", "description": "SMS body, max 160 chars for a single segment"}
},
"required": ["to", "message"]
}
}]
2. Phone number formatting
Use international E.164 format: + sign, country code, national number, no spaces or dashes. The 00 prefix in place of + also works. Examples:
-
United Kingdom:
+447700900123 -
Ireland:
+353861234567 -
United States:
+15551234567 -
Australia:
+61412345678
If your agent receives messy input ("07700 900 123"), normalise before sending — libraries like phonenumbers (Python) or libphonenumber-js (Node) handle this cleanly.
3. Call /send/add_single.json
curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
-d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
-d "to=+447700900123" \
-d "message=Your verification code is 482913. Valid 10 min."
Response:
{
"Result": "OK",
"IdSend": 98765,
"RemainingCredits": 1474
}
4. Delivery status from the response
Result: "OK" means the SMS was accepted by the gateway — not yet delivered to the handset. For delivery confirmation (DLR), listen for the upcoming sms.delivered webhook (see the SMS API roadmap). In the meantime, RemainingCredits tells you the send was billed.
Bulk SMS: let the agent target a whole list
Manage phone lists (/list, /phone)
Building an AI agent that texts? Mailpro’s plans include the SMS API, delivery reporting and the volume you need — at a price you can predict.
Phone lists are Mailpro™'s SMS equivalent of email address books. Endpoints to list, add, edit or delete lists and phones are all under /list/*.json and /phone/*.json.
Send a campaign with /send/add.json
curl -X POST "https://api.mailpro.com/sms/send/add.json" \
-d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
-d "id_list=11088" \
-d "message=Black Friday: 30% off until midnight. mailp.ro/bf2026"
The endpoint queues the campaign and fires SMS to every number in the list.
Schedule vs immediate
Add plan_date=2026-11-27T12:00:00 to schedule. Omit it for immediate send. The agent can pick the time based on recipient time zones — but watch aggregate delivery time: 10,000 SMS can take several minutes to flush through the gateway.
Bulk-importing phone numbers via file
Just like the email API, the SMS API now exposes a file upload endpoint:
n await fetch(`https://api.mailpro.com/sms/send/add_single.json`, { method: "POST", body: new URLSearchParams({ id_client: ID, api_key: KEY, to: b.input.to, message: b.input.message }) }); } } res.sendStatus(200); });cURL
curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
-d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
-d "to=+447700900123" \
-d "message=Your Mailpro backup completed successfully at 03:04 UTC."
For the same call in twenty+ other languages (PHP, Go, Ruby, C#, Java, Swift…), see the SMS reference — each endpoint ships the equivalent snippet ready to copy.
Coming soon: OTP Verify and Phone Lookup
Two features on our SMS API roadmap are particularly useful for AI agent integrations:
Verify / OTP endpoint
Rather than rolling your own OTP flow (generate code, store, send, check), the upcoming /verify/start and /verify/check endpoints handle it all: code generation, hashing, rate limits, multi-language templates, attempt counting. The agent just calls /verify/start and later /verify/check.
HLR Phone Lookup
The upcoming /phone/lookup endpoint will return real-time carrier info (mobile / fixed / voip), ported number detection, and reachability. Essential for cleaning lead lists before an SMS campaign — no point sending to a disconnected number.
Both features will plug into the same auth model, making them immediately consumable by AI agents.
Tips and gotchas
PascalCase responses (like v2 email)
Mailpro™ SMS returns Result, IdSend, RemainingCredits — PascalCase. Matches v2 email, differs from v3 CRM (snake_case). Tell your agent in the system prompt.
STOP handling and phone suppression
Users can reply STOP to opt out. Currently, our gateway handles this and blocks future sends automatically. The upcoming /suppressions endpoint will expose the suppression list as an API resource — for audit and manual management.
GDPR and consent
Always have explicit consent before sending marketing SMS. For transactional SMS (OTP, alerts triggered by user action), consent is implicit. Your agent should not be the one deciding whether to opt a user in — that's a legal decision, not a prompting one.
Case study (fictional): "VeloCourier" — London bike delivery with AI-driven ETA SMS
VeloCourier delivers food and packages across central London. Historically, customers got a "your courier is on the way" SMS at pickup, and that was it. The team wired Claude behind the dispatch system: whenever a courier's GPS showed them within 500 m of the drop-off, the agent fired a Mailpro™ SMS with a tailored message based on order type ("Your coffee is 2 minutes away — please be at the door"). Customer NPS on the arrival step went up 18 points. SMS volume grew 30%, which Mailpro™ cost-wise stayed well below the support-call savings. The dispatch team now monitors the agent's sent messages in the Mailpro™ history view; occasionally tweaks the prompt when a tone isn't quite right.
Next step
SMS is the last major channel in the Mailpro™ stack. If you haven't read our pillar guide on AI agents and Mailpro yet, start there for the full picture. For the companion email guides, see Transactional email v2 and CRM v3.
Reference: Mailpro SMS API. Pricing: Mailpro pricing.
FAQ
Can an AI agent send OTP codes via Mailpro?
Today yes, by rolling your own: generate a 6-digit code, store it with an expiry, send via /send/add_single.json. Very soon, a dedicated /verify/start + /verify/check endpoint will do all of this in one call. See the SMS API roadmap.
What's the price per SMS?
Varies by destination country. See pricing for the current rate card.
Does the API support international numbers?
Yes, Mailpro™ sends to 200+ countries. Use E.164 format (+<country code><number>, e.g. +447700900123) or the equivalent 00 prefix — the API accepts both.
How do I block a number that replied STOP?
Currently handled automatically at the gateway level. The upcoming /suppressions endpoint will let you list, add and remove suppressed numbers via API — useful for sync with your own database of preferences.
Mailpro and the SMS API
Let your AI agent send SMS — Mailpro handles the rest
Wire your AI agent to Mailpro’s SMS API and it can text customers on its own — reminders, alerts, confirmations. You get the reach and the reporting; see what it costs to run.
