Bloom SMS API Documentation

Welcome to the Bloom SMS Gateway API. Our platform provides high-performance SMS delivery with two specialized processing lanes: OTP (Instant delivery) and Promotional (Bulk throughput).

1. Authentication

Every request must include your unique API Key. You can provide it in two ways:

HTTP Header (Recommended): API-Key: your_key_here
Query Parameter: ?api_key=your_key_here

2. API Endpoints

Purpose	Endpoint	Lane
OTP SMS	`POST/GET /api/v1/sms/send/otp`	Priority (Low Latency)
Promotional SMS	`POST/GET /api/v1/sms/send`	Standard (Bulk)
Bulk SMS	`POST/GET /api/v1/sms/send/bulk`	Standard (Bulk)

IMPORTANT: Always use the **/otp** endpoint for time-sensitive messages like login codes, password resets, and alerts.

3. Request Parameters

Parameter	Type	Required	Description
`to`	String/Array	Yes	Recipient(s). For bulk, use comma-separated string or array.
`message`	String	Yes	The content of your SMS.
`sender`	String	No	Your approved Masking or Sender ID. Use `NOMASK` for default.
`gateway`	String	No	Target gateway provider (`route_mobile`, `gennet`). Auto-routed if omitted.
`api_key`	String	*	Required if not passed via HTTP Header.

4. Examples

Send OTP (GET Request)

GET https://api.yoursite.com/api/v1/sms/send/otp?api_key=bloom_abc123&to=8801700000000&message=Your+OTP+is+1234&sender=BLOOM

Send Bulk (GET Request)

GET https://api.yoursite.com/api/v1/sms/send/bulk?api_key=...&to=88017000,88017001&message=Hello&sender=BLOOM

Send Bulk (POST Request - JSON)

URL: https://api.yoursite.com/api/v1/sms/send/bulk
Header: API-Key: bloom_abc123
Body:

{
    "to": "8801700000000, 8801700000001",
    "message": "Check out our new summer sale!",
    "sender": "PROMO"
}

5. API Response

Success Response (HTTP 200)

{
    "success": true,
    "data": {
        "to": "8801700000000",
        "message_type": "TEXT",
        "status": "queued",
        "lane": "otp"
    },
    "message": "SMS queued successfully."
}

Success Response (Bulk Endpoint)

{
    "success": true,
    "data": {
        "total_recipients": 2,
        "total_cost": 1.0,
        "status": "queued"
    },
    "message": "Bulk SMS processed successfully."
}

Error Response (HTTP 401/422/400)

{
    "success": false,
    "message": "Insufficient wallet balance.",
    "errors": {
        "error": "Organization balance is less than estimated cost (BDT 0.50)."
    }
}

6. Rate Limits & Best Practices

Unicode Support: The API automatically detects Unicode characters. Unicode messages are limited to 70 characters per SMS part.
Concatenation: Long messages are automatically split and charged per part.
Async Processing: Our API is asynchronous. A "queued" status means your message has been accepted and is being transmitted by our high-speed Go workers.