API Reference

Overview

The Cyber Pigeon API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

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

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

curl https://api.cyberpigeon.email/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY"

Errors

Cyber Pigeon 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 that failed given the information provided. Codes in the 5xx range indicate an error with Cyber Pigeon's servers.

Rate Limits

The Cyber Pigeon API has rate limits to ensure fair usage and maintain service quality for all users.

Rate Limit Tiers

• Free: 100 requests per hour
• Starter: 1,000 requests per hour
• Pro: 10,000 requests per hour
• Enterprise: Custom limits

Rate Limit Headers

All API responses include headers that provide information about your current rate limit status:

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

API Endpoints

The Cyber Pigeon API provides the following endpoints:

Request Format

All API requests should be made over HTTPS. Requests made over plain HTTP will fail. API requests without authentication will also fail.

Content Type

All POST requests should use application/json content type and include the data as JSON in the request body.

curl -X POST https://api.cyberpigeon.email/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "noreply@yourapp.com",
    "subject": "Welcome!",
    "html": "<h1>Hello World!</h1>"
  }'

Response Format

All API responses are returned as JSON. Successful requests will return a 2xx status code along with the requested data. Failed requests will return a 4xx or 5xx status code along with an error object.

Success Response

{
  "id": "msg_1234567890",
  "status": "sent",
  "created_at": "2024-01-15T10:30:00Z",
  "to": "user@example.com",
  "from": "noreply@yourapp.com",
  "subject": "Welcome!"
}

Error Response

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "Missing required parameter: 'to'",
    "param": "to"
  }
}

Official SDKs

We provide official SDKs for popular programming languages to make integration easier:

Testing

Cyber Pigeon provides a test mode that allows you to test your integration without sending real emails or being charged.

Test Email Addresses

When in test mode, you can use these special email addresses to simulate different scenarios:

• success@cyberpigeon.test - Always succeeds
• bounce@cyberpigeon.test - Always bounces
• spam@cyberpigeon.test - Always marked as spam
• reject@cyberpigeon.test - Always rejected