SendBabaAPI Referencev1.0
LIVE API

SendBaba API
Reference

Transactional and marketing email infrastructure built for Africa. 42+ endpoints. 4 AI tools.

BASE URLhttps://api.sendbaba.com/api/v1
42+
API Endpoints
99.5%
Deliverability
4 AI
AI Endpoints
Getting Started

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from Dashboard → Settings → API Keys.

🔑
Pass your API key as Bearer YOUR_KEY on every request.
Header
cURL
Authorization: Bearer sb_live_your_api_key_here
curl -X POST https://api.sendbaba.com/api/v1/emails/send \
  -H "Authorization: Bearer sb_live_your_key" \
  -H "Content-Type: application/json"
sb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxLIVE
sb_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSANDBOX
⚠️
Never expose API keys in frontend code or public repos. Always use environment variables.
Getting Started

Quick Start

Send your first email in under 2 minutes.

cURL
Node.js
Python
PHP
Go
curl -X POST https://api.sendbaba.com/api/v1/emails/send \
  -H "Authorization: Bearer sb_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "recipient@example.com",
    "subject": "Hello from SendBaba!",
    "html": "<h1>It works!</h1>"
  }'
const res = await fetch('https://api.sendbaba.com/api/v1/emails/send', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.SENDBABA_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ from: 'hello@yourdomain.com', to: 'recipient@example.com', subject: 'Hello!', html: '<h1>It works!</h1>' })
});
import requests, os
resp = requests.post('https://api.sendbaba.com/api/v1/emails/send',
    headers={'Authorization': f'Bearer {os.environ["SENDBABA_API_KEY"]}'},
    json={'from':'hello@yourdomain.com','to':'recipient@example.com','subject':'Hello!','html':'<h1>It works!</h1>'})
