The full Amazon Simple Email Service v2 API (API version 2019-09-27) — 86 operations across email sending, email identities and DKIM, configuration sets and event destinations, contact lists and contacts, email templates, suppression lists, dedicated IP pools, deliverability reporting, tenants, import/export jobs and account settings. Harvested verbatim from the APIs.guru conversion of the first-party AWS SDK service model for sesv2.
openapi: 3.0.0
info:
version: 2019-09-27
x-release: v4
title: Amazon Simple Email Service
description: <fullname>Amazon SES API v2</fullname> <p> <a href="http://aws.amazon.com/ses">Amazon SES</a> is an Amazon Web Services service that you can use to send email messages to your customers.</p> <p>If you're new to Amazon SES API v2, you might find it helpful to review the <a href="https://docs.aws.amazon.com/ses/latest/DeveloperGuide/">Amazon Simple Email Service Developer Guide</a>. The <i>Amazon SES Developer Guide</i> provides information and code samples that demonstrate how to use Amazon SES API v2 features programmatically.</p>
x-logo:
url: https://api.apis.guru/v2/cache/logo/https_twitter.com_awscloud_profile_image.png
backgroundColor: "#FFFFFF"
termsOfService: https://aws.amazon.com/service-terms/
contact:
name: Mike Ralphson
email: mike.ralphson@gmail.com
url: https://github.com/mermade/aws2openapi
x-twitter: PermittedSoc
license:
name: Apache 2.0 License
url: http://www.apache.org/licenses/
x-providerName: amazonaws.com
x-serviceName: sesv2
x-aws-signingName: ses
x-origin:
- contentType: application/json
url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/sesv2-2019-09-27.normal.json
converter:
url: https://github.com/mermade/aws2openapi
version: 1.0.0
x-apisguru-driver: external
x-apiClientRegistration:
url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct
x-apisguru-categories:
- cloud
x-preferred: true
externalDocs:
description: Amazon Web Services documentation
url: https://docs.aws.amazon.com/email/
servers:
- url: http://email.{region}.amazonaws.com
variables:
region:
description: The AWS region
enum:
- us-east-1
- us-east-2
- us-west-1
- us-west-2
- us-gov-west-1
- us-gov-east-1
- ca-central-1
- eu-north-1
- eu-west-1
- eu-west-2
- eu-west-3
- eu-central-1
- eu-south-1
- af-south-1
- ap-northeast-1
- ap-northeast-2
- ap-northeast-3
- ap-southeast-1
- ap-southeast-2
- ap-east-1
- ap-south-1
- sa-east-1
- me-south-1
default: us-east-1
description: The Amazon SES V2 multi-region endpoint
- url: https://email.{region}.amazonaws.com
variables:
region:
description: The AWS region
enum:
- us-east-1
- us-east-2
- us-west-1
- us-west-2
- us-gov-west-1
- us-gov-east-1
- ca-central-1
- eu-north-1
- eu-west-1
- eu-west-2
- eu-west-3
- eu-central-1
- eu-south-1
- af-south-1
- ap-northeast-1
- ap-northeast-2
- ap-northeast-3
- ap-southeast-1
- ap-southeast-2
- ap-east-1
- ap-south-1
- sa-east-1
- me-south-1
default: us-east-1
description: The Amazon SES V2 multi-region endpoint
- url: http://email.{region}.amazonaws.com.cn
variables:
region:
description: The AWS region
enum:
- cn-north-1
- cn-northwest-1
default: cn-north-1
description: The Amazon SES V2 endpoint for China (Beijing) and China (Ningxia)
- url: https://email.{region}.amazonaws.com.cn
variables:
region:
description: The AWS region
enum:
- cn-north-1
- cn-northwest-1
default: cn-north-1
description: The Amazon SES V2 endpoint for China (Beijing) and China (Ningxia)
x-hasEquivalentPaths: true
paths:
/v2/email/metrics/batch:
post:
operationId: BatchGetMetricData
description: <p>Retrieves batches of metric data collected based on your sending activity.</p> <p>You can execute this operation no more than 16 times per second, and with at most 160 queries from the batches per second (cumulative).</p>
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/BatchGetMetricDataResponse"
"480":
description: BadRequestException
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestException"
"481":
description: InternalServiceErrorException
content:
application/json:
schema:
$ref: "#/components/schemas/InternalServiceErrorException"
"482":
description: TooManyRequestsException
content:
application/json:
schema:
$ref: "#/components/schemas/TooManyRequestsException"
"483":
description: NotFoundException
content:
application/json:
schema:
$ref: "#/components/schemas/NotFoundException"
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- Queries
properties:
Queries:
description: A list of queries for metrics to be retrieved.
type: array
items:
$ref: "#/components/schemas/BatchGetMetricDataQuery"
minItems: 1
maxItems: 10
parameters:
- $ref: "#/components/parameters/X-Amz-Content-Sha256"
- $ref: "#/components/parameters/X-Amz-Date"
- $ref: "#/components/parameters/X-Amz-Algorithm"
- $ref: "#/components/parameters/X-Amz-Credential"
- $ref: "#/components/parameters/X-Amz-Security-Token"
- $ref: "#/components/parameters/X-Amz-Signature"
- $ref: "#/components/parameters/X-Amz-SignedHeaders"
/v2/email/configuration-sets:
post:
operationId: CreateConfigurationSet
description: "Create a configuration set. <i>Configuration sets</i> are groups of rules that you can apply to the emails that you send. You apply a configuration set to an email by specifying the name of the configuration set when you call the Amazon SES API v2. When you apply a configuration set to an email, all of the rules in that configuration set are applied to the email. "
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/CreateConfigurationSetResponse"
"480":
description: AlreadyExistsException
content:
application/json:
schema:
$ref: "#/components/schemas/AlreadyExistsException"
"481":
description: NotFoundException
content:
application/json:
schema:
$ref: "#/components/schemas/NotFoundException"
"482":
description: TooManyRequestsException
content:
application/json:
schema:
$ref: "#/components/schemas/TooManyRequestsException"
"483":
description: LimitExceededException
content:
application/json:
schema:
$ref: "#/components/schemas/LimitExceededException"
"484":
description: BadRequestException
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestException"
"485":
description: ConcurrentModificationException
content:
application/json:
schema:
$ref: "#/components/schemas/ConcurrentModificationException"
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ConfigurationSetName
properties:
ConfigurationSetName:
description: <p>The name of a configuration set.</p> <p> <i>Configuration sets</i> are groups of rules that you can apply to the emails you send. You apply a configuration set to an email by including a reference to the configuration set in the headers of the email. When you apply a configuration set to an email, all of the rules in that configuration set are applied to the email.</p>
type: string
TrackingOptions:
description: <p>An object that defines the tracking options for a configuration set. When you use the Amazon SES API v2 to send an email, it contains an invisible image that's used to track when recipients open your email. If your email contains links, those links are changed slightly in order to track when recipients click them.</p> <p>These images and links include references to a domain operated by Amazon Web Services. You can optionally configure the Amazon SES to use a domain that you operate for these images and links.</p>
type: object
properties:
CustomRedirectDomain:
allOf:
- $ref: "#/components/schemas/CustomRedirectDomain"
- description: The domain to use for tracking open and click events.
DeliveryOptions:
description: Used to associate a configuration set with a dedicated IP pool.
type: object
properties:
TlsPolicy:
allOf:
- $ref: "#/components/schemas/TlsPolicy"
- description: Specifies whether messages that use the configuration set are required to use Transport Layer Security (TLS). If the value is <code>Require</code>, messages are only delivered if a TLS connection can be established. If the value is <code>Optional</code>, messages can be delivered in plain text if a TLS connection can't be established.
SendingPoolName:
allOf:
- $ref: "#/components/schemas/PoolName"
- description: The name of the dedicated IP pool to associate with the configuration set.
ReputationOptions:
description: "Enable or disable collection of reputation metrics for emails that you send using this configuration set in the current Amazon Web Services Region. "
type: object
properties:
ReputationMetricsEnabled:
allOf:
- $ref: "#/components/schemas/Enabled"
- description: If <code>true</code>, tracking of reputation metrics is enabled for the configuration set. If <code>false</code>, tracking of reputation metrics is disabled for the configuration set.
LastFreshStart:
allOf:
- $ref: "#/components/schemas/LastFreshStart"
- description: The date and time (in Unix time) when the reputation metrics were last given a fresh start. When your account is given a fresh start, your reputation metrics are calculated starting from the date of the fresh start.
SendingOptions:
description: Used to enable or disable email sending for messages that use this configuration set in the current Amazon Web Services Region.
type: object
properties:
SendingEnabled:
allOf:
- $ref: "#/components/schemas/Enabled"
- description: If <code>true</code>, email sending is enabled for the configuration set. If <code>false</code>, email sending is disabled for the configuration set.
Tags:
description: An array of objects that define the tags (keys and values) to associate with the configuration set.
type: array
items:
$ref: "#/components/schemas/Tag"
SuppressionOptions:
description: An object that contains information about the suppression list preferences for your account.
type: object
properties:
SuppressedReasons:
allOf:
- $ref: "#/components/schemas/SuppressionListReasons"
- description: <p>A list that contains the reasons that email addresses are automatically added to the suppression list for your account. This list can contain any or all of the following:</p> <ul> <li> <p> <code>COMPLAINT</code> – Amazon SES adds an email address to the suppression list for your account when a message sent to that address results in a complaint.</p> </li> <li> <p> <code>BOUNCE</code> – Amazon SES adds an email address to the suppression list for your account when a message sent to that address results in a hard bounce.</p> </li> </ul>
VdmOptions:
description: An object that defines the VDM settings that apply to emails that you send using the configuration set.
type: object
properties:
DashboardOptions:
allOf:
- $ref: "#/components/schemas/DashboardOptions"
- description: Specifies additional settings for your VDM configuration as applicable to the Dashboard.
GuardianOptions:
allOf:
- $ref: "#/components/schemas/GuardianOptions"
- description: Specifies additional settings for your VDM configuration as applicable to the Guardian.
parameters:
- $ref: "#/components/parameters/X-Amz-Content-Sha256"
- $ref: "#/components/parameters/X-Amz-Date"
- $ref: "#/components/parameters/X-Amz-Algorithm"
- $ref: "#/components/parameters/X-Amz-Credential"
- $ref: "#/components/parameters/X-Amz-Security-Token"
- $ref: "#/components/parameters/X-Amz-Signature"
- $ref: "#/components/parameters/X-Amz-SignedHeaders"
get:
operationId: ListConfigurationSets
description: <p>List all of the configuration sets associated with your account in the current region.</p> <p> <i>Configuration sets</i> are groups of rules that you can apply to the emails you send. You apply a configuration set to an email by including a reference to the configuration set in the headers of the email. When you apply a configuration set to an email, all of the rules in that configuration set are applied to the email.</p>
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ListConfigurationSetsResponse"
"480":
description: TooManyRequestsException
content:
application/json:
schema:
$ref: "#/components/schemas/TooManyRequestsException"
"481":
description: BadRequestException
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestException"
parameters:
- name: NextToken
in: query
required: false
description: A token returned from a previous call to <code>ListConfigurationSets</code> to indicate the position in the list of configuration sets.
schema:
type: string
- name: PageSize
in: query
required: false
description: The number of results to show in a single call to <code>ListConfigurationSets</code>. If the number of results is larger than the number you specified in this parameter, then the response includes a <code>NextToken</code> element, which you can use to obtain additional results.
schema:
type: integer
"/v2/email/configuration-sets/{ConfigurationSetName}/event-destinations":
post:
operationId: CreateConfigurationSetEventDestination
description: <p>Create an event destination. <i>Events</i> include message sends, deliveries, opens, clicks, bounces, and complaints. <i>Event destinations</i> are places that you can send information about these events to. For example, you can send event data to Amazon SNS to receive notifications when you receive bounces or complaints, or you can use Amazon Kinesis Data Firehose to stream data to Amazon S3 for long-term storage.</p> <p>A single configuration set can include more than one event destination.</p>
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/CreateConfigurationSetEventDestinationResponse"
"480":
description: NotFoundException
content:
application/json:
schema:
$ref: "#/components/schemas/NotFoundException"
"481":
description: AlreadyExistsException
content:
application/json:
schema:
$ref: "#/components/schemas/AlreadyExistsException"
"482":
description: LimitExceededException
content:
application/json:
schema:
$ref: "#/components/schemas/LimitExceededException"
"483":
description: TooManyRequestsException
content:
application/json:
schema:
$ref: "#/components/schemas/TooManyRequestsException"
"484":
description: BadRequestException
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestException"
parameters:
- name: ConfigurationSetName
in: path
required: true
description: The name of the configuration set .
schema:
type: string
description: <p>The name of a configuration set.</p> <p> <i>Configuration sets</i> are groups of rules that you can apply to the emails you send. You apply a configuration set to an email by including a reference to the configuration set in the headers of the email. When you apply a configuration set to an email, all of the rules in that configuration set are applied to the email.</p>
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- EventDestinationName
- EventDestination
properties:
EventDestinationName:
description: <p>The name of an event destination.</p> <p> <i>Events</i> include message sends, deliveries, opens, clicks, bounces, and complaints. <i>Event destinations</i> are places that you can send information about these events to. For example, you can send event data to Amazon SNS to receive notifications when you receive bounces or complaints, or you can use Amazon Kinesis Data Firehose to stream data to Amazon S3 for long-term storage.</p>
type: string
EventDestination:
description: An object that defines the event destination. Specifically, it defines which services receive events from emails sent using the configuration set that the event destination is associated with. Also defines the types of events that are sent to the event destination.
type: object
properties:
Enabled:
allOf:
- $ref: "#/components/schemas/Enabled"
- description: <p>If <code>true</code>, the event destination is enabled. When the event destination is enabled, the specified event types are sent to the destinations in this <code>EventDestinationDefinition</code>.</p> <p>If <code>false</code>, the event destination is disabled. When the event destination is disabled, events aren't sent to the specified destinations.</p>
MatchingEventTypes:
allOf:
- $ref: "#/components/schemas/EventTypes"
- description: An array that specifies which events the Amazon SES API v2 should send to the destinations in this <code>EventDestinationDefinition</code>.
KinesisFirehoseDestination:
allOf:
- $ref: "#/components/schemas/KinesisFirehoseDestination"
- description: An object that defines an Amazon Kinesis Data Firehose destination for email events. You can use Amazon Kinesis Data Firehose to stream data to other services, such as Amazon S3 and Amazon Redshift.
CloudWatchDestination:
allOf:
- $ref: "#/components/schemas/CloudWatchDestination"
- description: An object that defines an Amazon CloudWatch destination for email events. You can use Amazon CloudWatch to monitor and gain insights on your email sending metrics.
SnsDestination:
allOf:
- $ref: "#/components/schemas/SnsDestination"
- description: An object that defines an Amazon SNS destination for email events. You can use Amazon SNS to send notification when certain email events occur.
PinpointDestination:
allOf:
- $ref: "#/components/schemas/PinpointDestination"
- description: An object that defines an Amazon Pinpoint project destination for email events. You can send email event data to a Amazon Pinpoint project to view metrics using the Transactional Messaging dashboards that are built in to Amazon Pinpoint. For more information, see <a href="https://docs.aws.amazon.com/pinpoint/latest/userguide/analytics-transactional-messages.html">Transactional Messaging Charts</a> in the <i>Amazon Pinpoint User Guide</i>.
parameters:
- $ref: "#/components/parameters/X-Amz-Content-Sha256"
- $ref: "#/components/parameters/X-Amz-Date"
- $ref: "#/components/parameters/X-Amz-Algorithm"
- $ref: "#/components/parameters/X-Amz-Credential"
- $ref: "#/components/parameters/X-Amz-Security-Token"
- $ref: "#/components/parameters/X-Amz-Signature"
- $ref: "#/components/parameters/X-Amz-SignedHeaders"
get:
operationId: GetConfigurationSetEventDestinations
description: <p>Retrieve a list of event destinations that are associated with a configuration set.</p> <p> <i>Events</i> include message sends, deliveries, opens, clicks, bounces, and complaints. <i>Event destinations</i> are places that you can send information about these events to. For example, you can send event data to Amazon SNS to receive notifications when you receive bounces or complaints, or you can use Amazon Kinesis Data Firehose to stream data to Amazon S3 for long-term storage.</p>
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/GetConfigurationSetEventDestinationsResponse"
"480":
description: NotFoundException
content:
application/json:
schema:
$ref: "#/components/schemas/NotFoundException"
"481":
description: TooManyRequestsException
content:
application/json:
schema:
$ref: "#/components/schemas/TooManyRequestsException"
"482":
description: BadRequestException
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestException"
parameters:
- name: ConfigurationSetName
in: path
required: true
description: The name of the configuration set that contains the event destination.
schema:
type: string
description: <p>The name of a configuration set.</p> <p> <i>Configuration sets</i> are groups of rules that you can apply to the emails you send. You apply a configuration set to an email by including a reference to the configuration set in the headers of the email. When you apply a configuration set to an email, all of the rules in that configuration set are applied to the email.</p>
"/v2/email/contact-lists/{ContactListName}/contacts":
post:
operationId: CreateContact
description: Creates a contact, which is an end-user who is receiving the email, and adds them to a contact list.
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/CreateContactResponse"
"480":
description: BadRequestException
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestException"
"481":
description: TooManyRequestsException
content:
application/json:
schema:
$ref: "#/components/schemas/TooManyRequestsException"
"482":
description: NotFoundException
content:
application/json:
schema:
$ref: "#/components/schemas/NotFoundException"
"483":
description: AlreadyExistsException
content:
application/json:
schema:
$ref: "#/components/schemas/AlreadyExistsException"
parameters:
- name: ContactListName
in: path
required: true
description: The name of the contact list to which the contact should be added.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- EmailAddress
properties:
EmailAddress:
description: The contact's email address.
type: string
TopicPreferences:
description: The contact's preferences for being opted-in to or opted-out of topics.
type: array
items:
$ref: "#/components/schemas/TopicPreference"
UnsubscribeAll:
description: A boolean value status noting if the contact is unsubscribed from all contact list topics.
type: boolean
AttributesData:
description: The attribute data attached to a contact.
type: string
parameters:
- $ref: "#/components/parameters/X-Amz-Content-Sha256"
- $ref: "#/components/parameters/X-Amz-Date"
- $ref: "#/components/parameters/X-Amz-Algorithm"
- $ref: "#/components/parameters/X-Amz-Credential"
- $ref: "#/components/parameters/X-Amz-Security-Token"
- $ref: "#/components/parameters/X-Amz-Signature"
- $ref: "#/components/parameters/X-Amz-SignedHeaders"
get:
operationId: ListContacts
description: Lists the contacts present in a specific contact list.
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/ListContactsResponse"
"480":
description: BadRequestException
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestException"
"481":
description: TooManyRequestsException
content:
application/json:
schema:
$ref: "#/components/schemas/TooManyRequestsException"
"482":
description: NotFoundException
content:
application/json:
schema:
$ref: "#/components/schemas/NotFoundException"
parameters:
- name: ContactListName
in: path
required: true
description: The name of the contact list.
schema:
type: string
- name: PageSize
in: query
required: false
description: The number of contacts that may be returned at once, which is dependent on if there are more or less contacts than the value of the PageSize. Use this parameter to paginate results. If additional contacts exist beyond the specified limit, the <code>NextToken</code> element is sent in the response. Use the <code>NextToken</code> value in subsequent requests to retrieve additional contacts.
schema:
type: integer
- name: NextToken
in: query
required: false
description: A string token indicating that there might be additional contacts available to be listed. Use the token provided in the Response to use in the subsequent call to ListContacts with the same parameters to retrieve the next page of contacts.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
Filter:
description: A filter that can be applied to a list of contacts.
type: object
properties:
FilteredStatus:
allOf:
- $ref: "#/components/schemas/SubscriptionStatus"
- description: "The status by which you are filtering: <code>OPT_IN</code> or <code>OPT_OUT</code>."
TopicFilter:
allOf:
- $ref: "#/components/schemas/TopicFilter"
- description: Used for filtering by a specific topic preference.
/v2/email/contact-lists:
post:
operationId: CreateContactList
description: Creates a contact list.
responses:
"200":
description: Success
content:
application/json:
schema:
$ref: "#/components/schemas/CreateContactListResponse"
"480":
description: BadRequestException
content:
application/json:
schema:
$ref: "#/components/schemas/BadRequestException"
"481":
description: TooManyRequestsException
content:
application/json:
schema:
$ref: "#/components/schemas/TooManyRequestsException"
"482":
description: AlreadyExistsException
content:
application/json:
schema:
$ref: "#/components/schemas/AlreadyExistsException"
"483":
description: LimitExceededException
content:
application/json:
schema:
$ref: "#/components/schemas/LimitExceededException"
parameters: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ContactListName
properties:
ContactListName:
description: The name of the contact list.
type: string
Topics:
description: An interest group, theme, or label within a list. A contact list can have multiple topics.
type: array
items:
$ref: "#/components/schemas/Topic"
Description:
description: A description of what the contact list is about.
type: string
Tags:
description: The tags associated with a contact list.
type: array
items:
$ref: "#/components/schemas/Tag"
parameters:
- $ref: "#/components/parameters/X-Amz-Content-Sha256"
- $ref: "#/components/parameters/X-Amz-Date"
- $
# --- truncated at 32 KB (450 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amazon-ses/refs/heads/main/openapi/_original/amazon-ses-sesv2-openapi.yml