AhaSend Suppressions API

openapi: 3.2.0
info:
  title: AhaSend API v2 Suppressions API
  description: The AhaSend API v2 allows you to send transactional emails, manage domains, webhooks, routes, API keys, and view statistics.
  version: 2.0.0
  contact:
    email: support@ahasend.com
  license:
    name: MIT
    identifier: MIT
servers:
- url: https://api.ahasend.com
  description: Production server
security:
- BearerAuth: []
tags:
- name: Suppressions
  description: Manage email suppressions
paths:
  /v2/accounts/{account_id}/suppressions:
    get:
      summary: Get Suppressions
      description: 'Returns a list of suppressions for the account


        **Query Parameters:**

        - `domain`: Filter by domain (optional)

        - `email`: Filter by email (optional)

        - `from_time`: Filter suppressions created after this time (RFC3339 format, optional)

        - `to_time`: Filter suppressions created before this time (RFC3339 format, optional)

        - `limit`: Maximum number of items to return (1-100, default: 100)

        - `after`: Pagination cursor for the next page

        - `before`: Pagination cursor for the previous page'
      operationId: getSuppressions
      tags:
      - Suppressions
      parameters:
      - name: account_id
        in: path
        required: true
        description: Account ID
        schema:
          type: string
          format: uuid
      - name: domain
        in: query
        description: Filter by domain
        schema:
          type: string
      - name: email
        in: query
        description: Email address
        schema:
          type: string
          format: email
      - name: from_time
        in: query
        description: Filter suppressions created after this time (RFC3339 format)
        schema:
          type: string
          format: date-time
      - name: to_time
        in: query
        description: Filter suppressions created before this time (RFC3339 format)
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        description: Maximum number of items to return (1-100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
      - name: after
        in: query
        description: Pagination cursor for the next page. Provide the value provided in `next_cursor` from the response.
        schema:
          type: string
      - name: before
        in: query
        description: Pagination cursor for the previous page. Provide the value provided in `previous_cursor` from the response.
        schema:
          type: string
      security:
      - BearerAuth:
        - suppressions:read
      x-code-samples:
      - lang: go
        label: AhaSend Go SDK
        source: "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"log\"\n\n  \"github.com/AhaSend/ahasend-go/api\"\n  \"github.com/AhaSend/ahasend-go/models/requests\"\n  \"github.com/google/uuid\"\n)\n\nfunc main() {\n  // Create API client with authentication\n  client := api.NewAPIClient(\n    api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n  )\n\n  accountID := uuid.New()\n\n  // Create context for the API call\n  ctx := context.Background()\n\n  // Call the ping endpoint\n  response, httpResp, err := client.SuppressionsAPI.GetSuppressions(\n    ctx,\n    accountID,\n    requests.GetSuppressionsParams{},\n    nil,\n  )\n  if err != nil {\n    log.Fatalf(\"Error getting suppressions: %v\", err)\n  }\n\n  // Check response\n  if httpResp.StatusCode == 200 {\n    fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n    if response != nil {\n      fmt.Printf(\"Found %d suppressions\\n\", len(response.Data))\n    }\n  } else {\n    fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n  }\n}\n"
      - lang: javascript
        label: Node.js 22+ (AhaSend SDK)
        source: 'import { AhaSendClient } from "@ahasend/sdk";


          const client = AhaSendClient.fromEnv();

          const page = await client.suppressions.list({ limit: 20 });

          console.log("Suppressions listed.", { count: page.data.length });

          '
      responses:
        '200':
          description: List of suppressions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSuppressionsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Domain not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create Suppression
      description: 'Creates a new suppression for an email address


        **Validation Requirements:**

        - `email` must be a valid email address

        - `expires_at` must be in RFC3339 format

        - `domain` is optional - if not provided, applies to all account domains'
      operationId: createSuppression
      tags:
      - Suppressions
      parameters:
      - name: account_id
        in: path
        required: true
        description: Account ID
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/IdempotencyKey'
      security:
      - BearerAuth:
        - suppressions:write
      x-code-samples:
      - lang: go
        label: AhaSend Go SDK
        source: "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"log\"\n  \"time\"\n\n  \"github.com/AhaSend/ahasend-go\"\n  \"github.com/AhaSend/ahasend-go/api\"\n  \"github.com/AhaSend/ahasend-go/models/requests\"\n  \"github.com/google/uuid\"\n)\n\nfunc main() {\n  // Create API client with authentication\n  client := api.NewAPIClient(\n    api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n  )\n\n  accountID := uuid.New()\n\n  // Create context for the API call\n  ctx := context.Background()\n\n  // Call the ping endpoint\n  response, httpResp, err := client.SuppressionsAPI.CreateSuppression(\n    ctx,\n    accountID,\n    requests.CreateSuppressionRequest{\n      Email:     \"test@example.com\",\n      Reason:    ahasend.String(\"Inbox full\"),\n      ExpiresAt: time.Now().Add(time.Hour * 24 * 30),\n    },\n  )\n  if err != nil {\n    log.Fatalf(\"Error creating suppression: %v\", err)\n  }\n\n  // Check response\n  if httpResp.StatusCode == 201 {\n    fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n    if response != nil {\n      fmt.Printf(\"Created suppression: %#v\\n\", response)\n    }\n  } else {\n    fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n  }\n}\n"
      - lang: javascript
        label: Node.js 22+ (AhaSend SDK)
        source: "import { AhaSendClient } from \"@ahasend/sdk\";\n\nconst client = AhaSendClient.fromEnv();\nconst result = await client.suppressions.create(\n  {\n    email: \"recipient@example.net\",\n    reason: \"User requested removal\",\n    expires_at: \"2030-01-01T00:00:00Z\",\n  },\n  { idempotencyKey: \"sdk-sample-create-suppression\" },\n);\nconsole.log(\"Suppression created.\", { count: result.data.length });\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSuppressionRequest'
      responses:
        '201':
          description: Suppression created successfully
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSuppressionResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: 'Either the suppression already exists or the idempotency-key

            execution is in progress. The in-progress case is identified only

            by `Idempotent-Replayed: false` plus a positive integer

            `Retry-After`. A new duplicate-suppression response has neither

            header; a stored replay of that response has

            `Idempotent-Replayed: true`. The message is not a stable

            discriminator.

            '
          headers:
            Idempotent-Replayed:
              description: '`false` with a positive `Retry-After` means an execution is in

                progress. `true` means a stored duplicate-suppression 409 was

                replayed. Absent means a fresh duplicate-suppression conflict.

                '
              schema:
                type: string
                enum:
                - 'true'
                - 'false'
            Retry-After:
              $ref: '#/components/headers/IdempotencyRetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/IdempotencyPayloadMismatch'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete Suppression
      description: 'Deletes suppressions for an email address


        **Query Parameters:**

        - `email`: Required email address to delete from suppression list

        - `domain`: Optional domain filter to delete suppressions for specific domain only'
      operationId: deleteSuppression
      tags:
      - Suppressions
      parameters:
      - name: account_id
        in: path
        required: true
        description: Account ID
        schema:
          type: string
          format: uuid
      - name: email
        in: query
        required: true
        description: Email address
        schema:
          type: string
          format: email
      - name: domain
        in: query
        description: Optional domain filter
        schema:
          type: string
      security:
      - BearerAuth:
        - suppressions:delete
      x-code-samples:
      - lang: go
        label: AhaSend Go SDK
        source: "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"log\"\n\n  \"github.com/AhaSend/ahasend-go\"\n  \"github.com/AhaSend/ahasend-go/api\"\n  \"github.com/google/uuid\"\n)\n\nfunc main() {\n  // Create API client with authentication\n  client := api.NewAPIClient(\n    api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n  )\n\n  accountID := uuid.New()\n\n  // Create context for the API call\n  ctx := context.Background()\n\n  // Call the ping endpoint\n  response, httpResp, err := client.SuppressionsAPI.DeleteSuppression(\n    ctx,\n    accountID,\n    \"info@bigco.com\",\n    ahasend.String(\"notifications.example.com\"),\n  )\n  if err != nil {\n    log.Fatalf(\"Error deleting suppression: %v\", err)\n  }\n\n  // Check response\n  if httpResp.StatusCode == 200 {\n    fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n    if response != nil {\n      fmt.Printf(\"Deleted the suppression, response: %s\\n\", len(response.Message))\n    }\n  } else {\n    fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n  }\n}\n"
      - lang: javascript
        label: Node.js 22+ (AhaSend SDK)
        source: 'import { AhaSendClient } from "@ahasend/sdk";


          const client = AhaSendClient.fromEnv();

          const result = await client.suppressions.delete({ email: "recipient@example.net" });

          console.log("Suppression deleted.", { message: result.message });

          '
      responses:
        '200':
          description: Suppression deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Suppression not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v2/accounts/{account_id}/suppressions/all:
    delete:
      summary: Delete All Suppressions
      description: 'Deletes all suppressions for the account


        **Query Parameters:**

        - `domain`: Optional domain filter to delete suppressions for specific domain only'
      operationId: deleteAllSuppressions
      tags:
      - Suppressions
      parameters:
      - name: account_id
        in: path
        required: true
        description: Account ID
        schema:
          type: string
          format: uuid
      - name: domain
        in: query
        description: Optional domain filter
        schema:
          type: string
      security:
      - BearerAuth:
        - suppressions:wipe
      x-code-samples:
      - lang: go
        label: AhaSend Go SDK
        source: "package main\n\nimport (\n  \"context\"\n  \"fmt\"\n  \"log\"\n\n  \"github.com/AhaSend/ahasend-go/api\"\n  \"github.com/google/uuid\"\n)\n\nfunc main() {\n  // Create API client with authentication\n  client := api.NewAPIClient(\n    api.WithAPIKey(\"aha-sk-your-64-character-key\"),\n  )\n\n  accountID := uuid.New()\n\n  // Create context for the API call\n  ctx := context.Background()\n\n  // Call the ping endpoint\n  response, httpResp, err := client.SuppressionsAPI.DeleteAllSuppressions(\n    ctx,\n    accountID,\n    nil,\n  )\n  if err != nil {\n    log.Fatalf(\"Error deleting all suppressions: %v\", err)\n  }\n\n  // Check response\n  if httpResp.StatusCode == 200 {\n    fmt.Printf(\"✅ Status: %d\\n\", httpResp.StatusCode)\n    if response != nil {\n      fmt.Printf(\"Deleted all suppressions: %#v\\n\", response)\n    }\n  } else {\n    fmt.Printf(\"❌ Unexpected status code: %d\\n\", httpResp.StatusCode)\n  }\n}\n"
      - lang: javascript
        label: Node.js 22+ (AhaSend SDK)
        source: 'import { AhaSendClient } from "@ahasend/sdk";


          const client = AhaSendClient.fromEnv();

          const result = await client.suppressions.wipe({ domain: "example.com" });

          console.log("Domain suppressions deleted.", { message: result.message });

          '
      responses:
        '200':
          description: All suppressions deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Domain not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  headers:
    IdempotencyRetryAfter:
      description: 'Positive whole number of seconds after which the in-progress execution

        lease may be retried with the same key and unchanged request.

        '
      schema:
        type: integer
        minimum: 1
    IdempotentReplayed:
      description: 'Indicates that this response is a stored replay of a previous identical request.

        When this header is absent, the response is not a stored replay. Ordinary fresh

        responses do not send `false`; that value is reserved for an in-progress 409.

        '
      schema:
        type: string
        enum:
        - 'true'
  schemas:
    PaginatedSuppressionsResponse:
      type: object
      required:
      - object
      - data
      - pagination
      properties:
        object:
          type: string
          enum:
          - list
          description: Object type identifier
        data:
          type: array
          items:
            $ref: '#/components/schemas/Suppression'
          description: Array of suppressions
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    CreateSuppressionResponse:
      type: object
      required:
      - object
      - data
      properties:
        object:
          type: string
          enum:
          - list
          description: Object type identifier
        data:
          type: array
          items:
            $ref: '#/components/schemas/Suppression'
          description: Array of suppressions
    ErrorResponse:
      type: object
      description: 'Human-readable API error. The server currently sends no stable machine

        error code. In particular, clients must not parse `message` to

        distinguish IP-allow-list, scope, ownership, plan, self-lockout,

        suppression-duplicate, or other errors that share an HTTP status.

        '
      additionalProperties: false
      required:
      - message
      properties:
        message:
          type: string
          description: Error description
      example:
        message: Error message
    PaginationInfo:
      type: object
      required:
      - has_more
      properties:
        has_more:
          type: boolean
          description: Whether more items exist after the last item of this page
        next_cursor:
          type: string
          description: Pass as `after` to fetch the next page
        previous_cursor:
          type: string
          description: Pass as `before` to fetch the previous page; absent on a `before` page when the start of the list has been reached
      example:
        has_more: true
        next_cursor: eyJpZCI6MTIzNH0=
    SuccessResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Success message
      example:
        message: Operation completed successfully
    Suppression:
      type: object
      properties:
        object:
          type: string
          enum:
          - suppression
          description: Object type identifier
        id:
          type: string
          format: uuid
          description: Unique identifier for the suppression
        created_at:
          type: string
          format: date-time
          description: When the suppression was created
        email:
          type: string
          format: email
          description: Suppressed email address
        domain:
          type: string
          description: Domain for which the email is suppressed
        reason:
          type: string
          description: Reason for suppression
        expires_at:
          type: string
          format: date-time
          description: When the suppression expires
      required:
      - object
      - id
      - created_at
      - email
      - domain
      - reason
      - expires_at
    CreateSuppressionRequest:
      type: object
      required:
      - email
      - expires_at
      properties:
        email:
          type: string
          format: email
          description: Email address to suppress
        domain:
          type: string
          format: hostname
          description: Domain for which to suppress the email
        reason:
          type: string
          maxLength: 255
          description: Reason for suppression
        expires_at:
          type: string
          format: date-time
          description: When the suppression expires (RFC3339 format)
      example:
        email: user@example.com
        domain: example.com
        reason: User requested removal
        expires_at: '2024-12-25T10:30:00Z'
  responses:
    IdempotencyPayloadMismatch:
      description: 'Idempotency key was already used with a different HTTP method, resolved

        request path, or request body. This response includes neither

        `Idempotent-Replayed` nor `Retry-After`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: idempotency key was already used with a different request payload
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Optional idempotency key for safe request retries. Must be a unique string for each logical request.

        An identical request with a completed stored outcome returns the original status and body. An in-progress

        execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again.

        Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time `secret_key`,

        so successful encrypted replay responses for those operations expire after 5 minutes.

        '
      schema:
        type: string
        maxLength: 255
      example: user-12345-create-domain-20240101
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: aha-sk-64-CHARACTER-RANDOM-STRING
      description: 'API key for authentication. Non-empty Security Requirement values are

        AhaSend API-key roles. Roles listed within one requirement object are

        jointly required; separate requirement objects are alternatives.

        '