OpenAPI Specification
openapi: 3.0.3
info:
title: SMTP2GO Email Activity SMTP Users 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: SMTP Users
description: SMTP user account management
paths:
/users/smtp/add:
post:
operationId: addSmtpUser
summary: Add an SMTP user
description: Add a new SMTP user to your account
tags:
- SMTP Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SmtpUserRequest'
responses:
'200':
description: SMTP user added
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/users/smtp/edit:
post:
operationId: editSmtpUser
summary: Edit SMTP user details
description: Update an SMTP user's details with the parameters passed
tags:
- SMTP Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SmtpUserRequest'
responses:
'200':
description: SMTP user updated
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse'
/users/smtp/patch:
post:
operationId: patchSmtpUser
summary: Patch an SMTP user
description: Patch an existing SMTP user ignoring missing properties
tags:
- SMTP Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SmtpUserRequest'
responses:
'200':
description: SMTP user patched
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse'
/users/smtp/delete:
post:
operationId: removeSmtpUser
summary: Remove an SMTP user
description: Remove an SMTP user from your account
tags:
- SMTP Users
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- username
properties:
username:
type: string
description: SMTP username to remove
responses:
'200':
description: SMTP user removed
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse'
/users/smtp/view:
post:
operationId: viewSmtpUsers
summary: View SMTP users
description: Returns a list of all SMTP users managed by this account, or details of a specific user when you include the username
tags:
- SMTP Users
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: Optional SMTP username to view specific user
subaccount_id:
type: string
description: Make call on behalf of a subaccount
responses:
'200':
description: SMTP users list
content:
application/json:
schema:
$ref: '#/components/schemas/ViewSmtpUsersResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
StandardResponse:
type: object
properties:
request_id:
type: string
data:
type: object
additionalProperties: true
ViewSmtpUsersResponse:
type: object
properties:
request_id:
type: string
data:
type: object
properties:
results:
type: array
items:
type: object
properties:
username:
type: string
email_password:
type: string
sending_allowed:
type: boolean
custom_ratelimit:
type: boolean
custom_ratelimit_value:
type: integer
nullable: true
custom_ratelimit_period:
type: string
description:
type: string
feedback_enabled:
type: boolean
archive_enabled:
type: boolean
open_tracking_enabled:
type: boolean
bounce_notifications:
type: string
status:
type: string
SmtpUserRequest:
type: object
required:
- username
properties:
username:
type: string
description: SMTP username (email format)
email_password:
type: string
description: SMTP user password
sending_allowed:
type: boolean
description: Whether the user is allowed to send
description:
type: string
description: User description or notes
custom_ratelimit:
type: boolean
custom_ratelimit_value:
type: integer
description: Max emails per period (if custom rate limit enabled)
custom_ratelimit_period:
type: string
description: Period for custom rate limit
open_tracking_enabled:
type: boolean
archive_enabled:
type: boolean
bounce_notifications:
type: string
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