openapi: 3.2.0
info:
title: SMTP2GO STATISTICS 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: STATISTICS
description: Delivery, bounce, spam, unsubscribe and cycle statistics
paths:
/stats/email_bounces:
post:
tags:
- STATISTICS
summary: Email bounces
description: Retrieve a summary of bounces and rejects, for the last 30 days.
operationId: email-bounces
requestBody:
content:
application/json:
schema:
type: object
required: []
properties:
username:
type: string
description: Allows statistics to be returned for a specific user.
responses:
'200':
description: Bounce report
content:
application/json:
examples:
Result:
value:
request_id: ee9b9484-63eb-11ed-8da7-f23c9216ce11
data:
emails: 1
rejects: 0
softbounces: 0
hardbounces: 0
bounce_percent: '0.00'
schema:
type: object
required:
- request_id
- data
properties:
request_id:
type: string
example: 2917fc07-d685-4fea-b49a-14087058461f
data:
type: object
required:
- emails
- hardbounces
- bounce_percent
- softbounces
- rejects
properties:
emails:
type: integer
example: 159
default: 0
hardbounces:
type: integer
example: 0
default: 0
bounce_percent:
type: string
example: '0.00'
softbounces:
type: integer
example: 0
default: 0
rejects:
type: integer
example: 0
default: 0
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
error: You do not have permission to access this API endpoint
error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
schema:
type: object
properties:
request_id:
type: string
example: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
type: object
properties:
error:
type: string
example: You do not have permission to access this API endpoint
error_code:
type: string
example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
deprecated: false
/stats/email_cycle:
post:
tags:
- STATISTICS
summary: Email cycle
description: Retrieve a summary of your Account activity, including the start and end date of your monthly plan, the number of emails sent this cycle, the number of emails remaining and the number of emails in your monthly allowance.
operationId: email-cycle
responses:
'200':
description: Summary of Account
content:
application/json:
examples:
Result:
value:
request_id: 4b84c952-9bca-432f-a68e-585e4c7a969c
data:
cycle_start: '2022-11-01 00:00:00+00:00'
cycle_end: '2022-11-30 00:00:00+00:00'
cycle_used: 1
cycle_remaining: 9999
cycle_max: 10000
schema:
type: object
required:
- request_id
- data
properties:
request_id:
type: string
example: 4b84c952-9bca-432f-a68e-585e4c7a969c
data:
type: object
required:
- cycle_end
- cycle_used
- cycle_start
- cycle_max
- cycle_remaining
properties:
cycle_end:
type: string
example: '2016-08-04 01:49:15.863998'
cycle_used:
type: integer
example: 0
default: 0
cycle_start:
type: string
example: '2016-08-01 01:49:15.863998'
cycle_max:
type: integer
example: 1000
default: 0
cycle_remaining:
type: integer
example: 1000
default: 0
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
error: You do not have permission to access this API endpoint
error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
schema:
type: object
properties:
request_id:
type: string
example: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
type: object
properties:
error:
type: string
example: You do not have permission to access this API endpoint
error_code:
type: string
example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
deprecated: false
/stats/email_history:
post:
tags:
- STATISTICS
summary: Email history
description: Retrieve a summary of activity from a specified date range (defaults to last 30 days), per sender email address, SMTP username, domain or subaccount.
operationId: email-history
requestBody:
content:
application/json:
schema:
type: object
properties:
group_by:
type: string
description: One of [email_address, username, domain, subaccount] - controls the grouping of results. Defaults to email_address
start_date:
type: string
description: ISO-8601 formatted datetime which defaults to 30 days prior to the current date at midnight. Timezone is UTC
end_date:
type: string
description: ISO-8601 formatted datetime which defaults the current time. Timezone is UTC
subaccounts:
type: array
description: Pass an optional list of subaccount ids to fetch a summary of only particular subaccounts, ID's can be found by querying /subaccounts/search
responses:
'200':
description: Summary of Account
content:
application/json:
examples:
Result:
value:
request_id: f3898083-f5d5-4512-86bd-e02bd1685840
data:
count: 1
history:
- used: 1
bytecount: 1022
avgsize: 1022
email_address: test3@example.com
lastip: 82.1.149.48
bounces: 0
clicks: 0
opens: 0
rejects: 0
spam: 0
unsubscribes: 0
schema:
type: object
required:
- request_id
- data
properties:
request_id:
type: string
example: f3898083-f5d5-4512-86bd-e02bd1685840
data:
type: object
required:
- count
- history
properties:
count:
type: integer
example: 159
default: 0
bounce_percent_total:
type: number
example: 1.24
default: 0
description: The total percentage of emails that bounced.
open_percent_total:
type: number
example: 1.24
default: 0
description: The total percentage of emails that were opened.
reject_percent_total:
type: number
example: 1.24
default: 0
description: The total percentage of emails that were rejected.
spam_percent_total:
type: number
example: 1.24
default: 0
description: The total percentage of emails that were marked as spam.
unsubscribe_percent_total:
type: number
example: 1.24
default: 0
description: The total percentage of emails that were unsubscribed from.
history:
type: array
items:
type: object
required:
- lastip
- used
- bytecount
- avgsize
properties:
subaccount:
type: string
example: My Subaccount Name
description: Only returned if group_by is set to subaccount
domain:
type: string
example: test.com
description: Only returned if group_by is set to domain
domain_verified:
type: boolean
example: true
description: Only returned if group_by is set to domain
lastip:
type: string
example: 55.67.22.12
used:
type: integer
example: 123
default: 0
email_address:
type: string
example: test3@example.com
description: Only returned if group_by is set to email_address
username:
type: string
example: my_user
description: Only returned if group_by is set to username
description:
type: string
description: A comment or description of the user, Only returned if group_by is set to username
bytecount:
type: integer
example: 148113
default: 0
avgsize:
type: number
example: 1204.1707317073171
default: 0
bounces:
type: integer
example: 123
default: 0
clicks:
type: integer
example: 123
default: 0
opens:
type: integer
example: 123
default: 0
rejects:
type: integer
example: 123
default: 0
spam:
type: integer
example: 123
default: 0
unsubscribes:
type: integer
example: 123
default: 0
bounce_percent:
type: number
example: 1.24
default: 0
description: The percentage of emails that bounced.
open_percent:
type: number
example: 1.24
default: 0
description: The percentage of emails that were opened.
reject_percent:
type: number
example: 1.24
default: 0
description: The percentage of emails that were rejected.
spam_percent:
type: number
example: 1.24
default: 0
description: The percentage of emails that were marked as spam.
unsubscribe_percent:
type: number
example: 1.24
default: 0
description: The percentage of emails that recipients unsubscribed.
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
error: You do not have permission to access this API endpoint
error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
schema:
type: object
properties:
request_id:
type: string
example: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
type: object
properties:
error:
type: string
example: You do not have permission to access this API endpoint
error_code:
type: string
example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
deprecated: false
/stats/email_spam:
post:
tags:
- STATISTICS
summary: Email spam
description: Retrieve a summary of spam complaints and rejects, for the last 30 days.
operationId: email-spam
requestBody:
content:
application/json:
schema:
type: object
required: []
properties:
username:
type: string
description: Allows statistics to be returned for a specific user.
responses:
'200':
description: Spam report
content:
application/json:
examples:
Result:
value:
request_id: 0757ba83-9dfc-4584-bb0c-baa06a28a377
data:
emails: 1
rejects: 0
spams: 0
spam_percent: '0.00'
schema:
type: object
required:
- request_id
- data
properties:
request_id:
type: string
example: 0757ba83-9dfc-4584-bb0c-baa06a28a377
data:
type: object
required:
- spam_percent
- emails
- spams
- rejects
properties:
spam_percent:
type: string
example: '0.00'
emails:
type: integer
example: 159
default: 0
spams:
type: integer
example: 0
default: 0
rejects:
type: integer
example: 0
default: 0
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
error: You do not have permission to access this API endpoint
error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
schema:
type: object
properties:
request_id:
type: string
example: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
type: object
properties:
error:
type: string
example: You do not have permission to access this API endpoint
error_code:
type: string
example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
deprecated: false
/stats/email_summary:
post:
tags:
- STATISTICS
summary: Email summary
description: Retrieve a combination of the email_bounces, email_cycle, email_spam, and email_unsubs calls in one report. Note this call may take longer to complete.
operationId: email-summary
requestBody:
content:
application/json:
schema:
type: object
properties:
username:
type: string
description: Allows statistics to be returned for a specific user
responses:
'200':
description: Account Statistics
content:
application/json:
examples:
Result:
value:
request_id: 72f48187-64d9-4a2f-ba9c-527a2a7911f7
data:
spam_emails: 0
cycle_start: '2022-11-01 00:00:00+00:00'
cycle_end: '2022-11-30 00:00:00+00:00'
cycle_used: 1
cycle_remaining: 9999
cycle_max: 10000
email_count: 1
bounce_rejects: 0
softbounces: 0
hardbounces: 0
bounce_percent: '0.00'
spam_rejects: 0
spam_percent: '0.00'
unsubscribes: 0
unsubscribe_percent: '0.0'
opens: 0
clicks: 0
rejects: 0
schema:
type: object
required:
- request_id
- data
properties:
request_id:
type: string
example: 72f48187-64d9-4a2f-ba9c-527a2a7911f7
data:
type: object
required:
- cycle_end
- spam_rejects
- bounce_percent
- unsubscribes
- bounce_rejects
- spam_percent
- softbounces
- cycle_max
- spam_emails
- cycle_remaining
- cycle_start
- unsubscribe_percent
- cycle_used
- hardbounces
- email_count
- opens
- clicks
- rejects
properties:
cycle_end:
type: string
example: '2016-08-04 01:49:15.863998'
spam_rejects:
type: integer
example: 1
default: 0
deprecated: true
bounce_percent:
type: string
example: '7.33'
unsubscribes:
type: integer
example: 32
default: 0
bounce_rejects:
type: integer
example: 11
default: 0
deprecated: true
spam_percent:
type: string
example: '1.33'
softbounces:
type: integer
example: 6
default: 0
cycle_max:
type: integer
example: 1000
default: 0
spam_emails:
type: integer
example: 2
default: 0
cycle_remaining:
type: integer
example: 850
default: 0
cycle_start:
type: string
example: '2016-08-01 01:49:15.863998'
unsubscribe_percent:
type: string
example: '21.33'
cycle_used:
type: integer
example: 150
default: 0
hardbounces:
type: integer
example: 5
default: 0
email_count:
type: integer
example: 150
default: 0
opens:
type: integer
example: 123
default: 0
clicks:
type: integer
example: 321
default: 0
rejects:
type: integer
example: 11
default: 0
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
error: You do not have permission to access this API endpoint
error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
schema:
type: object
properties:
request_id:
type: string
example: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
type: object
properties:
error:
type: string
example: You do not have permission to access this API endpoint
error_code:
type: string
example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
deprecated: false
/stats/email_unsubs:
post:
tags:
- STATISTICS
summary: Email unsubscribes
description: Retrieve a summary of unsubscribes and rejects, for the last 30 days.
operationId: email-unsubscribes
requestBody:
content:
application/json:
schema:
type: object
required: []
properties:
username:
type: string
description: Allows statistics to be returned for a specific user.
responses:
'200':
description: Unsubscribe report
content:
application/json:
examples:
Result:
value:
request_id: e6e94157-90c7-496d-abdf-a5fef899ad54
data:
emails: 1
rejects: 0
unsubscribes: 0
unsubscribe_percent: '0.00'
schema:
type: object
required:
- request_id
- data
properties:
request_id:
type: string
example: e6e94157-90c7-496d-abdf-a5fef899ad54
data:
type: object
required:
- emails
- unsubscribes
- rejects
- unsubscribe_percent
properties:
emails:
type: integer
example: 159
default: 0
unsubscribes:
type: integer
example: 0
default: 0
rejects:
type: integer
example: 0
default: 0
unsubscribe_percent:
type: string
example: '0.00'
'400':
description: '400'
content:
application/json:
examples:
Result:
value:
request_id: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
error: You do not have permission to access this API endpoint
error_code: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
schema:
type: object
properties:
request_id:
type: string
example: 22e5acba-43bf-11e6-ae42-408d5cce2644
data:
type: object
properties:
error:
type: string
example: You do not have permission to access this API endpoint
error_code:
type: string
example: E_ApiResponseCodes.ENDPOINT_PERMISSION_DENIED
deprecated: false
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: X-Smtp2go-Api-Key
x-default: ${SMTP2GO_API_KEY}