openapi: 3.2.0
info:
  title: SMTP2GO EMAILS API
  version: 3.0.4
  description: The SMTP2GO v3 REST API for sending transactional email and SMS, managing sender domains and single sender emails, SMTP users, API keys, IP allow lists and IP auth, templates, webhooks, suppressions, subaccounts, dedicated IPs, email archive, activity search and delivery statistics. Every operation is a POST (with a PATCH variant on two paths) carrying a JSON body; authentication is an API key supplied in the X-Smtp2go-Api-Key header or as an api_key field in the request body.
  contact:
    name: SMTP2GO Support
    url: https://support.smtp2go.com/
  termsOfService: https://www.smtp2go.com/terms/
  x-harvest:
    source: https://developers.smtp2go.com/mcp
    method: MCP tools/call get-endpoint, one call per path+method, assembled verbatim
    harvested: '2026-08-13'
    server_info:
      name: SMTP2GO-API-Docs
      version: 3.0.4
    note: SMTP2GO does not publish a single fetchable OpenAPI URL; the ReadMe registry path answers 429 to non-browser clients. The provider's own remote MCP server returns the authoritative OpenAPI 3.1.0 fragment for each endpoint anonymously, and those 73 fragments are merged here without modification.
servers:
- url: https://api.smtp2go.com/v3
  description: Regionless
- url: https://us-api.smtp2go.com/v3
  description: US Region
- url: https://eu-api.smtp2go.com/v3
  description: EU Region
- url: https://au-api.smtp2go.com/v3
  description: AU Region
security:
- sec0: []
tags:
- name: EMAILS
  description: Send standard, MIME and batch email; manage scheduled sends
