The Monster SMS REST API lets you integrate SMS sending, contact management, and conversation data directly into your own applications. This guide covers authentication, available endpoints, and working code examples.

Getting your API key

To generate an API key:

1. Log in to app.monstersms.ai
2. Click your name in the top right → Settings
3. Go to the API tab
4. Click Generate API Key
5. Copy and store your key securely — it will only be shown once

Authentication

Include your API key in every request using the X-API-Key header:

X-API-Key: your_api_key_here
Content-Type: application/json

Endpoints

Send an SMS

POST /messages/send

Send a single SMS to a contact.

curl -X POST https://api.monstersms.ai/v1/messages/send \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+61412345678",
    "message": "Hi Jane, your appointment is confirmed for tomorrow at 2pm. Reply STOP to opt out.",
    "sender_id": "+61498765432"
  }'

Response:

{
  "success": true,
  "message_id": "msg_a1b2c3d4",
  "to": "+61412345678",
  "status": "queued",
  "credits_used": 1
}

Get contacts

GET /contacts

Retrieve your contact list with optional filters.

curl https://api.monstersms.ai/v1/contacts?limit=50&page=1 \
  -H "X-API-Key: your_api_key_here"

Response:

{
  "contacts": [
    {
      "id": "cnt_xyz789",
      "first_name": "Jane",
      "last_name": "Smith",
      "mobile": "+61412345678",
      "email": "[email protected]",
      "status": "active",
      "tags": ["vip", "retail"],
      "created_at": "2026-02-15T09:00:00Z"
    }
  ],
  "total": 342,
  "page": 1,
  "limit": 50
}

Create a contact

POST /contacts

Add a new contact to your account.

curl -X POST https://api.monstersms.ai/v1/contacts \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "James",
    "last_name": "Wilson",
    "mobile": "+61423456789",
    "email": "[email protected]",
    "tags": ["leads", "plumbing"]
  }'

Response:

{
  "success": true,
  "contact": {
    "id": "cnt_abc123",
    "first_name": "James",
    "last_name": "Wilson",
    "mobile": "+61423456789",
    "status": "active",
    "created_at": "2026-03-12T09:00:00Z"
  }
}

Create a campaign

POST /campaigns

Create and schedule an SMS campaign to a list.

curl -X POST https://api.monstersms.ai/v1/campaigns \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "March Promo",
    "list_id": "lst_promo2026",
    "sender_id": "+61498765432",
    "message": "Hi {{first_name}}, our March sale is on now! 20% off all services this week. Book at example.com. Reply STOP to opt out.",
    "schedule_at": "2026-03-15T09:00:00+10:00"
  }'

Response:

{
  "success": true,
  "campaign_id": "cmp_march2026",
  "name": "March Promo",
  "status": "scheduled",
  "recipient_count": 487,
  "credits_required": 487,
  "scheduled_at": "2026-03-15T09:00:00+10:00"
}

Get conversations

GET /conversations

List conversations with optional status filter.

curl "https://api.monstersms.ai/v1/conversations?status=open&limit=20" \
  -H "X-API-Key: your_api_key_here"

Response:

{
  "conversations": [
    {
      "id": "conv_def456",
      "contact_id": "cnt_xyz789",
      "contact_name": "Jane Smith",
      "mobile": "+61412345678",
      "last_message": "What time does the sale end?",
      "last_message_at": "2026-03-12T08:45:00Z",
      "status": "open",
      "handled_by": "human"
    }
  ],
  "total": 12,
  "page": 1
}

Webhooks

Monster SMS can POST inbound messages to your server in real time. To configure a webhook:

1. Go to Sender IDs
2. Find a Sender ID with a number you purchased from us or imported from your Twilio account
3. Click the 3 dots menu and click Add Webhook URL

Inbound webhook payload example:

{
  "event": "message.received",
  "timestamp": "2026-03-12T09:15:00Z",
  "data": {
    "from": "+61412345678",
    "to": "+61498765432",
    "message": "Yes, I am interested. What are your prices?",
    "contact_id": "cnt_xyz789",
    "conversation_id": "conv_def456"
  }
}

Rate limits

• Send messages: 100 requests/minute
• Read endpoints: 300 requests/minute
• Campaigns: 10 creates/minute

Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

Error codes

Code	Meaning
400	Bad request — check your payload
401	Invalid or missing API key
402	Insufficient credits
404	Resource not found
429	Rate limit exceeded
500	Server error — contact support