mailcheer-com Suppression API

openapi: 3.2.0
info:
  title: Mailcheer Com Suppression API
  version: 1.0.0
  contact:
    name: Mailcheer
    url: https://mailcheer.com/docs/api
    email: contact@mailcheer.com
  license:
    name: Mailcheer Terms of Sale
    url: https://mailcheer.com/terms
  description: 'Operations tagged Suppression across 2 of this provider''s published API definitions: openapi.json, mailcheer-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://mailcheer.com
  description: 'Production. There is no separate test environment: try it on a workspace of your own, with an address of your own. Every path below already includes the `/api/v1` prefix.'
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Suppression
  description: Addresses that will receive nothing further.
paths:
  /api/v1/suppression:
    get:
      operationId: listSuppressions
      tags:
      - Suppression
      summary: The suppressed addresses
      description: 'Permission required: `subscribers:read`. The `scope` field distinguishes addresses suppressed for this workspace (`organization`) from those suppressed platform-wide (`platform`). `reason` says what the entry refuses: `unsubscribe` refuses campaigns, automations and sends carrying `unsubscribe_url`; `bounce`, `complaint` and `manual` refuse everything, individual emails included.'
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      - name: email
        in: query
        description: Check one specific address.
        schema:
          type: string
          format: email
      responses:
        '200':
          description: The requested page.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Liste'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/Suppression'
          headers:
            Mailcheer-Mode:
              $ref: '#/components/headers/Mailcheer-Mode'
            Mailcheer-Quota-Limit:
              $ref: '#/components/headers/Mailcheer-Quota-Limit'
            Mailcheer-Quota-Used:
              $ref: '#/components/headers/Mailcheer-Quota-Used'
            Mailcheer-Quota-Remaining:
              $ref: '#/components/headers/Mailcheer-Quota-Remaining'
            Mailcheer-Quota-Reset:
              $ref: '#/components/headers/Mailcheer-Quota-Reset'
        '401':
          $ref: '#/components/responses/NonAuthentifie'
        '403':
          $ref: '#/components/responses/Interdit'
    post:
      operationId: createSuppression
      tags:
      - Suppression
      summary: Suppress an address
      description: 'Permission required: `subscribers:write`. The matching subscriber, if there is one, moves to `unsubscribed` in the same operation. Without `reason`, the entry is `manual` and refuses everything, individual emails included; `unsubscribe` only refuses campaigns, automations and sends carrying `unsubscribe_url`. An entry already `bounce`, `complaint` or `manual` is never downgraded to `unsubscribe`.


        **No endpoint removes an address from this list**, and that is deliberate: it is the one action that suspends a sending capability. It is done by hand, in your Mailcheer workspace.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                reason:
                  type: string
                  enum:
                  - unsubscribe
                  - bounce
                  - complaint
                  - manual
                  default: manual
      responses:
        '201':
          description: Suppressed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suppression'
          headers:
            Mailcheer-Mode:
              $ref: '#/components/headers/Mailcheer-Mode'
            Mailcheer-Quota-Limit:
              $ref: '#/components/headers/Mailcheer-Quota-Limit'
            Mailcheer-Quota-Used:
              $ref: '#/components/headers/Mailcheer-Quota-Used'
            Mailcheer-Quota-Remaining:
              $ref: '#/components/headers/Mailcheer-Quota-Remaining'
            Mailcheer-Quota-Reset:
              $ref: '#/components/headers/Mailcheer-Quota-Reset'
        '401':
          $ref: '#/components/responses/NonAuthentifie'
        '403':
          $ref: '#/components/responses/Interdit'
        '422':
          $ref: '#/components/responses/Refuse'
    servers:
    - url: https://mailcheer.com
      description: 'Production. There is no separate test environment: try it on a workspace of your own, with an address of your own. Every path below already includes the `/api/v1` prefix.'
