canonical: https://jentic.com/apis/bulksms.com/bulksms

# BulkSMS JSON REST API

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.

## For AI agents

Send and read SMS, manage RMM attachments, block numbers, transfer credits, and register webhooks across 15 BulkSMS REST endpoints.

## Scope

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.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Messages** — Send messages, retrieve history, and read individual message and conversation detail
- **Blocked Numbers** — List and add suppressed phone numbers
- **Profile** — Read the authenticated account profile and credit balance
- **Credit Transfer** — Move credits between BulkSMS sub-accounts
- **Webhooks** — Manage delivery report and inbound message webhook subscriptions
- **RMM Attachments** — Pre-sign upload URLs for rich media attachments

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **BulkGate SMS API** — BulkGate is a European-focused SMS gateway with batch personalization in the request body; BulkSMS uses standard HTTP Basic auth and emphasises UK and ZA routing.
- **Bugfender API** — Bugfender captures runtime logs from mobile apps that may use BulkSMS for two-factor codes.
- **Buildium API** — Buildium triggers tenant-facing events that BulkSMS can fan out as branded SMS reminders.

## FAQ

### 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.