openapi: 3.0.3
info:
  title: SMTP2GO Email Activity SMS 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: SMS
  description: Send and receive SMS messages
paths:
  /sms/send:
    post:
      operationId: sendSms
      summary: Send SMS
      description: Send an SMS message to one or more numbers, up to a maximum of 100 numbers
      tags:
      - SMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendSmsRequest'
      responses:
        '200':
          description: SMS sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendSmsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /sms/summary:
    post:
      operationId: smsSummary
      summary: SMS summary
      description: Retrieve a summary of SMS messages within a certain time range
      tags:
      - SMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                  description: ISO-8601 start datetime
                end_date:
                  type: string
                  description: ISO-8601 end datetime
      responses:
        '200':
          description: SMS summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /sms/view:
    post:
      operationId: viewSentSms
      summary: View sent SMS
      description: View sent SMS messages
      tags:
      - SMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                end_date:
                  type: string
      responses:
        '200':
          description: Sent SMS messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
  /sms/inbox:
    post:
      operationId: viewReceivedSms
      summary: View received SMS
      description: View received SMS messages
      tags:
      - SMS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date:
                  type: string
                end_date:
                  type: string
      responses:
        '200':
          description: Received SMS messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
components:
  schemas:
    StandardResponse:
      type: object
      properties:
        request_id:
          type: string
        data:
          type: object
          additionalProperties: true
    SendSmsResponse:
      type: object
      properties:
        request_id:
          type: string
        data:
          type: object
          properties:
            total_sent:
              type: integer
            statuses:
              type: object
              properties:
                queued:
                  type: integer
            messages:
              type: array
              items:
                type: object
                properties:
                  destination:
                    type: string
                  message_id:
                    type: string
                  status:
                    type: string
                    enum:
                    - processing
                    - enroute
                    - queued
                    - submitted
                    - processed
                    - delivered
                    - held
                    - expired
                    - cancelled
                    - failed
                    - rejected
    SendSmsRequest:
      type: object
      required:
      - destination
      - content
      properties:
        destination:
          type: array
          description: Array of SMS numbers (max 100), with country code
          items:
            type: string
          example:
          - '+12025550959'
        content:
          type: string
          description: SMS message content. Messages over 160 characters will be sent as multiple units.
        sender:
          type: string
          description: Sender number in E.164 format. Leave empty for default.
    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