API v1

Warmbox API

Pull mailbox reputation and domain health into your own dashboards, and pause or resume warmup from your outreach tooling. JSON over HTTPS, one API key per integration.

Included in the Agency plan and during your free trial. Machine-readable spec: OpenAPI 3.1.

Authentication

Create a key under Settings → API keys (owners and admins). It's shown once — store it as a secret. Send it as a bearer token; every request is scoped to the key's organization.

curl https://warmup.aiekip.com/api/v1/mailboxes \
  -H "Authorization: Bearer ew_live_…"

Successful responses wrap their payload in data:

{
  "data": [
    {
      "id": "cm…",
      "email": "sales@yourdomain.com",
      "status": "WARMING",
      "warmupEnabled": true,
      "reputationScore": 84,
      "deliverabilityRate": 0.93,
      "rampDay": 12,
      "rampTotalDays": 19
    }
  ]
}

Endpoints

GET/api/v1/organization

Your organization

Plan, mailbox quota, and how many mailboxes count against it.

GET/api/v1/mailboxes

List mailboxes

Every mailbox with its status, reputation score, deliverability rate and ramp progress.

GET/api/v1/mailboxes/{id}

Get a mailbox

One mailbox plus its warmup settings: ramp, daily maximum, reply rate, sending window and timezone.

PATCH/api/v1/mailboxes/{id}

Pause or resume warmup

Body {"warmupEnabled": false} pauses; true resumes where the ramp left off. Resuming past your plan's quota returns 409.

curl https://warmup.aiekip.com/api/v1/mailboxes/{id} \
  -H "Authorization: Bearer ew_live_…" \
  -X PATCH -H "Content-Type: application/json" -d '{"warmupEnabled": false}'

GET/api/v1/mailboxes/{id}/reputation?days=30

Reputation history

Daily snapshots (1–90 days): score, sent, received, inbox rate, spam rate and reply rate.

GET/api/v1/mailboxes/{id}/domain-health

Domain health

SPF, DKIM, DMARC and MX checks plus DNS blacklist status for the mailbox's sending domain.

Rate limits & errors

Each key may make 120 requests per minute; responses carry X-RateLimit-Limit and X-RateLimit-Remaining. Errors look like { "error": { "code": "not_found", "message": "Mailbox not found" } }.

Status	Code	Meaning
400	invalid_request	The body or query didn't validate.
401	unauthorized	Missing, malformed, unknown or revoked API key.
403	plan_required	Your plan doesn't include API access.
404	not_found	No such resource in your organization.
409	quota_exceeded	Resuming would exceed your plan's mailbox quota.
429	rate_limited	More than 120 requests in a minute; honour Retry-After.

Need something the API doesn't do yet? Outbound webhooks are coming soon. See plans.