Skip to main content

API Overview

Msghub provides a complete REST API for sending messages, managing contacts, creating campaigns, and triggering flows.

Base URL

https://your-msghub.com/api/v1

Authentication

All requests require an API key in the X-API-Key header:

curl -X GET \
  https://your-msghub.com/api/v1/contacts \
  -H "X-API-Key: mk_live_..."

Get Your API Key

  1. Go Settings → API Keys
  2. Copy your API key (starts with mk_live_)
  3. Use in all requests

Request Format

All requests use JSON:

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+919876543210",
    "body": "Hello!"
  }'

Response Format

All responses are JSON:

{
  "messageId": "msg_abc123",
  "channel": "sms",
  "to": "+919876543210",
  "status": "queued",
  "createdAt": "2024-04-08T10:30:00Z"
}

Rate Limits

  • 100 requests per second per API key
  • 10,000 requests per day per API key

If you exceed limits, you'll receive a 429 (Too Many Requests) response.

Error Handling

Error Response

{
  "error": {
    "code": "invalid_phone_number",
    "message": "Phone number is not in valid E.164 format",
    "details": {
      "field": "to",
      "value": "919876543210"
    }
  }
}

Common Errors

CodeStatusDescription
invalid_api_key401API key is invalid or missing
invalid_phone_number400Phone number is not in E.164 format
invalid_email400Email address is invalid
channel_not_connected400Channel is not connected in Settings
template_not_found404Template does not exist
contact_not_found404Contact does not exist
rate_limit_exceeded429Too many requests
internal_error500Internal server error

API Endpoints

Messages

  • POST /messages/send — Send a message
  • GET /messages/{messageId} — Get message status
  • GET /messages — List messages

Contacts

  • POST /contacts — Create contact
  • GET /contacts/{contactId} — Get contact
  • PUT /contacts/{contactId} — Update contact
  • GET /contacts — List contacts
  • DELETE /contacts/{contactId} — Delete contact

Campaigns

  • POST /campaigns — Create campaign
  • GET /campaigns/{campaignId} — Get campaign
  • GET /campaigns — List campaigns
  • PUT /campaigns/{campaignId} — Update campaign

Flows

  • POST /flows/{flowId}/trigger — Trigger flow
  • GET /flows/{flowId} — Get flow
  • GET /flows — List flows

Webhooks

  • POST /webhooks — Create webhook
  • GET /webhooks — List webhooks
  • DELETE /webhooks/{webhookId} — Delete webhook

Pagination

List endpoints support pagination:

curl -X GET \
  "https://your-msghub.com/api/v1/contacts?page=1&limit=50" \
  -H "X-API-Key: mk_live_..."

Parameters:

  • page — Page number (default: 1)
  • limit — Items per page (default: 50, max: 100)

Response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1000,
    "pages": 20
  }
}

Webhooks

Msghub sends webhook events for:

  • Message delivered
  • Message read
  • Message failed
  • Contact created
  • Campaign completed

Configure Webhook

  1. Go Settings → Webhooks
  2. Click Add Webhook
  3. Enter:
    • Event — Which event to listen for?
    • URL — Where to send events?
  4. Click Save

Webhook Payload

{
  "event": "message.delivered",
  "messageId": "msg_abc123",
  "channel": "sms",
  "to": "+919876543210",
  "status": "delivered",
  "deliveredAt": "2024-04-08T10:30:05Z"
}

Verify Webhook Signature

All webhooks are signed with HMAC-SHA256:

X-Msghub-Signature: sha256=abc123...

Verify the signature:

import hmac
import hashlib

signature = request.headers.get('X-Msghub-Signature')
payload = request.body
secret = 'your_webhook_secret'

expected = 'sha256=' + hmac.new(
  secret.encode(),
  payload,
  hashlib.sha256
).hexdigest()

if signature == expected:
  # Signature is valid
  pass

SDK Support

Msghub SDKs are available for:

  • Python
  • Node.js
  • PHP
  • Ruby
  • Go

Python Example

import msghub

client = msghub.Client(api_key='mk_live_...')

# Send SMS
message = client.messages.send(
  channel='sms',
  to='+919876543210',
  body='Hello!'
)

# Get message status
status = client.messages.get(message.id)

# Create contact
contact = client.contacts.create(
  name='Rahul',
  phone='+919876543210',
  email='rahul@example.com'
)

Best Practices

Error Handling

Always handle errors:

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -d '{...}' \
  || echo "Request failed"

Rate Limiting

Respect rate limits:

# Add delay between requests
for contact in contacts; do
  curl -X POST \
    https://your-msghub.com/api/v1/messages/send \
    -H "X-API-Key: mk_live_..." \
    -d "{...}"
  sleep 0.01  # 10ms delay
done

Logging

Log all requests:

curl -X POST \
  https://your-msghub.com/api/v1/messages/send \
  -H "X-API-Key: mk_live_..." \
  -d '{...}' \
  | tee request.log

See Also