Cooper Email Webhooks API

Webhooks operations for the Cooper Email API.

GitHub OpenAPI

Operations 9

GET /api/v1/webhooks List webhooks #
POST /api/v1/webhooks Register a webhook (message.received, message.held, message.sent… #
GET /api/v1/webhooks/{id} Get a webhook #
PATCH /api/v1/webhooks/{id} Update a webhook #
DELETE /api/v1/webhooks/{id} Delete a webhook #
POST /api/v1/webhooks/{id}/rotate-secret Rotate a webhook signing secret #
POST /api/v1/webhooks/{id}/test Send a webhook.test event and wait #
GET /api/v1/webhooks/{id}/deliveries List webhook deliveries #
POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver Redeliver a stored webhook payload #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/cooperemail-com:cooperemail-com-webhooks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cooperemail-com-webhooks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Cooperemail Com Webhooks 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 Webhooks 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: Webhooks
  description: Webhooks operations for the Cooper Email API.
paths:
  /api/v1/webhooks:
    get:
      operationId: listWebhooks
      tags:
      - Webhooks
      summary: List webhooks
      description: Includes inbox_id, inbox_ids, enabled, consecutive_failures, disabled_at, disabled_reason, header names with values redacted, last_delivery_status, last_delivery_at, previous_secret_expires_at, and previous_secret_active. The current secret is truncated. The previous secret is never returned. previous_secret_expires_at is present only while the 24 hour overlap is still in the future.
      responses:
        '200':
          description: Success.
        '400':
          description: Client error. The JSON body uses error.code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createWebhook
      tags:
      - Webhooks
      summary: Register a webhook (message.received, message.held, message.sent…
      description: Cooper signs the raw JSON body with HMAC-SHA256. x-cooper-signature is sha256= of the raw body. x-cooper-timestamp is unix seconds. x-cooper-signature-v2 is v1=. Reject timestamps more than 5 minutes off and dedupe on x-cooper-delivery. For 24 hours after a secret rotation both signature headers are comma-separated, current secret first. Split on the comma and accept the delivery when any segment matches. Optional headers (max 5, Authorization or X-*) are stored encrypted, redacted on read, and sent on every delivery. inbox_id is stored into inbox_ids. inbox_ids accepts at most 10 ids (400 too_many_inboxes). An empty inbox_ids matches every inbox. The same client_id returns HTTP 200 and the original hook with the secret redacted. 5xx and network errors are retried. A final non-2xx increments consecutive_failures. At 20 the hook is disabled with disabled_reason consecutive_failures. Any 2xx resets the counter.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                events:
                  type: array
                  items:
                    type: string
                    enum:
                    - message.received
                    - message.held
                    - message.sent
                    - message.blocked
                    - message.bounced
                    - message.complained
                    - task.received
                    - owner.reply
                    - chat.message
                    - domain.verified
                    - draft.created
                    - draft.approved
                    - draft.rejected
                    - draft.sent
                    - account.sending_paused
                    - account.sending_resumed
                    - thread.assigned
                    - thread.unassigned
                    - thread.folder_updated
                    - question.answered
                    - question.expired
                    - rule.matched
                secret:
                  type: string
                inbox_id:
                  type:
                  - string
                  - 'null'
                  description: Fire only for this inbox. Stored into inbox_ids. Omit to receive every inbox on the account.
                inbox_ids:
                  type: array
                  items:
                    type: string
                  description: At most 10 inbox ids. Empty matches every inbox. More than 10 is 400 too_many_inboxes.
                client_id:
                  type: string
                  description: Idempotency key. The same value returns the original hook with HTTP 200 and a redacted secret.
                headers:
                  type: object
                  description: At most 5 headers. Names must be Authorization or X-* (not x-cooper-signature, x-cooper-signature-v2, x-cooper-timestamp, x-cooper-event, or x-cooper-delivery). Values max 1024 characters. GET returns the names with values redacted.
                  additionalProperties:
                    type: string
              required:
              - url
      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/webhooks/{id}:
    get:
      operationId: getWebhook
      tags:
      - Webhooks
      summary: Get a webhook
      description: Secret is redacted the same way as the list. previous_secret_expires_at and previous_secret_active describe a 24 hour overlap after rotation. The previous secret is never returned. Another account's id is 404 webhook_not_found.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Webhook
        '404':
          description: webhook_not_found
    patch:
      operationId: updateWebhook
      tags:
      - Webhooks
      summary: Update a webhook
      description: Partial update. Pass inbox_id null or inbox_ids [] to clear the inbox filter. Pass enabled true to re-enable and reset consecutive_failures. Pass enabled false to disable. Pass headers null to remove custom headers. A secret that differs from the current secret moves the current secret to the previous secret for 24 hours, the same overlap as POST /rotate-secret. The response still redacts the secret. Another account's id is 404 webhook_not_found.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                events:
                  type: array
                  items:
                    type: string
                    enum:
                    - message.received
                    - message.held
                    - message.sent
                    - message.blocked
                    - message.bounced
                    - message.complained
                    - task.received
                    - owner.reply
                    - chat.message
                    - domain.verified
                    - draft.created
                    - draft.approved
                    - draft.rejected
                    - draft.sent
                    - account.sending_paused
                    - account.sending_resumed
                    - thread.assigned
                    - thread.unassigned
                    - thread.folder_updated
                    - question.answered
                    - question.expired
                    - rule.matched
                secret:
                  type: string
                  description: When this differs from the current secret, the current secret stays valid for 24 hours and deliveries are signed with both.
                inbox_id:
                  type:
                  - string
                  - 'null'
                inbox_ids:
                  type: array
                  items:
                    type: string
                  description: At most 10 inbox ids. Empty matches every inbox.
                enabled:
                  type: boolean
                  description: true re-enables and resets consecutive_failures. false disables deliveries.
                headers:
                  type:
                  - object
                  - 'null'
                  additionalProperties:
                    type: string
      responses:
        '200':
          description: Success.
        '400':
          description: Client error. The JSON body uses error.code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteWebhook
      tags:
      - Webhooks
      summary: Delete a webhook
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
        '404':
          description: webhook_not_found
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/webhooks/{id}/rotate-secret:
    post:
      operationId: rotateWebhookSecret
      tags:
      - Webhooks
      summary: Rotate a webhook signing secret
      description: Mints a new whsec_ secret and returns it once, the same as create. The previous secret stays valid for 24 hours. The response includes previous_secret_expires_at and previous_secret_active true, and does not return the previous secret. Rotating again replaces the previous secret and resets the window. A hook with no secret just stores the new one. Same permission as PATCH (webhook_write). During the window x-cooper-signature is sha256=,sha256= and x-cooper-signature-v2 is v1=,v1=, current secret first. Accept the delivery when any comma-separated segment matches. Another account's id is 404 webhook_not_found.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Webhook with the new secret revealed once
        '404':
          description: webhook_not_found
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/webhooks/{id}/test:
    post:
      operationId: testWebhook
      tags:
      - Webhooks
      summary: Send a webhook.test event and wait
      description: Body is {type:"webhook.test", data:{webhook_id}}. Returns {delivery:{id, status, response_status, attempts, event_id}}. A disabled hook is 409 webhook_disabled. Another account's id is 404 webhook_not_found.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Delivery result
        '404':
          description: webhook_not_found
        '409':
          description: webhook_disabled
    servers:
    - url: https://cooperemail.com
      description: This deployment
  /api/v1/webhooks/{id}/deliveries:
    get:
      operationId: listWebhookDeliveries
      tags:
      - Webhooks
      summary: List webhook deliveries
      description: Newest first. limit is 1 to 100 (default 50). status is delivered or failed. Payload is capped at 256 KB. Rows older than 7 days are deleted by the daily cron. 400 invalid_limit, 400 invalid_status, 404 webhook_not_found.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: status
        in: query
        schema:
          type: string
          enum:
          - delivered
          - failed
      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/webhooks/{id}/deliveries/{deliveryId}/redeliver:
    post:
      operationId: redeliverWebhook
      tags:
      - Webhooks
      summary: Redeliver a stored webhook payload
      description: Same event id, new timestamp and signature. Sends the stored payload (at most 256 KB). Returns {delivery:{id, status, response_status, attempts, event_id}}. 404 delivery_not_found, 404 webhook_not_found, 409 webhook_disabled.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: deliveryId
        in: path
        required: true
        schema:
          type: string
      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
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
    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
    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
    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