OpenAPI Specification
openapi: 3.0.3
info:
title: SMTP2GO Email Activity Suppressions 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: Suppressions
description: Suppression list management
paths:
/suppression/add:
post:
operationId: addSuppression
summary: Add a suppression
description: Suppresses the specified email address or domain
tags:
- Suppressions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddSuppressionRequest'
responses:
'200':
description: Suppression added
content:
application/json:
schema:
$ref: '#/components/schemas/AddSuppressionResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/suppression/delete:
post:
operationId: removeSuppression
summary: Remove a suppression
description: Removes the suppression on the specified email address or domain
tags:
- Suppressions
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email_address
properties:
email_address:
type: string
description: Email address or domain to unsuppress
responses:
'200':
description: Suppression removed
content:
application/json:
schema:
$ref: '#/components/schemas/StandardResponse'
/suppression/view:
post:
operationId: viewSuppressions
summary: View suppressions
description: Returns your suppressed email addresses and domains
tags:
- Suppressions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ViewSuppressionsRequest'
responses:
'200':
description: Suppressions list
content:
application/json:
schema:
$ref: '#/components/schemas/ViewSuppressionsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ViewSuppressionsRequest:
type: object
properties:
continue_token:
type: string
description: Token for pagination through results
email_address:
type: string
description: Check if specific email or domain is blocked
end_date:
type: string
description: ISO-8601 datetime (defaults to 30 days prior)
fuzzy:
type: boolean
description: Enable fuzzy matching on recipients and reasons
reason:
type: string
description: Search by single reason string
reasons:
type: array
items:
type: string
description: Search by multiple reason strings
recipient:
type: string
recipients:
type: array
items:
type: string
sort:
type: string
enum:
- asc
- desc
start_date:
type: string
description: ISO-8601 datetime (defaults to current date)
suppression_type:
type: string
enum:
- manual
- spam
- unsubscribe
- bounce
- compliance
suppression_types:
type: array
items:
type: string
wildcard:
type: string
AddSuppressionRequest:
type: object
required:
- email_address
properties:
email_address:
type: string
description: Email address or domain to suppress
block_description:
type: string
description: Reason for the suppression
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
StandardResponse:
type: object
properties:
request_id:
type: string
data:
type: object
additionalProperties: true
ViewSuppressionsResponse:
type: object
properties:
request_id:
type: string
data:
type: object
properties:
continue_token:
type: string
nullable: true
total_results:
type: integer
results:
type: array
items:
type: object
properties:
email_address:
type: string
reason:
type: string
block_description:
type: string
timestamp:
type: string
complaint:
type: string
AddSuppressionResponse:
type: object
properties:
request_id:
type: string
data:
type: object
properties:
added:
type: boolean
email_address:
type: string
block_description:
type: string
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