BulkSMS JSON REST API
Official vendor OpenAPI document · agent-readyCommunicationsSms Messagingbasic15 EndpointsREST
For Agents
Send and read SMS, manage RMM attachments, block numbers, transfer credits, and register webhooks across 15 BulkSMS REST endpoints.
Use for: I need to send a transactional SMS through BulkSMS, Retrieve the delivery status of a specific message, List all messages received on my BulkSMS number today, Add a phone number to the BulkSMS block list
Not supported: Does not handle voice calls, email, or contact list management - use for outbound and inbound SMS, RMM attachments, blocked numbers, credit transfers, and webhooks only.
BulkSMS is a long-running global SMS gateway with strong UK and South African routing and dedicated number support. The JSON REST API covers the full message lifecycle: sending one or many messages, retrieving message history with delivery status, attaching media for RMM (Rich Mobile Messaging), managing blocked numbers, transferring credit between accounts, and registering webhooks for delivery and inbound events. Use it for transactional SMS, two-factor authentication, marketing pushes, and inbound number handling. The API supports both username-password and API token credentials over HTTP Basic auth.
Install Jentic One Beta
Connect the BulkSMS JSON REST API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the BulkSMS JSON REST API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fbulksms.com%2Fbulksms" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fbulksms.com%2Fbulksms" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with BulkSMS JSON REST API.
Send a single SMS via simple GET or POST or a batch via the messages POST endpoint
Retrieve sent and received messages with their delivery status and metadata
Pre-sign an upload URL to attach media to an RMM message
List and add numbers to the blocked numbers list to suppress sends
Transfer credits between BulkSMS sub-accounts programmatically
Read the authenticated account profile, including credit balance and limits
Register, update, list, and delete webhooks for inbound and delivery events
Use Cases
Patterns agents use BulkSMS JSON REST API for, with concrete tasks.
★ Two-Factor Authentication SMS
Deliver one-time passwords for login flows using BulkSMS as a high-deliverability transactional channel. The agent posts the OTP and recipient to /messages with the to and body fields, then either polls GET /messages/{id} for status or relies on a webhook configured via POST /webhooks to receive a delivery report. BulkSMS routing is well-suited to UK and South African numbers in particular.
Send the message Your code is 392104 to phone +27821112233 via POST /messages and store the returned message id.
Inbound SMS to Webhook
Capture replies to a dedicated number and route them into a help desk or chat agent. POST /webhooks registers a webhook URL for inbound message events, GET /webhooks lists current subscriptions, and DELETE /webhooks/{id} retires one. This gives you a structured webhook event for every reply rather than polling the messages list endpoint.
Register a webhook pointed at https://example.com/sms-incoming to receive inbound message events from BulkSMS.
Bulk Marketing Sends with Block-List Hygiene
Send marketing SMS campaigns while respecting opt-outs. The agent first calls GET /blocked-numbers to confirm the recipient list does not include suppressed numbers, then sends the campaign via POST /messages. POST /blocked-numbers adds new opt-outs as they arrive, keeping future campaigns compliant without extra bookkeeping.
Send a marketing SMS batch to 2000 recipients via POST /messages after filtering out any numbers returned by GET /blocked-numbers.
AI Agent Notification Service via Jentic
An agent connected via Jentic can send transactional SMS in response to natural-language requests like text Maria the meeting is rescheduled. The agent searches Jentic for send sms, loads the POST /messages schema, and executes against the operator's vault-stored BulkSMS API token without exposing the credential to the model.
Search Jentic for send a BulkSMS message, load the POST /messages schema, and send the user-supplied body to the user-supplied phone number.
Key Endpoints
15 endpoints — bulksms is a long-running global sms gateway with strong uk and south african routing and dedicated number support.
METHOD
PATH
DESCRIPTION
POST
/messages
Send messages
GET
/messages/{id}
Show a message
GET
/messages
Retrieve messages
POST
/blocked-numbers
Add a blocked number
POST
/webhooks
Create a webhook
POST
/credit/transfer
Transfer credits to another account
POST
/rmm/pre-sign-attachment
Pre-sign an RMM attachment upload
POST
/messages
Send messages
GET
/messages/{id}
Show a message
GET
/messages
Retrieve messages
POST
/blocked-numbers
Add a blocked number
POST
/webhooks
Create a webhook
POST
/credit/transfer
Transfer credits to another account
POST
/rmm/pre-sign-attachment
Pre-sign an RMM attachment upload
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring BulkSMS by hand means constructing its HTTP Basic Authorization header from your token id and secret against api.bulksms.com/v1 and shaping each message payload yourself. Through Jentic you install once, import BulkSMS from the API Directory, store the token once, and your agent calls it.
Permission scoping
BulkSMS carries the recipients in the request body and references a message by id only when reading its status, so scope the agent by the operations it needs, such as sending a message or listing sent messages. Because you choose the allowed operations, it can send and read messages without being able to transfer credit or block numbers unless you add those.
Credential isolation
Your BulkSMS token id and secret are stored once, encrypted, by your own Jentic One instance and used to build the Basic Authorization header at execution time. Neither value ever enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'send an SMS' or 'register a webhook', and Jentic returns the matching BulkSMS operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using BulkSMS JSON REST API through Jentic.
What authentication does the BulkSMS JSON REST API use?
BulkSMS uses HTTP Basic auth. You can use either your account username and password or a generated API token (token-id and token-secret) - API tokens are recommended for production. Through Jentic, the credential pair is stored encrypted in the vault and the Basic auth header is constructed at execution time.
Can I send SMS in bulk through the BulkSMS API?
Yes. POST /messages accepts an array of message objects so a single request can dispatch many recipients with different bodies. Use GET /messages/{id} to confirm delivery for individual messages or register a webhook via POST /webhooks for delivery reports.
Does the BulkSMS API support inbound SMS replies?
Yes. Configure a webhook with POST /webhooks pointing at your endpoint, and BulkSMS will deliver inbound message events to it. GET /messages and GET /messages/{id}/relatedReceivedMessages also let you pull received messages and conversation threads on demand.
How do I attach an image to a BulkSMS RMM message?
POST /rmm/pre-sign-attachment returns a signed upload URL. Upload the file to that URL, then reference the returned attachment identifier when calling POST /messages so the message is delivered as RMM with the media attached.
What are the rate limits for the BulkSMS API?
BulkSMS applies per-account throughput limits that depend on your plan and route. The OpenAPI spec does not encode the exact quotas - add retry-with-backoff for HTTP 429 responses and prefer batch sends over many individual calls when dispatching campaigns.
How do I send a BulkSMS message from an AI agent through Jentic?
Run pip install jentic and authenticate with your ak_* key. Search Jentic with send a BulkSMS message, load the POST /messages operation, and execute it with the to and body fields. Jentic injects the Basic auth header from your stored API token without exposing the secret to the agent.
Can I limit what my agent is allowed to do with the BulkSMS API?
Yes. Because Jentic One is self-hosted, you decide in your own rules which BulkSMS operations the agent may call and which stored credential it uses. You can allow only sending a message via POST /messages and reading status via GET /messages/{id} and GET /messages, so the agent can send and read messages without being able to transfer credit via POST /credit/transfer or add entries via POST /blocked-numbers. Those operations stay off limits until you explicitly grant them.
GET STARTED