$ch = curl_init('https://api.sendbaba.com/api/v1/emails/send');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('SENDBABA_API_KEY'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['from'=>'hello@yourdomain.com','to'=>'recipient@example.com','subject'=>'Hello!','html'=>'&lt;h1&gt;It works!&lt;/h1&gt;'])]);
$d = json_decode(curl_exec($ch), true);
req, _ := http.NewRequest("POST", "https://api.sendbaba.com/api/v1/emails/send", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SENDBABA_API_KEY"))
202 Response
{
  "success": true,
  "data": { "id": "e72f9a01-3b44...", "status": "sent" }
}
Email

Send Email

Send a single transactional email. Supports HTML, plain text, CC, BCC, reply-to, tags and metadata.

POST/v1/emails/send
ParameterTypeRequiredDescription
fromstringrequiredSender email — must be a verified domain
tostring | arrayrequiredRecipient email(s)
subjectstringrequiredEmail subject line
htmlstringoptionalHTML body content
textstringoptionalPlain text fallback
reply_tostringoptionalReply-to address
ccstring | arrayoptionalCC recipients
bccstring | arrayoptionalBCC recipients
tagsarrayoptionalTags for analytics grouping
metadataobjectoptionalCustom key-value data returned in webhooks
💡
Either html or text is required.
POST/v1/emails/batchBatch Send
SMS

Send SMS

Send a single transactional or promotional SMS to any mobile number. Billed per segment from your SMS wallet. Requires the sms.send scope.

POST/v1/sms/send
ParameterTypeRequiredDescription
tostringrequiredRecipient number, international format (e.g. 2348141261989)
bodystringrequiredMessage text. Max 1600 characters (10 segments)
fromstringoptionalSender ID: Sendbaba, SBverify, or SBpromos. Defaults to Sendbaba
referencestringoptionalYour own tracking id, echoed back in the response
💰
Billed at ₦6.85 per segment from your SMS wallet. The response returns charged and balance_after. Low balance returns 402 insufficient_balance.
SMS

Check SMS Balance

Retrieve your current SMS wallet balance, per-segment rate, and recent transactions. Requires the sms.read scope.

GET/v1/sms/balance/api

Returns balance, currency, rate_per_segment, and recent_transactions.

SMS

Sender IDs

The from field sets the sender name recipients see. Use the right sender ID for each message type.

Sender IDUse ForDescription
SBverifyTransactionalOTP codes, verification, alerts. Delivers to all numbers including DND
SBpromosMarketingPromotional messages. Subject to DND filtering
SendbabaDefaultGeneral purpose. Used when no sender ID is specified
ℹ️
An unapproved sender ID returns 403 sender_not_approved. Contact support to whitelist a custom branded sender ID.
SMS

Segments & Pricing

SMS is billed per segment. A segment is a single 160-character message (GSM-7). Longer messages and special characters split into multiple segments.

EncodingSingle SegmentMulti-Segment (each)
GSM-7 (standard text)160 chars153 chars
UCS-2 (emoji / non-Latin)70 chars67 chars
💰
Each segment costs ₦6.85. A 200-character message = 2 segments = ₦13.70. Top up in Dashboard → SMS.
Templates

Templates

Store reusable HTML templates server-side. Send by ID using {{variable}} merge tags.

POST/v1/templatesCreate
GET/v1/templatesList
GET/v1/templates/:idGet
PUT/v1/templates/:idUpdate
DEL/v1/templates/:idDelete
POST/v1/templates/:id/previewPreview
GET/v1/templates/libraryBrowse public library
POST/v1/templates/library/:id/cloneClone to your account

Clone a public library template into your account. Returns a new template_id ready to use.

ℹ️
Cloned templates are private to your account. Changes don't affect the original library template.
POST/v1/emails/send-templateSend via template
ParameterTypeRequiredDescription
tostringrequiredRecipient email
template_idstringrequiredTemplate UUID
variablesobjectoptionalKey-value pairs to substitute
subjectstringoptionalOverride template subject
Webhooks

Webhooks

Receive real-time HTTP POST notifications for email events. All payloads are signed with HMAC-SHA256.

GET/v1/webhooksGet config
POST/v1/webhooksConfigure
ParameterTypeRequiredDescription
urlstringrequiredHTTPS endpoint to receive events
eventsarrayoptionalEvents to subscribe (default: all)
💡
The webhook secret is returned only once — on creation. Store it immediately.
POST/v1/webhooks/testSend test event
DEL/v1/webhooksDelete

Events Reference

EventDescription
email.sentAccepted by recipient mail server
email.deliveredConfirmed delivery to inbox
email.openedRecipient opened the email
email.clickedRecipient clicked a tracked link
email.bouncedHard or soft bounce
email.complainedMarked as spam
email.unsubscribedRecipient unsubscribed

Verify Signatures

Node.js
Python
PHP
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
expected = 'sha256=' + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig)
$expected = 'sha256='.hash_hmac('sha256', $payload, getenv('WH_SECRET'));
if (!hash_equals($expected, $sig)) { http_response_code(401); exit; }
Sub-Accounts

Sub-Accounts

Isolate sending streams per product, client, or email type. Each sub-account has its own API key, limits, and stats.

POST/v1/subaccountsCreate
ParameterTypeRequiredDescription
namestringrequiredSub-account name
daily_limitintegeroptionalMax emails/day (default: 10,000)
monthly_limitintegeroptionalMax emails/month (default: 300,000)
ℹ️
The API key is returned once — on creation only. Store it immediately.
GET/v1/subaccountsList
POST/v1/subaccounts/:id/rotate-keyRotate key
GET/v1/subaccounts/:id/statsStats
Validation

Email Validation

Validate emails before sending. Checks format, MX records, typo domains, disposable addresses, and suppression list.

POST/v1/validate/emailValidate single
Request
Response
{ "email": "john@gmial.com", "check_mx": true }
{ "data": { "is_valid": false, "reason": "Typo: gmial.com → gmail.com", "risk_level": "high" } }
POST/v1/validate/emailsValidate batch (max 1000)
AI Endpoints

AI-Powered Tools

4 AI endpoints powered by Claude. Analyze campaigns, generate subject lines, write emails, and detect spam.

