Authentication

The PostDog API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard under Settings > Developers.

Sends a WhatsApp message, Email, or Social post depending on the channel ID.

Example

curl -X POST https://api.postdog.app/v1/messages \
  -H "Authorization: Bearer pd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "ch_123456",
    "to": "+15550109999",
    "content": {
      "type": "text",
      "text": "Hello world!"
    }
  }'

Returns a paginated list of contacts in your account.

Example

curl https://api.postdog.app/v1/contacts?page=1&limit=50 \
  -H "Authorization: Bearer pd_live_..."

Creates a new contact in your account. Contacts can be reached via WhatsApp, email, or both.

Example

curl -X POST https://api.postdog.app/v1/contacts \
  -H "Authorization: Bearer pd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com",
    "tags": ["customer", "vip"]
  }'

Returns all message templates in your account, including their approval status.

Example

curl https://api.postdog.app/v1/templates \
  -H "Authorization: Bearer pd_live_..."

Submits a new message template for approval. Templates are reviewed by Meta within 24-48 hours.

Example

curl -X POST https://api.postdog.app/v1/templates \
  -H "Authorization: Bearer pd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "category": "UTILITY",
    "language": "en",
    "body": "Hi {{1}}, your order #{{2}} has been confirmed!"
  }'

Registers a URL to receive real-time event notifications. Your endpoint must return a 200 status within 5 seconds.

Example

curl -X POST https://api.postdog.app/v1/webhooks \
  -H "Authorization: Bearer pd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/postdog",
    "events": ["message.received", "message.delivered", "message.read"]
  }'

Available Webhook Events

Example Webhook Payload

{
  "event": "message.received",
  "timestamp": "2026-03-10T10:30:00Z",
  "data": {
    "messageId": "msg_abc123",
    "from": "+1234567890",
    "body": "Hello!",
    "type": "text"
  }
}

Rate Limits

API requests are rate-limited per plan. Exceeding the limit returns a 429 status code.

Plan	Requests/min	Burst
Starter	100	150
Pro	500	750
Business	2,000	3,000

Rate Limit Headers

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with a message field.

Code	Status	Description
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for this action
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded. Retry after X-RateLimit-Reset.
500	Internal Error	Server error. Retry with exponential backoff.

Error Response Example

{
  "error": {
    "code": 400,
    "message": "Invalid phone number format. Use E.164 format: +1234567890"
  }
}

SDKs & Libraries

Official client libraries for common languages. All SDKs handle authentication, rate limiting, and retries automatically.

Node.js

npm install @postdog/sdk

const PostDog = require('@postdog/sdk');
const client = new PostDog({ apiKey: 'pd_live_...' });

const message = await client.messages.send({
  channelId: 'ch_123456',
  to: '+15550109999',
  content: { type: 'text', text: 'Hello from Node.js!' }
});

Python

pip install postdog

from postdog import PostDog

client = PostDog(api_key="pd_live_...")

message = client.messages.send(
    channel_id="ch_123456",
    to="+15550109999",
    content={"type": "text", "text": "Hello from Python!"}
)

For full documentation, visit the Getting Started Guide or join our Developer Community.