Skip to main content

API Introduction

The Zyphr API is a RESTful API that allows you to send notifications across multiple channels: email, push, SMS, and in-app inbox.

Base URL​

https://api.zyphr.dev/v1

For staging/testing:

https://api.staging.zyphr.dev/v1

Authentication​

All API requests require an API key passed in the X-API-Key header:

curl https://api.zyphr.dev/v1/emails \
  -H "X-API-Key: zy_live_your_api_key"

See Authentication for details on creating and managing API keys.

Request Format​

  • All requests must include Content-Type: application/json header
  • Request bodies must be valid JSON
  • Dates should be ISO 8601 format: 2024-01-15T10:30:00Z

Response Format​

All responses follow a consistent format:

Success Response​

{
  "data": {
    "id": "msg_abc123",
    "status": "queued",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

Error Response​

{
  "error": {
    "code": "validation_error",
    "message": "Invalid email address format",
    "details": {
      "field": "to",
      "reason": "must be a valid email address"
    }
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}

HTTP Status Codes​

CodeDescription
200Success
201Created
204No Content (successful deletion)
400Bad Request - Invalid input
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limited
500Internal Server Error

Rate Limiting​

API requests are rate limited based on your plan:

PlanRequests/second
Free10
Pro100
EnterpriseCustom

Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

When rate limited, you'll receive a 429 response:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please retry after 60 seconds.",
    "details": {
      "retry_after": 60
    }
  }
}

Idempotency​

For POST requests, you can include an Idempotency-Key header to prevent duplicate operations:

curl -X POST https://api.zyphr.dev/v1/emails \
  -H "X-API-Key: zy_live_your_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"to": "user@example.com", "subject": "Hello", "html": "<p>Hi!</p>"}'

If you retry with the same idempotency key within 24 hours, you'll receive the same response without creating a duplicate.

Pagination​

List endpoints support pagination:

curl "https://api.zyphr.dev/v1/emails?page=2&per_page=25" \
  -H "X-API-Key: zy_live_your_key"

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}

Filtering​

Many endpoints support filtering via query parameters:

# Filter emails by status
curl "https://api.zyphr.dev/v1/emails?status=delivered" \
  -H "X-API-Key: zy_live_your_key"

# Filter by date range
curl "https://api.zyphr.dev/v1/emails?created_after=2024-01-01&created_before=2024-01-31" \
  -H "X-API-Key: zy_live_your_key"

Versioning​

The API is versioned via the URL path (/v1/). We maintain backwards compatibility within a major version.

Breaking changes will be introduced in new versions (/v2/) with migration guides.

SDKs​

Official SDKs are available for common languages:

OpenAPI Specification​

The complete OpenAPI 3.0 specification is available at:

https://api.zyphr.dev/v1/openapi.yaml

You can import this into tools like Postman or use it to generate client libraries.

Postman Collection​

A pre-built Postman collection with all endpoints is available. See the Postman Collection guide for import instructions.

Support​