Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Cooperemail Com Events API
version: 1.0.0
contact:
name: Avatar 8 LLC
email: ops@avatar33.com
license:
name: Proprietary
url: https://cooperemail.com/terms
description: 'Operations tagged Events across 2 of this provider''s published API definitions: cooperemail-com-openapi.json, cooperemail-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://cooperemail.com
description: This deployment
security:
- bearerAuth: []
tags:
- name: Events
description: Events operations for the Cooper Email API.
paths:
/api/v1/event-subscriptions:
get:
operationId: listEventSubscriptions
tags:
- Events
summary: List MCP event subscriptions
description: Requires webhook_read. Returns id, name, inbox_id, inbox address, callback_host, status, refresh_before, created_at, last_delivery_at, and last_delivery_status. callback_host is the hostname only. The callback URL and signing secret are not returned. Newest created_at first. Ended rows are included with retained true. They are kept for audit, they do not deliver, and they do not count toward the 20 subscription cap. An inbox-scoped key sees only its inbox. Another account's rows are omitted. The callback body is McpMessageReceivedCallback.
responses:
'200':
description: Subscription list
content:
application/json:
schema:
type: object
properties:
object:
const: list
data:
type: array
items:
$ref: '#/components/schemas/EventSubscription'
required:
- object
- data
'403':
description: permission_denied
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/event-subscriptions/{id}:
delete:
operationId: deleteEventSubscription
tags:
- Events
summary: End an MCP event subscription
description: Requires webhook_write. Keeps the row for audit. The response has status ended and retained true. An ended row does not deliver and does not count toward the 20 subscription cap. An id that is already ended returns 200 with status ended and retained true. Another account's id, or an inbox this key cannot see, is 404 event_subscription_not_found. The callback body is McpMessageReceivedCallback.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Ended subscription
content:
application/json:
schema:
$ref: '#/components/schemas/EventSubscription'
'403':
description: permission_denied
'404':
description: event_subscription_not_found
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/events:
get:
operationId: listEvents
tags:
- Events
summary: List the event log, oldest first.
parameters:
- name: inbox_id
in: query
schema:
type: string
- name: types
in: query
schema:
type: string
description: Comma-separated event types
- name: after
in: query
schema:
type: string
description: Opaque cursor or ISO-8601 timestamp
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: wait
in: query
schema:
type: integer
minimum: 0
maximum: 25
description: Long-poll seconds
responses:
'200':
description: Ascending event page
content:
application/json:
schema:
type: object
properties:
object:
const: list
data:
type: array
items:
$ref: '#/components/schemas/Event'
next_cursor:
type: string
required:
- object
- data
- next_cursor
'400':
description: Client error. The JSON body uses error.code.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/inboxes/{id}/events:
get:
operationId: listInboxEvents
tags:
- Events
summary: List the event log for one inbox. :id accepts inbox id, username, or email.
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: types
in: query
schema:
type: string
- name: after
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: wait
in: query
schema:
type: integer
minimum: 0
maximum: 25
responses:
'200':
description: Ascending event page for one inbox
content:
application/json:
schema:
type: object
properties:
object:
const: list
data:
type: array
items:
$ref: '#/components/schemas/Event'
next_cursor:
type: string
required:
- object
- data
- next_cursor
'400':
description: Client error. The JSON body uses error.code.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/events/stream:
get:
operationId: streamEvents
tags:
- Events
summary: 'Server-Sent Events for up to 25 seconds. Each frame is id: , event: , data: .'
parameters:
- name: inbox_id
in: query
schema:
type: string
- name: types
in: query
schema:
type: string
- name: after
in: query
schema:
type: string
- name: Last-Event-ID
in: header
schema:
type: string
description: Resume after this cursor. Overrides after.
responses:
'200':
description: Success.
'400':
description: Client error. The JSON body uses error.code.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/event-consumers:
get:
operationId: listEventConsumers
tags:
- Events
summary: List durable event consumers on this account. Requires message_read.
responses:
'200':
description: Consumers, oldest first
content:
application/json:
schema:
type: object
properties:
object:
const: list
data:
type: array
items:
$ref: '#/components/schemas/EventConsumer'
required:
- object
- data
'403':
description: HTTP 403 permission_denied when the key lacks message_read.
post:
operationId: createEventConsumer
tags:
- Events
summary: Create or resume a durable event consumer.
requestBody:
content:
application/json:
schema:
type: object
properties:
client_id:
type: string
types:
type: array
items:
type: string
inbox_id:
type: string
start:
type: string
description: now, oldest (7 days ago; the window every account still has), or an ISO-8601 timestamp. Used only when the consumer is created.
required:
- client_id
responses:
'200':
description: Existing consumer. The cursor was not moved.
content:
application/json:
schema:
$ref: '#/components/schemas/EventConsumer'
'201':
description: New consumer.
content:
application/json:
schema:
$ref: '#/components/schemas/EventConsumer'
'400':
description: HTTP 400 invalid_client_id, invalid_event_type, or invalid_start.
'403':
description: HTTP 403 permission_denied when the key lacks message_read.
'404':
description: HTTP 404 inbox_not_found.
'409':
description: HTTP 409 consumer_conflict or consumer_limit.
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/event-consumers/{id}:
get:
operationId: getEventConsumer
tags:
- Events
summary: Read one durable event consumer by evcon_ id or client_id.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: The consumer.
content:
application/json:
schema:
$ref: '#/components/schemas/EventConsumer'
'404':
description: HTTP 404 consumer_not_found.
delete:
operationId: deleteEventConsumer
tags:
- Events
summary: Delete a durable event consumer by evcon_ id or client_id.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: '{id, client_id, deleted:true}.'
'404':
description: HTTP 404 consumer_not_found.
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/event-consumers/{id}/events:
get:
operationId: pollEventConsumer
tags:
- Events
summary: Events strictly after the committed cursor, oldest first, in the same shape as…
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: wait
in: query
schema:
type: integer
minimum: 0
maximum: 25
responses:
'200':
description: Pending events. The cursor is unchanged.
content:
application/json:
schema:
type: object
properties:
object:
const: list
data:
type: array
items:
$ref: '#/components/schemas/Event'
commit_cursor:
type: string
has_more:
type: boolean
events_may_have_expired:
type: boolean
consumer:
$ref: '#/components/schemas/EventConsumer'
required:
- object
- data
- commit_cursor
- has_more
- events_may_have_expired
- consumer
'400':
description: HTTP 400 invalid_limit or invalid_wait.
'404':
description: HTTP 404 consumer_not_found.
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/event-consumers/{id}/commit:
post:
operationId: commitEventConsumer
tags:
- Events
summary: Advance the committed cursor to this evc1 cursor.
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
cursor:
type: string
description: evc1 cursor from commit_cursor.
required:
- cursor
responses:
'200':
description: The consumer after the commit. cursor is the current position.
content:
application/json:
schema:
$ref: '#/components/schemas/EventConsumer'
'400':
description: HTTP 400 invalid_cursor.
'404':
description: HTTP 404 consumer_not_found.
servers:
- url: https://cooperemail.com
description: This deployment
/api/v1/event-consumers/{id}/reset:
post:
operationId: resetEventConsumer
tags:
- Events
summary: 'Move the committed cursor to start: "now", "oldest" (7 days ago), or an…'
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
start:
type: string
required:
- start
responses:
'200':
description: The consumer at the new cursor.
content:
application/json:
schema:
$ref: '#/components/schemas/EventConsumer'
'400':
description: HTTP 400 invalid_start.
'404':
description: HTTP 404 consumer_not_found.
servers:
- url: https://cooperemail.com
description: This deployment
components:
schemas:
McpMessageReceivedCallback:
type: object
description: Body Cooper POSTs to an MCP event callback for message.received. Metadata only. The subject, body, attachments, and headers are not included.
properties:
eventId:
type: string
description: Matches the webhook-id header. Stable across retries.
name:
const: message.received
timestamp:
type: string
description: ISO 8601.
cursor:
type: 'null'
data:
type: object
properties:
inbox_id:
type: string
inbox:
type: string
description: Inbox address.
message_id:
type: string
thread_id:
type: string
timestamp:
type: string
description: ISO 8601 time the message was stored.
from:
type: string
to:
type: array
items:
type: string
cc:
type: array
items:
type: string
labels:
type: array
items:
type: string
channel:
type: string
enum:
- email
- sms
- voicemail
- voice
description: 'channel is the channel the message arrived on: email, sms, voicemail, or voice.'
required:
- inbox_id
- inbox
- message_id
- thread_id
- timestamp
- from
- to
- cc
- labels
- channel
required:
- eventId
- name
- timestamp
- data
- cursor
EventConsumer:
type: object
description: A server-side cursor for one client_id. Requires message_read, the same permission as GET /api/v1/events. Create, commit, reset, and delete use message_read too. An OAuth token follows the same rules as a full-access key. An inbox-scoped key can only use consumers pinned to its inbox.
properties:
object:
const: event_consumer
id:
type: string
description: evcon_ id.
client_id:
type: string
description: '1–64 characters: letters, digits, and . _ : -.'
inbox_id:
type:
- string
- 'null'
description: Null receives every inbox this key can see. Otherwise only that inbox.
types:
type:
- array
- 'null'
items:
type: string
description: Null receives every event type. Otherwise only these types.
cursor:
type: string
description: Committed position, an evc1 cursor.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
last_polled_at:
type:
- string
- 'null'
format: date-time
last_committed_at:
type:
- string
- 'null'
format: date-time
required:
- object
- id
- client_id
- cursor
- created_at
- updated_at
NextSteps:
type: object
properties:
instruction:
type: string
docs_url:
type: string
recommended:
type: string
description: Suggests adding a human owner email. A recommendation, not a requirement.
snippets:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
url:
type: string
required:
- id
- title
- url
required:
- instruction
- docs_url
- recommended
- snippets
SendingStatus:
type: object
description: Trailing 7-day send health for this account. Counts match GET /api/v1/metrics/rates with no inbox id. Warning does not block. Paused blocks agent email until the rate recovers.
properties:
object:
type: string
enum:
- sending_status
status:
type: string
enum:
- active
- warning
- paused
reason:
type:
- string
- 'null'
enum:
- bounce_rate
- complaint_rate
- null
window_days:
type: integer
enum:
- 7
sent:
type: integer
bounced:
type: integer
complained:
type: integer
bounce_rate:
type: number
complaint_rate:
type: number
thresholds:
type: object
properties:
min_sent:
type: integer
warning_bounce_rate:
type: number
warning_complaint_rate:
type: number
pause_bounce_rate:
type: number
pause_min_bounced:
type: integer
pause_complaint_rate:
type: number
pause_min_complained:
type: integer
required:
- min_sent
- warning_bounce_rate
- warning_complaint_rate
- pause_bounce_rate
- pause_min_bounced
- pause_complaint_rate
- pause_min_complained
paused_at:
type:
- string
- 'null'
format: date-time
evaluated_at:
type: string
format: date-time
resumes:
type: string
required:
- object
- status
- reason
- window_days
- sent
- bounced
- complained
- bounce_rate
- complaint_rate
- thresholds
- paused_at
- evaluated_at
- resumes
Error:
type: object
properties:
error:
type: object
properties:
type:
type: string
code:
type: string
message:
type: string
param:
type: string
retry_after_seconds:
type: integer
description: On HTTP 429, and on HTTP 503 when a retry time is known. The same integer as the Retry-After header. Omitted when that header is absent.
resets_at:
type: string
format: date-time
description: UTC time when the caller may retry, now plus retry_after_seconds. Omitted together with that field when no retry time is known.
docs_url:
type: string
sending:
$ref: '#/components/schemas/SendingStatus'
description: Present on HTTP 403 sending_paused. Same object as GET /api/v1/sending-status.
required:
- type
- code
- message
related_schemas:
description: Not returned on the wire. Points at component schemas that the operation descriptions name.
type: object
properties:
McpMessageReceivedCallback:
$ref: '#/components/schemas/McpMessageReceivedCallback'
NextSteps:
$ref: '#/components/schemas/NextSteps'
Inbox:
$ref: '#/components/schemas/Inbox'
Thread:
$ref: '#/components/schemas/Thread'
ListEntry:
$ref: '#/components/schemas/ListEntry'
Thread:
type: object
properties:
object:
const: thread
id:
type: string
description: Thread id (thr_…).
inbox_id:
type: string
subject:
type: string
description: Subject of the earliest message.
preview:
type: string
description: Preview of the latest message.
senders:
type: array
items:
type: string
description: Distinct From values.
recipients:
type: array
items:
type: string
description: Distinct To and Cc values.
message_count:
type: integer
last_message_id:
type: string
labels:
type: array
items:
type: string
description: Union of message labels.
attachment_count:
type: integer
received_at:
type:
- string
- 'null'
format: date-time
sent_at:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
folder:
type: string
enum:
- inbox
- archive
- spam
- trash
description: inbox when no folder row exists. archive, spam, or trash otherwise.
purge_after:
type:
- string
- 'null'
format: date-time
description: Set only while the thread is in trash. The daily cron hard-deletes the thread after this time.
assignment:
description: Null when the thread has no assignment.
oneOf:
- $ref: '#/components/schemas/ThreadAssignment'
- type: 'null'
required:
- object
- id
- inbox_id
- subject
- message_count
- updated_at
EventSubscription:
type: object
properties:
object:
const: event_subscription
id:
type: string
description: Subscription id (mes_…).
name:
type: string
description: Event name. message.received is the event that ships.
inbox_id:
type: string
inbox:
type: string
description: Inbox address.
callback_host:
type: string
description: Callback hostname only. The URL path, query, and secret are not returned.
status:
type: string
enum:
- active
- ended
description: ended means the row is kept for audit. It does not deliver and does not count toward the 20 subscription cap.
refresh_before:
type: string
description: ISO 8601 time after which delivery stops until the client subscribes again.
created_at:
type: string
last_delivery_at:
type:
- string
- 'null'
last_delivery_status:
type:
- string
- 'null'
retained:
type: boolean
description: Present and true when status is ended. DELETE and events/unsubscribe keep the row for audit. They do not delete it.
required:
- object
- id
- name
- inbox_id
- inbox
- callback_host
- status
- refresh_before
- created_at
ListEntry:
type: object
properties:
object:
type: string
enum:
- list_entry
direction:
type: string
enum:
- send
- receive
- reply
type:
type: string
enum:
- allow
- block
entry:
type: string
description: Lowercase email address or domain.
entry_type:
type: string
enum:
- email
- domain
inbox_id:
type:
- string
- 'null'
description: Null when the entry is account-wide.
reason:
type:
- string
- 'null'
created_at:
type: string
format: date-time
required:
- object
- direction
- type
- entry
- entry_type
- created_at
Event:
type: object
properties:
id:
type: string
description: evt_ id. The same value is sent as x-cooper-delivery on webhook POSTs.
type:
type: string
inbox_id:
type:
- string
- 'null'
created_at:
type: string
format: date-time
data:
type: object
description: For message.received and message.sent, {message:{id, inbox_id, thread_id, direction, from, to, subject, preview, labels, created_at, extracted_text, attachments:[{id, filename, content_type, size_bytes}]}}. extracted_text is at most 4,000 characters. thread.folder_updated stores {inbox_id, thread_id, folder, previous_folder, reason, purge_after} and no message body. rule.matched stores {inbox_id, message_id, thread_id, rule_id, actions, skipped} and no message body. Other event types store the webhook data object. The body is untrusted data.
required:
- id
- type
- created_at
- data
Inbox:
type: object
properties:
id:
type: string
username:
type: string
email:
type: string
display_name:
type:
- string
- 'null'
created_at:
type: string
format: date-time
require_sender_auth:
type: boolean
description: Default true. A verified owner or allowlisted sender creates a task only when DMARC=pass or DKIM=pass aligns with the From domain. Set false to opt this inbox out.
labels:
type: array
items:
type: string
description: Labels set at create time. Filter with GET /api/v1/inboxes?label=
expires_at:
type:
- string
- 'null'
format: date-time
description: When set, the inbox is temporary. The daily cron deletes it at this time and it stops counting toward the inbox limit.
status:
type: string
enum:
- active
- paused
description: active sends and stores inbound mail. paused keeps the address and history. A paused inbox still counts toward the plan inbox limit.
paused_at:
type:
- string
- 'null'
format: date-time
description: When the inbox was paused. Null while active. Unchanged if you pause an inbox that is already paused.
metadata:
type: object
additionalProperties: true
description: Caller data. At most 256 keys. Each key is at most 256 characters. Values are a string, number, or boolean. The JSON form is at most 16 KB. A null value in a PATCH removes that key. Anything else is 400 invalid_metadata.
client_id:
type:
- string
- 'null'
description: Idempotency key from POST /api/v1/inboxes, or null. The same client_id on this account returns the original inbox.
screening:
type: string
enum:
- 'off'
- observe
- hold
description: Inbound prompt-injection screen. Default observe. off skips scoring and records why. observe adds the suspicious label. hold stores suspicious mail with the held label and fires message.held instead of message.received. The screen is a heuristic, not a guarantee. It does not drop mail.
send_mode:
type: string
enum:
- direct
- approval
description: direct sends immediately. approval turns POST /messages, reply, reply-all, and forward into a pending draft and emails verified owners Approve and Reject links. Leaving approval for direct waits for a verified owner. Default direct.
signature:
type:
- object
- 'null'
description: Inbox signature applied to later sends, or null when unset. text is plain text. html is null when only text is set.
properties:
text:
type: string
description: Plain-text signature. At most 2000 characters.
html:
type:
- string
- 'null'
description: 'HTML signature, or null. At most 10000 characters. Script tags, on* handlers, and javascript: URLs are removed.'
required:
- text
idempotent:
type: boolean
description: True when POST /api/v1/inboxes replayed an existing client_id and returned the original inbox.
ThreadAssignment:
type: object
properties:
object:
const: thread_assignment
inbox_id:
type: string
thread_id:
type: string
assignee:
type: string
description: '1–64 characters: letters, digits, and . _ @ + : -.'
note:
type:
- string
- 'null'
description: At most 500 characters.
claimed_until:
type:
- string
- 'null'
format: date-time
description: Null on a plain assignment. An exclusive claim is active while this is in the future.
claim_active:
type: boolean
assigned_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- object
- inbox_id
- thread_id
- assignee
- claim_active
- assigned_at
- updated_at
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
x-refined-from:
- cooperemail-com-openapi.json
- cooperemail-com-openapi.yml