API Reference

The Canary API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard Settings.

# Include your API key in the Authorization header
curl https://api.canarymsg.dev/v1/sms \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx"

Canary uses webhooks to notify your application when events happen in your account. Webhooks are particularly useful for asynchronous events like when a message is delivered or when a recipient opens an email.

Webhook Events

Webhook Payload

{
  "id": "evt_1234567890",
  "type": "message.delivered",
  "created": 1704067200,
  "data": {
    "message_id": "msg_abc123",
    "to": "+15551234567",
    "status": "delivered",
    "delivered_at": "2024-01-01T12:00:00Z"
  }
}

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

The Canary API implements rate limiting to ensure fair usage and protect against abuse. Rate limits are applied per API key.

Rate limit information is included in the response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067260

Canary uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the 2xx range indicate success, codes in the 4xx range indicate an error with the information provided, and codes in the 5xx range indicate an error with Canary's servers.

Error Response Format

{
  "error": {
    "code": "invalid_phone_number",
    "message": "The phone number provided is not valid",
    "param": "to",
    "doc_url": "https://canarymsg.dev/docs/errors#invalid_phone_number"
  }
}