openapi: 3.0.3
info:
  title: SMTP2GO Email Activity Stats 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: Stats
  description: Email delivery statistics and reports
paths:
  /stats/email_summary:
    post:
      operationId: emailSummary
      summary: Email summary
      description: Retrieve a combination of email_bounces, email_cycle, email_spam, and email_unsubs calls in one report
      tags:
      - Stats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Return statistics for a specific SMTP user
      responses:
        '200':
          description: Email summary statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailSummaryResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /stats/email_bounces:
    post:
      operationId: emailBounces
      summary: Email bounces
      description: Retrieve a summary of bounces and rejects for the last 30 days
      tags:
      - Stats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
      responses:
        '200':
          description: Bounce statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /stats/email_cycle:
    post:
      operationId: emailCycle
      summary: Email cycle
      description: Retrieve a summary of your account activity including billing cycle dates and email counts
      tags:
      - Stats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
      responses:
        '200':
          description: Email cycle data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /stats/email_history:
    post:
      operationId: emailHistory
      summary: Email history
      description: Retrieve a summary of activity from a specified date range per sender, SMTP username, domain or subaccount
      tags:
      - Stats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                  description: ISO-8601 start datetime (defaults to last 30 days)
                end_date:
                  type: string
                  description: ISO-8601 end datetime
                username:
                  type: string
      responses:
        '200':
          description: Email history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /stats/email_spam:
    post:
      operationId: emailSpam
      summary: Email spam
      description: Retrieve a summary of spam complaints and rejects for the last 30 days
      tags:
      - Stats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Spam statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /stats/email_unsubscribes:
    post:
      operationId: emailUnsubscribes
      summary: Email unsubscribes
      description: Retrieve a summary of unsubscribes and rejects for the last 30 days
      tags:
      - Stats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Unsubscribe statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
components:
  schemas:
    StandardResponse:
      type: object
      properties:
        request_id:
          type: string
        data:
          type: object
          additionalProperties: true
    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
    EmailSummaryResponse:
      type: object
      properties:
        request_id:
          type: string
        data:
          type: object
          properties:
            spam_emails:
              type: integer
            cycle_start:
              type: string
            cycle_end:
              type: string
            cycle_used:
              type: integer
            cycle_remaining:
              type: integer
            cycle_max:
              type: integer
            email_count:
              type: integer
            softbounces:
              type: integer
            hardbounces:
              type: integer
            bounce_percent:
              type: string
            spam_rejects:
              type: integer
              deprecated: true
            spam_percent:
              type: string
            unsubscribes:
              type: integer
            unsubscribe_percent:
              type: string
            opens:
              type: integer
            clicks:
              type: integer
            rejects:
              type: integer
            bounce_rejects:
              type: integer
              deprecated: true
  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