components:
  responses:
    Interdit:
      description: 'The key does not have the requested permission, or the workspace cannot send: `sending_blocked` (suspended, blocked or banned — nothing goes out, through any channel), `commitment_required` (the anti-spam commitment is not accepted), `reputation_blocked` (too many bounces or complaints).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erreur'
      headers:
        Mailcheer-Mode:
          $ref: '#/components/headers/Mailcheer-Mode'
        Mailcheer-Quota-Limit:
          $ref: '#/components/headers/Mailcheer-Quota-Limit'
        Mailcheer-Quota-Used:
          $ref: '#/components/headers/Mailcheer-Quota-Used'
        Mailcheer-Quota-Remaining:
          $ref: '#/components/headers/Mailcheer-Quota-Remaining'
        Mailcheer-Quota-Reset:
          $ref: '#/components/headers/Mailcheer-Quota-Reset'
    NonAuthentifie:
      description: Key missing, unknown or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erreur'
    Refuse:
      description: Malformed field, unverified domain, or recipient on the suppression list.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Erreur'
      headers:
        Mailcheer-Mode:
          $ref: '#/components/headers/Mailcheer-Mode'
        Mailcheer-Quota-Limit:
          $ref: '#/components/headers/Mailcheer-Quota-Limit'
        Mailcheer-Quota-Used:
          $ref: '#/components/headers/Mailcheer-Quota-Used'
        Mailcheer-Quota-Remaining:
          $ref: '#/components/headers/Mailcheer-Quota-Remaining'
        Mailcheer-Quota-Reset:
          $ref: '#/components/headers/Mailcheer-Quota-Reset'
  parameters:
    Limit:
      name: limit
      in: query
      description: Number of items per page, from 1 to 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      description: The `next_cursor` from the previous response.
      schema:
        type: string
  schemas:
    Liste:
      type: object
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            type: object
        has_more:
          type: boolean
          description: One more page after this one.
        next_cursor:
          type:
          - string
          - 'null'
          description: To pass back as `?cursor=` for the next page. `null` on the last page.
      description: 'The envelope of every list. To walk through it: as long as `has_more` is `true`, call the same address again with `?cursor=<next_cursor>`. The order is stable; a page returns at most `limit` items (50 by default, 100 at most).'
    Erreur:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - missing_api_key
              - invalid_api_key
              - revoked_api_key
              - insufficient_scope
              - rate_limit_exceeded
              - validation_error
              - unverified_from_domain
              - suppressed_recipient
              - undeliverable_recipient
              - quota_exceeded
              - free_plan_domain_used
              - key_quota_exceeded
              - reputation_blocked
              - sending_blocked
              - sending_paused
              - daily_quota_exceeded
              - commitment_required
              - not_found
              - conflict
              - idempotency_key_reused
              - idempotency_key_in_use
              - send_failed
              - internal_error
              description: Write your code against this field, never against `message`.
            message:
              type: string
              description: Written to be read by a human; may be rephrased without notice.
            details:
              type: object
              description: 'What you need to fix things without guessing: `issues` (the offending field and why) on a validation error, `verifiedDomains` on a refused domain, `available` on an unknown sender, and on `quota_exceeded` the numbers `plan`, `quota`, `sent`, `in_flight`, `remaining`, `requested`, `resets_at`, and on `free_plan_domain_used` the `domain`, its `root_domain`, the `period` and `resets_at`, and on `key_quota_exceeded` the key''s `key_id`, `key_name`, `limit`, `used`, `remaining`, `requested` and `resets_at`. A `429` and a `423` also give `retry_after_seconds` when the refusal comes from a daily limit or a safety review — the same value as `Retry-After`.'
              additionalProperties: true
        statusCode:
          type: integer
          examples:
          - 422
        message:
          type: string
          description: The same text as `error.message` — written for a human.
        name:
          type: string
          enum:
          - missing_api_key
          - invalid_api_key
          - revoked_api_key
          - insufficient_scope
          - rate_limit_exceeded
          - validation_error
          - unverified_from_domain
          - suppressed_recipient
          - undeliverable_recipient
          - quota_exceeded
          - free_plan_domain_used
          - key_quota_exceeded
          - reputation_blocked
          - sending_blocked
          - sending_paused
          - daily_quota_exceeded
          - commitment_required
          - not_found
          - conflict
          - idempotency_key_reused
          - idempotency_key_in_use
          - send_failed
          - internal_error
          description: The same value as `error.code`. Write your logic against it.
      description: Two readings of the same content. `error` is Mailcheer's shape, structured. `statusCode`, `message` and `name` follow Resend's shape, so that code written against that API shows a correct message without being rewritten. `name` carries the same value as `error.code`, and `message` the same text as `error.message`.
      examples:
      - error:
          code: unverified_from_domain
          message: 'Domain “example.com” is not verified in this workspace. Verified domains: yourdomain.com.'
          details:
            from: hello@example.com
            verifiedDomains:
            - yourdomain.com
        statusCode: 422
        message: 'Domain “example.com” is not verified in this workspace. Verified domains: yourdomain.com.'
        name: unverified_from_domain
    Suppression:
      type: object
      properties:
        object:
          type: string
          const: suppression
        email:
          type: string
        reason:
          type: string
          enum:
          - unsubscribe
          - bounce
          - complaint
          - manual
        scope:
          type: string
          enum:
          - organization
          - platform
        created_at:
          type: string
          format: date-time
  headers:
    Mailcheer-Quota-Remaining:
      description: What can still be sent this month, queue already deducted — never negative. `unlimited` on an unlimited plan.
      schema:
        type: string
        examples:
        - '565'
        - unlimited
    Mailcheer-Quota-Used:
      description: Emails sent this month **plus** those waiting in the queue (campaigns being sent, API sends in progress). The same count as `usage.emails_sent + usage.emails_in_flight` in `GET /api/v1/me`.
      schema:
        type: string
        examples:
        - '2435'
    Mailcheer-Mode:
      description: '`live`, or `test` when the call was made with a test key (`mch_test_…`): nothing is sent and the quota is not touched.'
      schema:
        type: string
        enum:
        - live
        - test
    Mailcheer-Quota-Reset:
      description: 'When the counter resets, in ISO 8601: the 1st of next month, 00:00 UTC.'
      schema:
        type: string
        format: date-time
        examples:
        - '2026-10-01T00:00:00.000Z'
    Mailcheer-Quota-Limit:
      description: Emails a month included in the workspace's plan, or `unlimited`.
      schema:
        type: string
        examples:
        - '3000'
        - unlimited
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An API key for the workspace, created under Settings → API in your Mailcheer workspace. Shape: `mch_live_…` — or `mch_test_…` for a test key, which checks everything and sends nothing (see Test mode).


        `Authorization: Bearer mch_live_…`


        The key carries permissions (`scopes`): every operation states which one it requires, and `GET /api/v1/me` states the ones yours carries. A key belongs to ONE workspace — there is no cross-workspace call.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'The same key, in a dedicated header. Strictly equivalent to the Bearer form: some enterprise clients and gateways do not let `Authorization` through. Do not send both.'
externalDocs:
  description: The written documentation, with per-language examples.
  url: https://mailcheer.com/docs/api
x-refined-from:
- openapi.json
- mailcheer-com-openapi.json