# POST /api/v1/event-consumers

Auth: Bearer

HTML: https://cooperemail.com/docs/reference/event-consumers

## Summary

Create or resume a durable event consumer. client_id is 1–64 characters of letters, digits, and . _ : -. The same client_id returns HTTP 200 and does not move the cursor. A new consumer is HTTP 201. start is now (default), oldest, or an ISO-8601 timestamp, and applies only when the consumer is created. types is an optional subset of the webhook event types. inbox_id is an inbox id or address. A different types list or inbox_id is HTTP 409 consumer_conflict. Filters are not edited in place. Delete the consumer to change them. An account can store at most 50 consumers (HTTP 409 consumer_limit). That cap is a technical limit, not a plan limit. Requires message_read, the same permission as GET /api/v1/events. Create, list, poll, commit, reset, and delete all use message_read. A full-access key and an OAuth token can call them. An inbox-scoped key is pinned to its inbox. A different inbox_id is HTTP 404 inbox_not_found. HTTP 400 invalid_client_id, invalid_event_type, or invalid_start. GET /api/v1/event-consumers lists them. Guide: /docs/event-consumers.

## Request

```json
{
  "client_id": "nightly-digest",
  "types": [
    "message.received"
  ],
  "start": "oldest"
}
```

## Response

HTTP 200. Sample values illustrate the schema.

```json
{
  "object": "event_consumer",
  "id": "inb_example",
  "client_id": "inb_example",
  "cursor": "string",
  "created_at": "2026-10-18T12:00:00.000Z",
  "updated_at": "2026-10-18T12:00:00.000Z"
}
```

## Errors

- HTTP 409 consumer_conflict
- HTTP 409 consumer_limit
- HTTP 404 inbox_not_found
- HTTP 400 invalid_client_id
- HTTP 403 permission_denied

The live `message` is the sentence for that code. Branch on `code`.

```json
{
  "error": {
    "type": "conflict",
    "code": "consumer_conflict",
    "docs_url": "https://cooperemail.com/docs#consumer_conflict"
  }
}
```

## Idempotency

client_id makes this write idempotent. Sending the same client_id again returns the original object instead of creating a duplicate.