API Documentation

The Cheddar Inbox API lets you programmatically manage email health checks. Send domain health check requests, monitor progress, and control campaigns through a simple REST API.

Base URLhttps://cheddarinbox.com/api/v1

Authentication

All requests require a Bearer token in the Authorization header:

header

Authorization: Bearer ci_xxxxxxxxxxxxx

Get your API key from the Dashboard → Settings → API Keys. Each key is shown only once at creation time, so store it securely.

Endpoints

POST/api/v1/warmup

Create a new email health check request. Provide your domain and SMTP credentials. Daily volume is determined by your plan tier (Starter: 50/day, Growth: 250/day, Scale: 1,000/day). The system ramps up automatically.

Request Body

json

{
  "domain": "mydomain.com",
  "from_email": "hello@mydomain.com",
  "from_name": "My Brand",
  "smtp_host": "smtp.sendgrid.net",
  "smtp_port": 587,
  "smtp_user": "apikey",
  "smtp_pass": "SG.xxx",
  "duration_days": 30
}

Response 201

json

{
  "request": {
    "id": 1,
    "domain": "mydomain.com",
    "status": "active",
    "daily_volume": 250,
    "package": "growth",
    "duration_days": 30,
    "current_daily_volume": 5,
    "started_at": "2026-03-20T00:00:00.000Z"
  }
}

Example

curl

curl -X POST https://cheddarinbox.com/api/v1/warmup \
  -H "Authorization: Bearer ci_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "mydomain.com",
    "from_email": "hello@mydomain.com",
    "smtp_host": "smtp.sendgrid.net",
    "smtp_port": 587,
    "smtp_user": "apikey",
    "smtp_pass": "SG.xxx",
    "duration_days": 30
  }'

GET/api/v1/warmup

List all health check requests associated with your API key. Returns requests ordered by most recent first.

Response 200

json

{
  "requests": [
    {
      "id": 1,
      "domain": "mydomain.com",
      "daily_volume": 250,
      "package": "growth",
      "duration_days": 30,
      "status": "active",
      "days_elapsed": 5,
      "total_sends": 42,
      "total_replies": 18,
      "total_opens": 35,
      "current_daily_volume": 7,
      "started_at": "2026-03-15T...",
      "completed_at": null
    }
  ]
}

Example

curl

curl https://cheddarinbox.com/api/v1/warmup \
  -H "Authorization: Bearer ci_xxxxx"

GET/api/v1/warmup/{id}

Get detailed status for a single health check request, including a breakdown of tasks by action type and status.

Response 200

json

{
  "request": {
    "id": 1,
    "domain": "mydomain.com",
    "status": "active",
    "daily_volume": 250,
    "package": "growth",
    "duration_days": 30,
    "days_elapsed": 5,
    "total_sends": 42,
    "total_replies": 18,
    "current_daily_volume": 7
  },
  "taskBreakdown": [
    { "action_type": "send", "status": "completed", "count": "42" },
    { "action_type": "reply", "status": "completed", "count": "18" },
    { "action_type": "send", "status": "pending", "count": "3" }
  ]
}

Example

curl

curl https://cheddarinbox.com/api/v1/warmup/1 \
  -H "Authorization: Bearer ci_xxxxx"

PUT/api/v1/warmup/{id}

Control a health check request by changing its status. Valid statuses: active, paused, cancelled. Cancelling a request sets the completed_at timestamp.

Request Body

json

{
  "status": "paused"
}

Response 200

json

{
  "request": {
    "id": 1,
    "domain": "mydomain.com",
    "status": "paused",
    "daily_volume": 250,
    "package": "growth",
    "duration_days": 30,
    "days_elapsed": 5
  }
}

Example

curl

curl -X PUT https://cheddarinbox.com/api/v1/warmup/1 \
  -H "Authorization: Bearer ci_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

GET/api/v1/health

Get current network health metrics. This endpoint is public and does not require authentication.

Response 200

json

{
  "status": "operational",
  "network": {
    "active_nodes": "127",
    "total_nodes": "184",
    "avg_score": "72.4",
    "sends_today": "4821",
    "active_requests": "31"
  },
  "timestamp": "2026-03-20T12:00:00.000Z"
}

Example

curl

curl https://cheddarinbox.com/api/v1/health

Code Examples

Quick-start examples for creating a health check request in your language of choice.

bash

curl -X POST https://cheddarinbox.com/api/v1/warmup \
  -H "Authorization: Bearer ci_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "duration_days": 30}'

Rate Limits

API keys are rate-limited on a per-day basis. Exceeding your limit returns a 429 status code.

Endpoint	Limit
General API requests	10,000 / day per key
Health check creation (POST /warmup)	100 / day
Health endpoint (GET /health)	Unlimited (no auth)

Errors

The API uses standard HTTP status codes. Errors return a JSON body with an error field.

Code	Meaning
`400`	Invalid request body
`401`	Invalid or missing API key
`404`	Resource not found
`429`	Rate limit exceeded
`502`	Upstream service error

json

{
  "error": "Invalid or rate-limited API key"
}

Ready to get started?

Create your API key and start monitoring domains in minutes.

Get Started