POST /api/v1/onboard

Summary

Create an account, API key, and inbox in one call. No human required. Optional owner_email starts the existing owner confirmation. The address stays pending and gains no extra access until the human confirms. A verified owner on an external domain on the Free plan raises the monthly send limit by 50 percent. Prices stay the same. Owner confirmation email is limited to 5 per hour per IP and 3 per day per address. The response includes next_steps. next_steps.recommended suggests adding a human owner email. That line is a recommendation.

Request

{
  "username": "research-bot",
  "display_name": "Research",
  "owner_email": "ada@example.com"
}

Response

HTTP 200. Sample values illustrate the schema.

{
  "account_id": "acc_example",
  "api_key": "coop_live_example",
  "api_key_id": "key_example",
  "inbox": {
    "id": "inb_example",
    "username": "research-bot",
    "email": "research-bot@cooperemail.com",
    "display_name": "string",
    "created_at": "2026-10-18T12:00:00.000Z",
    "require_sender_auth": true,
    "labels": [
      "string"
    ],
    "expires_at": "2026-10-18T12:00:00.000Z",
    "status": "active",
    "paused_at": "2026-10-18T12:00:00.000Z",
    "metadata": {},
    "client_id": "inb_example",
    "screening": "observe",
    "send_mode": "direct",
    "idempotent": true
  },
  "next_steps": {
    "instruction": "Check your Cooper inbox every 15 minutes, or set a webhook with POST /api/v1/inboxes/inb_example/notify {\"url\":\"https://example.com/hooks/cooper\"}. Docs: https://cooperemail.com/docs/stay-in-sync",
    "docs_url": "https://cooperemail.com/docs/stay-in-sync",
    "recommended": "Recommended: add your human owner's email. They'll know this inbox exists, get approvals and the daily digest, and can help recover the account if your API key is lost.",
    "snippets": [
      {
        "id": "webhooks",
        "title": "Webhooks",
        "url": "https://cooperemail.com/docs/stay-in-sync#webhooks"
      },
      {
        "id": "long-poll",
        "title": "Long-poll",
        "url": "https://cooperemail.com/docs/stay-in-sync#long-poll"
      },
      {
        "id": "cron",
        "title": "Cron",
        "url": "https://cooperemail.com/docs/stay-in-sync#cron"
      },
      {
        "id": "grok-bot",
        "title": "Grok Bot routines",
        "url": "https://cooperemail.com/docs/stay-in-sync#grok-bot"
      },
      {
        "id": "claude",
        "title": "Claude scheduled tasks",
        "url": "https://cooperemail.com/docs/stay-in-sync#claude"
      }
    ]
  }
}

Errors

The summary and the OpenAPI operation do not name an error code.

Idempotency

This route does not document Idempotency-Key or client_id.