Prerequisites

Account setup completed in Chatmaid dashboard
At least one connected sender phone in dashboard
API key generated in dashboard with message scopes

First Message Flow

Store your API key in your server secrets.
Fetch available sender phone IDs from standard API endpoints.
Send a message with API key auth.

Current base URL: https://developers-api.chatmaid.net.

curl -X GET https://developers-api.chatmaid.net/v1/phone-numbers \
  -H "Authorization: Bearer sk_test_xxx"

const response = await fetch("https://developers-api.chatmaid.net/v1/phone-numbers", {
  headers: { Authorization: "Bearer " + process.env.CHATMAID_API_KEY },
});

const phones = await response.json();

import os
import requests

response = requests.get(
    "https://developers-api.chatmaid.net/v1/phone-numbers",
    headers={"Authorization": f"Bearer {os.environ['CHATMAID_API_KEY']}"},
)

phones = response.json()

Send your first message.

curl -X POST https://developers-api.chatmaid.net/v1/messages/send \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fromPhoneId": "+15551234567",
    "to": "+15557654321",
    "content": "Hello from Chatmaid"
  }'

const response = await fetch("https://developers-api.chatmaid.net/v1/messages/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    fromPhoneId: "+15551234567",
    to: "+15557654321",
    content: "Hello from Chatmaid"
  })
});

const payload = await response.json();

import requests

response = requests.post(
    "https://developers-api.chatmaid.net/v1/messages/send",
    headers={
        "Authorization": "Bearer sk_test_xxx",
        "Content-Type": "application/json",
    },
    json={
        "fromPhoneId": "+15551234567",
        "to": "+15557654321",
        "content": "Hello from Chatmaid",
    },
)

payload = response.json()

{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "content": "Hello from Chatmaid",
    "mediaUrls": [],
    "status": "sent",
    "createdAt": "2026-02-06T14:18:33.000Z",
    "sentAt": "2026-02-06T14:18:33.120Z",
    "failedAt": null,
    "errorCode": null,
    "errorMessage": null
  }
}

Poll status until terminal state.

curl -X GET https://developers-api.chatmaid.net/v1/messages/msg_abc123def456 \
  -H "Authorization: Bearer sk_test_xxx"

const response = await fetch(
  "https://developers-api.chatmaid.net/v1/messages/msg_abc123def456",
  { headers: { "Authorization": "Bearer sk_test_xxx" } }
);

const payload = await response.json();

import requests

response = requests.get(
    "https://developers-api.chatmaid.net/v1/messages/msg_abc123def456",
    headers={"Authorization": "Bearer sk_test_xxx"},
)

payload = response.json()

{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "status": "sent",
    "sentAt": "2026-02-06T14:18:34.000Z",
    "failedAt": null,
    "errorCode": null,
    "errorMessage": null
  }
}

Retry Safety (Optional)

If your app retries failed HTTP requests aggressively, include an idempotencyKey generated from your own operation ID to avoid duplicate sends.

Production Checklist

Keep the same base URL and switch to sk_live_* credentials in production.
Use sk_live_* keys only in production systems.
Configure webhook destination in dashboard and verify signatures in your receiver.
Monitor failed delivery events and implement retries in your system.

Getting Started

Prerequisites

First Message Flow

Production Checklist

On this page