---
title: "Getting Started"
description: "End-to-end quickstart from account creation to first message."
---

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

## 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

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

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

<Tabs items={['cURL', 'Node.js', 'Python']}>
<Tab value="cURL">
```bash
curl -X GET https://developers-api.chatmaid.net/v1/phone-numbers \
  -H "Authorization: Bearer sk_test_xxx"
```
</Tab>
<Tab value="Node.js">
```ts
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();
```
</Tab>
<Tab value="Python">
```python
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()
```
</Tab>
</Tabs>

4. Send your first message.

<Tabs items={['cURL', 'Node.js', 'Python']}>
<Tab value="cURL">
```bash
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"
  }'
```
</Tab>
<Tab value="Node.js">
```ts
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();
```
</Tab>
<Tab value="Python">
```python
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()
```
</Tab>
</Tabs>

```json
{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "isGroup": false,
    "groupId": null,
    "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
  }
}
```

5. Poll status until terminal state.

<Tabs items={['cURL', 'Node.js', 'Python']}>
<Tab value="cURL">
```bash
curl -X GET https://developers-api.chatmaid.net/v1/messages/msg_abc123def456 \
  -H "Authorization: Bearer sk_test_xxx"
```
</Tab>
<Tab value="Node.js">
```ts
const response = await fetch(
  "https://developers-api.chatmaid.net/v1/messages/msg_abc123def456",
  { headers: { "Authorization": "Bearer sk_test_xxx" } }
);

const payload = await response.json();
```
</Tab>
<Tab value="Python">
```python
import requests

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

payload = response.json()
```
</Tab>
</Tabs>

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

<Callout type="info" title="Retry Safety (Optional)">
  If your app retries failed HTTP requests aggressively, include an `idempotencyKey` generated from your own operation ID to avoid duplicate sends.
</Callout>

## 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.