🤖
Same API key. All responses return structured JSON.
POST/v1/ai/analyzeAnalyze campaign
ParameterTypeDescription
typestringdeliverability | subject | content | timing | full
subjectstringSubject line to analyze
htmlstringHTML body for content analysis
send_timestringProposed send time
POST/v1/ai/subject-generatorGenerate subject lines
POST/v1/ai/email-writerWrite email content
POST/v1/ai/spam-checkSpam checker
POST/v1/ai/generate-templateGenerate + save template
ParameterTypeRequiredDescription
descriptionstringrequiredPlain English description of the email
brand_namestringoptionalYour brand name
brand_colorstringoptionalHex color for buttons
tonestringoptionalprofessional | casual | formal
categorystringoptionalotp | welcome | auth | transactional
savebooleanoptionalSave to account (default: true)
🚀
The returned id is immediately usable with POST /v1/emails/send-template.
Reference

Error Handling

All errors return JSON. Use the error field as a stable machine-readable code.

{
  "success": false,
  "error": "domain_not_verified",
  "message": "Domain is not verified for your organization"
}
CodeMeaningAction
200OKRequest successful
202AcceptedEmail queued for delivery
400Bad RequestFix request parameters
401UnauthorizedCheck your API key
404Not FoundResource doesn't exist
429Rate LimitedCheck X-RateLimit-Reset and retry
500Server ErrorRetry with exponential backoff
Reference

Rate Limits

Enforced per API key per minute. All responses include these headers.

X-RateLimit-Limit:     60
X-RateLimit-Remaining: 57
X-RateLimit-Reset:     43   # seconds until window resets
PlanPriceReq/MinEmails/DayEmails/Month
Free$0101001,000
Starter$10601,00010,000
Growth$491205,00050,000
Professional$9920015,000150,000
Scale$19930030,000300,000
Business$29950050,000500,000
EnterpriseCustom1,000+CustomCustom
SMTP

SMTP Relay

Connect any app that supports SMTP — WordPress, WooCommerce, Laravel, Django — to SendBaba's delivery infrastructure.

SettingValue
Hostsmtp.sendbaba.com
Port (TLS)587
Port (SSL)465
EncryptionTLS / STARTTLS / SSL
UsernameDashboard → Settings → SMTP
Auth MethodLOGIN or PLAIN
Nodemailer
Django
Flask
PHPMailer
Go
const transporter = nodemailer.createTransport({
  host: 'smtp.sendbaba.com', port: 587, secure: false,
  auth: { user: 'your_smtp_username', pass: 'your_smtp_password' }
});
# settings.py
EMAIL_HOST = 'smtp.sendbaba.com'
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = 'your_smtp_username'
EMAIL_HOST_PASSWORD = 'your_smtp_password'
app.config.update(
  MAIL_SERVER = 'smtp.sendbaba.com',
  MAIL_PORT = 587, MAIL_USE_TLS = True,
  MAIL_USERNAME = 'smtp_user', MAIL_PASSWORD = 'smtp_pass'
)
$mail->Host = 'smtp.sendbaba.com';
$mail->SMTPAuth = true;
$mail->Port = 587;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
auth := smtp.PlainAuth("", "smtp_user", "smtp_pass", "smtp.sendbaba.com")
SMTP

Connect Gmail to SendBaba

Send from your verified SendBaba domain directly inside Gmail with full DKIM/SPF/DMARC authentication.

Works with personal Gmail and Google Workspace. Recipients see your domain — not gmail.com.
1
Get your SMTP credentials
Go to Dashboard → Settings → SMTP and click + Create Credential. Copy the username and password.
2
Open Gmail Settings
Click the gear icon → See all settings → Accounts and Import → under "Send mail as" click Add another email address.
3
Enter your name and email
Name: your name. Email: your SendBaba verified domain address. Leave "Treat as an alias" checked.
4
Enter SMTP settings
SMTP Server: smtp.sendbaba.com | Port: 465 (SSL) or 587 (TLS) | Username/Password: from step 1 | IMAP: mail.sendbaba.com:993
5
Verify your email
Gmail sends a verification email to your SendBaba address. Click the verification link or enter the 6-digit code.
You're live
When composing in Gmail, click From to switch to your SendBaba domain. All emails route through SendBaba infrastructure.
⚠️
Make sure your domain is fully verified (SPF ✓ DKIM ✓ DMARC ✓) before connecting Gmail.