paths:
  /email/batch:
    post:
      tags:
      - EMAILS
      summary: Send a batch of emails
      description: Send a batch of emails
      operationId: send-email-batch
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - emails
              example:
                emails:
                - to:
                  - Jane Jones <jane@example.com>
                  sender: John Smith <john@example.com>
                  subject: 'My Test Email #1'
                  html_body: <h1>Test <img src="cid:mypicture.jpg" /></h1>
                  text_body: Test
                  attachments:
                  - filename: report.pdf
                    mimetype: application/pdf
                    fileblob: bm90IGFjdHVhbGx5IGEgcGRm...
                  inlines:
                  - filename: mypicture.jpg
                    mimetype: image/jpeg
                    url: https://myserver.com/mypicture.jpg
                - to:
                  - Jane Jones <jane@example.com>
                  sender: John Smith <john@example.com>
                  subject: 'My Test Email #2'
                  html_body: <h1>Test <img src="cid:mypicture.jpg" /></h1>
                  text_body: Test
                  attachments:
                  - filename: report.pdf
                    mimetype: application/pdf
                    fileblob: bm90IGFjdHVhbGx5IGEgcGRm...
                  inlines:
                  - filename: mypicture.jpg
                    mimetype: image/jpeg
                    url: https://myserver.com/mypicture.jpg
                  schedule: 2026-01-01 12:00:00 +1300
              properties:
                emails:
                  type: array
                  description: An array of email objects to schedule
                  items:
                    type: object
                    required:
                    - sender
                    - to
                    - subject
                    properties:
                      sender:
                        type: string
                        description: The name and email address to send from, in the format `Name <name@example.com>`
                      to:
                        type: array
                        description: An array of names and email addresses (up to 100) to send to, in the format `Name <name@example.com>`
                        items:
                          type: string
                      cc:
                        type: array
                        description: An array of names and email addresses (up to 100) to CC, in the format `Name <name@example.com>`
                        items:
                          type: string
                      bcc:
                        type: array
                        description: An array of names and email addresses (up to 100) to BCC, in the format `Name <name@example.com>`
                        items:
                          type: string
                      subject:
                        type: string
                        description: The subject of the email to be sent
                      html_body:
                        type: string
                        description: 'A HTML encoded email body. Either html_body or text_body is required if template_id is not passed.<br><br> <strong>Warning:</strong><ul><li>To correctly track clicking of URLs you must:  <ul><li>Enable click tracking for the API key</li>  <li>Insert a full anchor HTML element (not just the URL)</li> <li>Include "https://" at the start of the HREF property</li> </ul></ul>'
                      text_body:
                        type: string
                        description: A plain text email body. Either html_body or text_body is required if template_id is not passed
                      custom_headers:
                        type: array
                        description: An array of custom header objects to be applied to the email. For example, a `Reply-To` email can be specified here, with header `Reply-To` and value `name@example.com`. For sending purposes the following headers are not allowed `Content-Type`, `Content-Transfer-Encoding` and `MIME-Version`.
                        items:
                          properties:
                            header:
                              type: string
                              description: Custom header to add to the email
                            value:
                              type: string
                              description: Custom header value to set
                          required:
                          - header
                          - value
                          type: object
                      attachments:
                        type: array
                        description: An array of attachment objects to be attached to the email
                        items:
                          properties:
                            filename:
                              type: string
                              description: The filename to use for this binary data
                            fileblob:
                              type: string
                              description: The Base64 encoded binary data of the file. Required if no url is specified.
                            mimetype:
                              type: string
                              description: The mimetype of the binary data
                            url:
                              type: string
                              description: A URL pointing to the attachment data. The data is directly retrieved by our system, and cached for fast re-use for 24 hours. Required if no fileblob is specified
                          required:
                          - filename
                          type: object
                      inlines:
                        type: array
                        description: An array of images to be inlined into the email. Use an image in content as `<img src="cid:filename" />`
                        items:
                          properties:
                            filename:
                              type: string
                              description: The filename to use for this binary data
                            fileblob:
                              type: string
                              description: The Base64 encoded binary data of the file. Required if no url is specified.
                            mimetype:
                              type: string
                              description: The mimetype of the binary data
                            url:
                              type: string
                              description: A URL pointing to the attachment data. The data is directly retrieved by our system, and cached for fast re-use for 24 hours. Required if no fileblob is specified
                          required:
                          - filename
                          type: object
                      template_id:
                        type: string
                        description: The ID of the template you wish to use
                      template_data:
                        type: string
                        description: 'When a template_id is provided, include the pass-through values in the format `{"variable1": "value1", "variable2": "value2"}`'
                        format: json
                      schedule:
                        type: string
                        description: A timestamp that when passed allows you to schedule an email for sending. Must be in the future and within the next 3 days.<br />The api response will include a `schedule_id` property which can then be used alongside webhooks (An `X-Smtp2go-Schedule-Id` header is added to the sent email corresponds to this id). A total of 50,000 emails can be queued at any one time.
      responses:
        '200':
          description: An array of `email_id/schedule_id` values coinciding with the same order as the request payload.
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: aa253464-0bd0-467a-b24b-6159dcd7be60
                    data:
                    - email_id: 123456-1234-12
                    - schedule_id: 188262b6-f6cc-4c98-bbe6-84c39d1c0ef4
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    example: aa253464-0bd0-467a-b24b-6159dcd7be60
                  data:
                    type: array
                    description: An array of `email_id/schedule_id` information in the same order as the payload.
                    items:
                      type: object
                      properties:
                        email_id:
                          type: string
                          description: The email_id of the email
                        schedule_id:
                          type: string
                          description: The schedule_id of the email (if `schedule` was passed, used to search/remove scheduled emails)
                    example:
                    - email_id: 123456-1234-12
                    - schedule_id: 188262b6-f6cc-4c98-bbe6-84c39d1c0ef4
                    - schedule_id: 789db207-5aba-4895-801b-4ebf1843721e
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
                    data:
                      error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error: You do not have permission to access this API endpoint
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    example: 22e5acba-43bf-11e6-ae42-408d5cce2644
                  data:
                    type: object
                    properties:
                      error_code:
                        type: string
                        example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error:
                        type: string
                        example: You do not have permission to access this API endpoint
      deprecated: false
  /email/mime:
    post:
      tags:
      - EMAILS
      summary: Send a MIME email
      description: Send an email by supplying a pre-encoded MIME string
      operationId: send-mime-email
      requestBody:
        content:
          application/json:
            example:
              mime_email: VG86IHRlc3RAZXhhbXBsZS5jb20KU3ViamVjdDogdGVzdApGcm9tOiBvdGhlckBleGFtcGxlLmNvbQoKdGVzdCBlbWFpbA==
            schema:
              type: object
              required:
              - mime_email
              properties:
                mime_email:
                  type: string
                  description: A valid MIME-encoded string that has been Base64 encoded
                schedule:
                  type: string
                  description: A timestamp that when passed allows you to schedule an email for sending. Must be in the future and within the next 3 days.<br />The api response will include a `schedule_id` property which can then be used alongside webhooks (An `X-Smtp2go-Schedule-Id` header is added to the sent email corresponds to this id). A total of 50,000 emails can be queued at any one time.
                fastaccept:
                  type: boolean
                  default: false
                  description: If true, the email will be accepted immediately and sent in a background process. Use webhooks if you need information about final delivery to the recipient. This will soon become the default method of sending via API.
      responses:
        '200':
          description: Mime email sent
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: aa253464-0bd0-467a-b24b-6159dcd7be60
                    data:
                      failed: 0
                      failures: []
                      succeeded: 1
              schema:
                type: object
                required:
                - request_id
                - data
                properties:
                  request_id:
                    type: string
                    example: aa253464-0bd0-467a-b24b-6159dcd7be60
                  data:
                    type: object
                    required:
                    - email_id
                    properties:
                      failed:
                        type: integer
                        example: 0
                        default: 0
                        description: 'The number of emails that failed to send.<br><br>Note: An email with multiple recipients is classed as 1 email. Only returned if ''fastaccept'' is false.'
                      failures:
                        type: array
                        description: An array containing any error messages encountered during sending. Only returned if 'fastaccept' is false.
                      succeeded:
                        type: integer
                        example: 1
                        default: 0
                        description: 'The number of emails that were successfully sent.<br><br>Note: An email with multiple recipients is classed as 1 email. Only returned if ''fastaccept'' is false.'
                      email_id:
                        type: string
                        example: 1u0SwL-B9zBpi9ffUq-JAB2
                        description: The email ID generated if successfully sent
                      schedule_id:
                        type: string
                        example: caa928f4-24ec-4a68-bcfc-1fd2596342f0
                        description: The schedule ID generated if queued for sending. Only returned if 'schedule' is passed.
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
                    data:
                      error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error: You do not have permission to access this API endpoint
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    example: 22e5acba-43bf-11e6-ae42-408d5cce2644
                  data:
                    type: object
                    properties:
                      error_code:
                        type: string
                        example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error:
                        type: string
                        example: You do not have permission to access this API endpoint
      deprecated: false
  /email/scheduled/remove:
    post:
      tags:
      - EMAILS
      summary: Remove a scheduled email
      description: Removes a scheduled email by ID
      operationId: remove-scheduled-email
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - schedule_id
              example:
                schedule_id: fe7d54d0-8f06-40c5-a675-d72f183e8ebf
              properties:
                schedule_id:
                  type: string
                  description: The schedule_id returned from <code>/v3/email/scheduled/search</code> or the following endpoints [<code>/v3/email/send</code>, <code>/v3/email/mime</code>] (when <code>schedule</code> is passed)
      responses:
        '200':
          description: Scheduled email removed
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
                    data:
                      error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error: You do not have permission to access this API endpoint
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    example: 22e5acba-43bf-11e6-ae42-408d5cce2644
                  data:
                    type: object
                    properties:
                      error_code:
                        type: string
                        example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error:
                        type: string
                        example: You do not have permission to access this API endpoint
      deprecated: false
  /email/scheduled/search:
    post:
      tags:
      - EMAILS
      summary: Search schedule emails
      description: Allows searching of scheduled emails
      operationId: search-scheduled-emails
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: []
              example:
                schedule_id: 8fb29ea3-286d-493e-83c5-401f76859bb1
                search: recipient@example.com
                limit: 100
                page: 2
              properties:
                schedule_id:
                  type: string
                  description: The schedule_id returned from the `/email/send` endpoint
                search_subject:
                  type: string
                  description: The subject of the email you want to search for
                search_recipient:
                  type: string
                  description: The recipient of the email you want to search for
                search_sender:
                  type: string
                  description: The sender of the email you want to search for
                limit:
                  type: integer
                  description: If passed will limit the search results
                  default: 1000
                page:
                  type: integer
                  description: If passed will return the results of the specific page
      responses:
        '200':
          description: Scheduled email results
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: c2dca1b4-89b9-4dc7-bd82-a86b83b29d84
                    data:
                    - schedule_id: 4d3b03a7-8663-4592-899a-b479ba6fcba9
                      schedule: '2025-06-30T23:11:56Z'
                      sender: test@example.com
                      subject: test 1
                      recipients: test@example2.com
                      client_ip: 127.0.0.1
                    - schedule_id: 188262b6-f6cc-4c98-bbe6-84c39d1c0ef4
                      schedule: '2025-06-30T23:11:56Z'
                      sender: test@example.com
                      subject: test 2
                      recipients: test@example2.com
                      client_ip: 127.0.0.1
                    - schedule_id: 789db207-5aba-4895-801b-4ebf1843721e
                      schedule: '2025-06-30T23:11:56Z'
                      sender: test@example.com
                      subject: test 3
                      recipients: test@example2.com
                      client_ip: 127.0.0.1
              schema:
                type: array
                items:
                  type: object
                  description: An array of emails scheduled to be sent
                  properties:
                    schedule_id:
                      type: string
                      description: A unique identifier for the scheduled_email
                    schedule:
                      type: string
                      description: A timestamp indicating when the email was scheduled. A total of 50,000 emails can be queued at any one time.
                    sender:
                      type: string
                      description: The sender of the scheduled email
                    subject:
                      type: string
                      description: The subject of the email
                    recipients:
                      type: string
                      description: The recipients the email is scheduled to send to
                    client_ip:
                      type: string
                      description: The IP address that scheduled the email.
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
                    data:
                      error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error: You do not have permission to access this API endpoint
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    example: 22e5acba-43bf-11e6-ae42-408d5cce2644
                  data:
                    type: object
                    properties:
                      error_code:
                        type: string
                        example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error:
                        type: string
                        example: You do not have permission to access this API endpoint
      deprecated: false
  /email/send:
    post:
      tags:
      - EMAILS
      summary: Send a standard email
      description: Send an email by passing a JSON email object
      operationId: send-standard-email
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - sender
              - to
              example:
                to:
                - Jane Jones <jane@example.com>
                sender: John Smith <john@example.com>
                subject: My Test Email
                html_body: <h1>Test <img src="cid:mypicture.jpg" /></h1>
                text_body: Test
                attachments:
                - filename: report.pdf
                  mimetype: application/pdf
                  fileblob: bm90IGFjdHVhbGx5IGEgcGRm...
                inlines:
                - filename: mypicture.jpg
                  mimetype: image/jpeg
                  url: https://myserver.com/mypicture.jpg
                schedule: 2025-09-10 13:15:00 +1200
              properties:
                sender:
                  type: string
                  description: The name and email address to send from, in the format `Name <name@example.com>`
                to:
                  type: array
                  description: An array of names and email addresses (up to 100) to send to, in the format `Name <name@example.com>`
                  items:
                    type: string
                cc:
                  type: array
                  description: An array of names and email addresses (up to 100) to CC, in the format `Name <name@example.com>`
                  items:
                    type: string
                bcc:
                  type: array
                  description: An array of names and email addresses (up to 100) to BCC, in the format `Name <name@example.com>`
                  items:
                    type: string
                subject:
                  type: string
                  description: The subject of the email to be sent, <strong>Note:</strong> if <code>template_id</code> if passed this field is ignored.<br /><br />If you would like to set a custom subject in the <code>template_data</code>, use a variable (<code>{{custom_subject}}</code> for instance) as the value of the templates <em>subject</em> and then set its value in <code>template_data</code> respectively.
                html_body:
                  type: string
                  description: 'A HTML encoded email body. Either <code>html_body</code> or <code>text_body</code> is required if <code>template_id</code> is not passed. If <code>template_id</code> is passed this field is ignored.<br><br> <strong>Warning:</strong><ul><li>To correctly track clicking of URLs you must:  <ul><li>Enable click tracking for the API key</li>  <li>Insert a full anchor HTML element (not just the URL)</li> <li>Include "https://" at the start of the HREF property</li> </ul></ul>'
                text_body:
                  type: string
                  description: A plain text email body. Either <code>html_body</code> or <code>text_body</code> is required if <code>template_id</code> is not passed. If <code>template_id</code> is passed this field is ignored.
                custom_headers:
                  type: array
                  description: An array of custom header objects to be applied to the email. For example, a `Reply-To` email can be specified here, with header `Reply-To` and value `name@example.com`. For sending purposes the following headers are not allowed `Content-Type`, `Content-Transfer-Encoding` and `MIME-Version`.
                  items:
                    properties:
                      header:
                        type: string
                        description: Custom header to add to the email
                      value:
                        type: string
                        description: Custom header value to set
                    required:
                    - header
                    - value
                    type: object
                attachments:
                  type: array
                  description: An array of attachment objects to be attached to the email
                  items:
                    properties:
                      filename:
                        type: string
                        description: The filename to use for this binary data
                      fileblob:
                        type: string
                        description: The Base64 encoded binary data of the file. Required if no url is specified.
                      mimetype:
                        type: string
                        description: The mimetype of the binary data
                      url:
                        type: string
                        description: A URL pointing to the attachment data. The data is directly retrieved by our system, and cached for fast re-use for 24 hours. Required if no fileblob is specified
                    required:
                    - filename
                    type: object
                inlines:
                  type: array
                  description: An array of images to be inlined into the email. Use an image in content as `<img src="cid:filename"/>`
                  items:
                    properties:
                      filename:
                        type: string
                        description: The filename to use for this binary data
                      fileblob:
                        type: string
                        description: The Base64 encoded binary data of the file. Required if no url is specified.
                      mimetype:
                        type: string
                        description: The mimetype of the binary data
                      url:
                        type: string
                        description: A URL pointing to the attachment data. The data is directly retrieved by our system, and cached for fast re-use for 24 hours. Required if no fileblob is specified
                    required:
                    - filename
                    type: object
                template_id:
                  type: string
                  description: The ID of the template you wish to use
                template_data:
                  type: string
                  description: 'When a template_id is provided, include the pass-through values in the format `{"variable1": "value1", "variable2": "value2"}`'
                  format: json
                schedule:
                  type: string
                  description: A timestamp that when passed allows you to schedule an email for sending. Must be in the future and within the next 3 days.<br />The api response will include a `schedule_id` property which can then be used alongside webhooks (An `X-Smtp2go-Schedule-Id` header is added to the sent email corresponds to this id). A total of 50,000 emails can be queued at any one time.
                fastaccept:
                  type: boolean
                  default: false
                  description: If true, the email will be accepted immediately and sent in a background process. Use webhooks if you need information about final delivery to the recipient. This will soon become the default method of sending via API.
      responses:
        '200':
          description: Email sent
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: aa253464-0bd0-467a-b24b-6159dcd7be60
                    data:
                      succeeded: 1
                      failed: 0
                      failures: []
                      email_id: 1u0SwL-B9zBpi9ffUq-JAB2
              schema:
                type: object
                required:
                - request_id
                - data
                properties:
                  request_id:
                    type: string
                    example: aa253464-0bd0-467a-b24b-6159dcd7be60
                  data:
                    type: object
                    required:
                    - email_id
                    properties:
                      failed:
                        type: integer
                        example: 0
                        default: 0
                        description: 'The number of emails that failed to send.<br><br>Note: An email with multiple recipients is classed as 1 email. Only returned if ''fastaccept'' is false.'
                      failures:
                        type: array
                        description: An array containing any error messages encountered during sending. Only returned if 'fastaccept' is false.
                      succeeded:
                        type: integer
                        example: 1
                        default: 0
                        description: 'The number of emails that were successfully sent.<br><br>Note: An email with multiple recipients is classed as 1 email. Only returned if ''fastaccept'' is false.'
                      email_id:
                        type: string
                        example: 1u0SwL-B9zBpi9ffUq-JAB2
                        description: The email ID generated if successfully sent
                      schedule_id:
                        type: string
                        example: caa928f4-24ec-4a68-bcfc-1fd2596342f0
                        description: The schedule ID generated if queued for sending. Only returned if 'schedule' is passed.
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Example:
                  value:
                    request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
                    data:
                      error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error: You do not have permission to access this API endpoint
              schema:
                type: object
                properties:
                  request_id:
                    type: string
                    example: 22e5acba-43bf-11e6-ae42-408d5cce2644
                  data:
                    type: object
                    properties:
                      error_code:
                        type: string
                        example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
                      error:
                        type: string
                        example: You do not have permission to access this API endpoint
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: X-Smtp2go-Api-Key
      x-default: ${SMTP2GO_API_KEY}