openapi: 3.0.3
info:
  title: SMTP2GO Email Activity Webhooks API
  description: REST API for sending transactional emails and SMS, managing sender domains, SMTP users, API keys, templates, webhooks, suppressions, and accessing delivery reports and activity statistics. All requests use POST with JSON bodies. Authentication is via API key in request body or X-Smtp2go-Api-Key header.
  version: 3.0.4
  contact:
    name: SMTP2GO Support
    url: https://support.smtp2go.com/
  license:
    name: Proprietary
    url: https://www.smtp2go.com/terms/
servers:
- url: https://api.smtp2go.com/v3
  description: Global endpoint (auto-routes to nearest region)
- url: https://us-api.smtp2go.com/v3
  description: United States region
- url: https://eu-api.smtp2go.com/v3
  description: European Union region
- url: https://au-api.smtp2go.com/v3
  description: Oceania region
security:
- ApiKeyHeader: []
- ApiKeyBody: []
tags:
- name: Webhooks
  description: Webhook configuration
paths:
  /webhook/add:
    post:
      operationId: addWebhook
      summary: Add a new Webhook
      description: Add a new webhook with the given configuration
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
      responses:
        '200':
          description: Webhook added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /webhook/edit:
    post:
      operationId: editWebhook
      summary: Edit a specified Webhook
      description: Make changes to a specific webhook using its unique ID
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
  /webhook/delete:
    post:
      operationId: removeWebhook
      summary: Remove a specified Webhook
      description: Remove a specific webhook using its unique ID
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Webhook ID to remove
      responses:
        '200':
          description: Webhook removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /webhook/view:
    post:
      operationId: viewWebhooks
      summary: View Webhooks
      description: Returns information for configured webhooks
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: Optional webhook ID to retrieve specific webhook
      responses:
        '200':
          description: Webhooks list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
components:
  schemas:
    WebhookResponse:
      type: object
      properties:
        request_id:
          type: string
        data:
          type: object
          properties:
            url:
              type: string
            id:
              type: integer
            events:
              type: array
              items:
                type: string
            sms_events:
              type: array
              items:
                type: string
            headers:
              type: array
              items:
                type: object
            usernames:
              type: array
              items:
                type: string
            output_format:
              type: string
            auth_header_type:
              type: string
            auth_header_value:
              type: string
    StandardResponse:
      type: object
      properties:
        request_id:
          type: string
        data:
          type: object
          additionalProperties: true
    WebhookRequest:
      type: object
      required:
      - url
      properties:
        id:
          type: integer
          description: Webhook ID (required for edit/delete)
        url:
          type: string
          description: Webhook destination URL
          format: uri
        events:
          type: array
          description: Email events to receive
          items:
            type: string
            enum:
            - delivered
            - unsubscribe
            - spam
            - bounce
            - processed
            - reject
            - click
            - open
        sms_events:
          type: array
          description: SMS events to receive
          items:
            type: string
            enum:
            - delivered
            - failed
            - rejected
            - sending
            - submitted
        headers:
          type: array
          description: Custom headers to include in event data
          items:
            type: object
            properties:
              header:
                type: string
              value:
                type: string
        usernames:
          type: array
          description: Filter by usernames; all included if unspecified
          items:
            type: string
        output_format:
          type: string
          description: Data format for webhook payloads
          enum:
          - form
          - json
          default: form
        auth_header_type:
          type: string
          description: Authentication type for webhook
          enum:
          - bearer
          - basic
          - ''
          default: ''
        auth_header_value:
          type: string
          description: Authentication credentials or token
        subaccount_id:
          type: string
    ErrorResponse:
      type: object
      properties:
        request_id:
          type: string
        data:
          type: object
          properties:
            error:
              type: string
              description: Human-readable error message
            error_code:
              type: string
              description: Specific error code
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Smtp2go-Api-Key
      description: API key passed as an HTTP header
    ApiKeyBody:
      type: apiKey
      in: header
      name: api_key
      description: API key can also be included in the JSON request body as the "api_key" field
externalDocs:
  description: SMTP2GO Developer Documentation
  url: https://developers.smtp2go.com/docs/introduction-guide