AWS SES actions

This page provides a reference for AWS Simple Email Service (SES) actions available in the workflow automation actions catalog. Use these actions to create, update, retrieve, and delete email templates, and to send emails through Amazon SES.

Prerequisites

For prerequisites and credentials setup, see Set up AWS credentials.

Create a template

The action identifier is aws.ses.createTemplate.

Creates an email template in Amazon SES for sending templated emails.

Important

At least one of textPart or htmlPart must be provided. SES requires the template to have body content in at least one format.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region where the template will be created.	`us-east-2`
`templateName`	String	Required. Name of the template to create.	`WelcomeEmailTemplate`
`subjectPart`	String	Required. Subject line for emails sent with this template. Supports template variables using `{{variableName}}` syntax.	`Welcome to Our Service`
`textPart`	String	Optional. Plain text version of the email body. At least one of `textPart` or `htmlPart` must be provided.	`Hello, welcome aboard.`
`htmlPart`	String	Optional. HTML version of the email body. At least one of `textPart` or `htmlPart` must be provided.	`<h1>Hello</h1><p>Welcome aboard.</p>`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "created", "expression": ".success"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the create_template boto3 reference. Returns an empty object `{}` on success.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (AlreadyExistsException) when calling the CreateTemplate operation: Template WelcomeEmailTemplate already exists"`

Example workflow

name: create-ses-template
description: 'Create an email template in Amazon SES'
steps:
  - name: createWelcomeTemplate
    type: action
    action: aws.ses.createTemplate
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: us-east-2
      templateName: WelcomeEmailTemplate
      subjectPart: "Welcome to Our Service"
      textPart: "Hello, welcome aboard."
      htmlPart: "<h1>Hello</h1><p>Welcome aboard.</p>"
    next: end

Update a template

The action identifier is aws.ses.updateTemplate.

Updates an existing email template in Amazon SES. The template must already exist.

Important

At least one of textPart or htmlPart must be provided. SES requires the template to have body content in at least one format.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region where the template exists.	`us-east-2`
`templateName`	String	Required. Name of the template to update. Must already exist.	`WelcomeEmailTemplate`
`subjectPart`	String	Required. Updated subject line. Supports template variables using `{{variableName}}` syntax.	`Welcome to Our Service (Updated)`
`textPart`	String	Optional. Updated plain text version of the email body. At least one of `textPart` or `htmlPart` must be provided.	`Hi, thanks again for signing up.`
`htmlPart`	String	Optional. Updated HTML version of the email body. At least one of `textPart` or `htmlPart` must be provided.	`<h1>Welcome!</h1><p>Thanks again for signing up.</p>`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "updated", "expression": ".success"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the update_template boto3 reference. Returns an empty object `{}` on success.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (TemplateDoesNotExistException) when calling the UpdateTemplate operation: Template (WelcomeEmailTemplate) does not exist"`

Example workflow

name: update-ses-template
description: 'Update an email template in Amazon SES'
steps:
  - name: updateWelcomeTemplate
    type: action
    action: aws.ses.updateTemplate
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: us-east-2
      templateName: WelcomeEmailTemplate
      subjectPart: "Welcome to Our Service (Updated)"
      textPart: "Hi, thanks again for signing up."
      htmlPart: "<h1>Welcome!</h1><p>Thanks again for signing up.</p>"
    next: end

Delete a template

The action identifier is aws.ses.deleteTemplate.

Deletes an email template from Amazon SES. This action is idempotent — it succeeds even if the named template does not exist.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region where the template exists.	`us-east-2`
`templateName`	String	Required. Name of the template to delete.	`WelcomeEmailTemplate`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "deleted", "expression": ".success"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the delete_template boto3 reference. Returns an empty object `{}` on success.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (AccessDenied) when calling the DeleteTemplate operation: User is not authorized to perform ses:DeleteTemplate"`

Example workflow

name: delete-ses-template
description: 'Delete an email template from Amazon SES'
steps:
  - name: deleteWelcomeTemplate
    type: action
    action: aws.ses.deleteTemplate
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: us-east-2
      templateName: WelcomeEmailTemplate
    next: end

Get a template

The action identifier is aws.ses.getTemplate.

Retrieves an existing email template from Amazon SES, including its subject, plain text body, and HTML body.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region where the template exists.	`us-east-2`
`templateName`	String	Required. Name of the template to retrieve.	`WelcomeEmailTemplate`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "template", "expression": ".response.Template"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the get_template boto3 reference. Contains a `Template` object with `TemplateName`, `SubjectPart`, `TextPart`, and `HtmlPart`.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (TemplateDoesNotExistException) when calling the GetTemplate operation: Template (WelcomeEmailTemplate) does not exist"`

Example workflow

name: get-ses-template
description: 'Retrieve an email template from Amazon SES'
steps:
  - name: getWelcomeTemplate
    type: action
    action: aws.ses.getTemplate
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: us-east-2
      templateName: WelcomeEmailTemplate
      selectors:
        - name: template
          expression: ".response.Template"
    next: end

List templates

The action identifier is aws.ses.listTemplates.

Lists the email templates present in your Amazon SES account in the current region.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region to list templates from.	`us-east-2`
`maxItems`	Integer	Optional. Maximum number of templates to return per page. Must be between 1 and 100. Defaults to 10.	`50`
`nextToken`	String	Optional. Pagination token from a previous response to retrieve the next page of results.	`some-pagination-token`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "templates", "expression": ".response.TemplatesMetadata"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the list_templates boto3 reference. Contains a `TemplatesMetadata` array of objects with `Name` and `CreatedTimestamp`, plus a `NextToken` for pagination.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (AccessDenied) when calling the ListTemplates operation: User is not authorized to perform ses:ListTemplates"`

Example workflow

name: list-ses-templates
description: 'List email templates in Amazon SES'
steps:
  - name: listSesTemplates
    type: action
    action: aws.ses.listTemplates
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: us-east-2
      maxItems: 50
      selectors:
        - name: templates
          expression: ".response.TemplatesMetadata"
    next: end

Send an email

The action identifier is aws.ses.sendEmail.

Sends an email through Amazon SES. The source address must be a verified SES identity.

Important

At least one of toAddresses, ccAddresses, or bccAddresses must be provided, and at least one of bodyText or bodyHtml must be provided. The combined recipient count across all three address fields cannot exceed 50. All email addresses must be 7-bit ASCII — Unicode domains must be Punycode-encoded.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region to send the email from.	`us-east-2`
`source`	String	Required. Sender email address. Must be a verified SES identity.	`no-reply@example.com`
`subject`	String	Required. Email subject line.	`Welcome to Our Service`
`toAddresses`	List	Optional. List of To recipient addresses. At least one of `toAddresses`, `ccAddresses`, or `bccAddresses` must be provided.	`["recipient@example.com"]`
`ccAddresses`	List	Optional. List of CC recipient addresses. At least one of `toAddresses`, `ccAddresses`, or `bccAddresses` must be provided.	`["cc@example.com"]`
`bccAddresses`	List	Optional. List of BCC recipient addresses. At least one of `toAddresses`, `ccAddresses`, or `bccAddresses` must be provided.	`["bcc@example.com"]`
`bodyText`	String	Optional. Plain text email body. At least one of `bodyText` or `bodyHtml` must be provided.	`Hi there, thanks for signing up.`
`bodyHtml`	String	Optional. HTML email body. At least one of `bodyText` or `bodyHtml` must be provided.	`<h1>Welcome!</h1><p>Thanks for signing up.</p>`
`subjectCharset`	String	Optional. Character set for the subject. Defaults to `UTF-8`.	`UTF-8`
`bodyTextCharset`	String	Optional. Character set for the plain text body. Defaults to `UTF-8`.	`UTF-8`
`bodyHtmlCharset`	String	Optional. Character set for the HTML body. Defaults to `UTF-8`.	`UTF-8`
`replyToAddresses`	List	Optional. Reply-to addresses.	`["reply-to@example.com"]`
`returnPath`	String	Optional. Email address for bounce and complaint notifications.	`bounces@example.com`
`sourceArn`	String	Optional. ARN of a verified identity to use for sending authorization.	`arn:aws:ses:us-east-2:123456789012:identity/example.com`
`returnPathArn`	String	Optional. ARN of a verified identity associated with `returnPath`, for sending authorization.	`arn:aws:ses:us-east-2:123456789012:identity/example.com`
`configurationSetName`	String	Optional. Name of a configuration set to use for this send.	`my-configuration-set`
`tags`	List	Optional. Message tags as a list of `{"Name": "...", "Value": "..."}` objects.	`[{"Name": "purpose", "Value": "welcome-email"}]`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "messageId", "expression": ".response.MessageId"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the send_email boto3 reference. Contains a `MessageId` string on success.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (MessageRejected) when calling the SendEmail operation: Email address is not verified. The following identities failed the check in region US-EAST-2: sender@example.com"`

Example workflow

name: send-ses-email
description: 'Send an email through Amazon SES'
steps:
  - name: sendWelcomeEmail
    type: action
    action: aws.ses.sendEmail
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: us-east-2
      source: no-reply@example.com
      toAddresses:
        - recipient@example.com
      subject: "Welcome to Our Service"
      bodyText: "Hi there, thanks for signing up."
      bodyHtml: "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
      selectors:
        - name: messageId
          expression: ".response.MessageId"
    next: end

Send a templated email

The action identifier is aws.ses.sendTemplatedEmail.

Sends an email using an existing Amazon SES template, substituting placeholder values from templateData into the template. The source address and the referenced template must already exist.

Important

At least one of toAddresses, ccAddresses, or bccAddresses must be provided. Omitting all three results in an AWS API error at send time. The combined recipient count cannot exceed 50, and templateData cannot exceed 262,144 characters.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region to send the email from.	`us-east-2`
`source`	String	Required. Sender email address. Must be a verified SES identity.	`no-reply@example.com`
`template`	String	Required. Name of the SES template to use. Must already exist.	`WelcomeEmailTemplate`
`templateData`	String	Required. JSON string of key/value pairs to substitute into the template's placeholders. Maximum 262,144 characters.	`{"name": "Alice"}`
`toAddresses`	List	Optional. List of To recipient addresses. At least one of `toAddresses`, `ccAddresses`, or `bccAddresses` must be provided.	`["recipient@example.com"]`
`ccAddresses`	List	Optional. List of CC recipient addresses. At least one of `toAddresses`, `ccAddresses`, or `bccAddresses` must be provided.	`["cc@example.com"]`
`bccAddresses`	List	Optional. List of BCC recipient addresses. At least one of `toAddresses`, `ccAddresses`, or `bccAddresses` must be provided.	`["bcc@example.com"]`
`replyToAddresses`	List	Optional. Reply-to addresses.	`["reply-to@example.com"]`
`returnPath`	String	Optional. Email address for bounce and complaint notifications.	`bounces@example.com`
`sourceArn`	String	Optional. ARN of a verified identity to use for sending authorization.	`arn:aws:ses:us-east-2:123456789012:identity/example.com`
`returnPathArn`	String	Optional. ARN of a verified identity associated with `returnPath`, for sending authorization.	`arn:aws:ses:us-east-2:123456789012:identity/example.com`
`templateArn`	String	Optional. Cross-account ARN of the template, as an alternative to `template`.	`arn:aws:ses:us-east-2:123456789012:template/WelcomeEmailTemplate`
`configurationSetName`	String	Optional. Name of a configuration set to use for this send.	`my-configuration-set`
`tags`	List	Optional. Message tags as a list of `{"Name": "...", "Value": "..."}` objects.	`[{"Name": "purpose", "Value": "welcome-email"}]`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "messageId", "expression": ".response.MessageId"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the send_templated_email boto3 reference. Contains a `MessageId` string on success.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (TemplateDoesNotExistException) when calling the SendTemplatedEmail operation: Template (WelcomeEmailTemplate) does not exist"`

Example workflow

name: send-ses-templated-email
description: 'Send a templated email through Amazon SES'
steps:
  - name: sendWelcomeTemplatedEmail
    type: action
    action: aws.ses.sendTemplatedEmail
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: us-east-2
      source: no-reply@example.com
      template: WelcomeEmailTemplate
      templateData: '{"name": "Alice"}'
      toAddresses:
        - recipient@example.com
      selectors:
        - name: messageId
          expression: ".response.MessageId"
    next: end

Send bulk templated emails

The action identifier is aws.ses.sendBulkTemplatedEmail.

Sends a templated email to multiple recipients in a single call, with per-recipient template data substitution. The source address and the referenced template must already exist.

Important

AWS limits this action to 50 destinations entries per call, with up to 50 recipients (combined To/Cc/Bcc) per destination, and a maximum generated message size of 10 MB. Exceeding any of these limits produces an AWS API error at send time.

Each entry in destinations accepts the following fields:

destination — Required. Object with toAddresses, ccAddresses, and/or bccAddresses (each a list of strings).
replacementTemplateData — Optional. JSON string of per-recipient placeholder values. Overrides defaultTemplateData for this recipient.
replacementTags — Optional. List of {"name": "...", "value": "..."} objects that override defaultTags for this recipient.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region to send the emails from.	`us-east-2`
`source`	String	Required. Sender email address. Must be a verified SES identity.	`no-reply@example.com`
`template`	String	Required. Name of the SES template to use. Must already exist.	`WelcomeEmailTemplate`
`defaultTemplateData`	String	Required. JSON string of fallback placeholder values used for any destination that does not supply its own `replacementTemplateData`.	`{"name": "Guest"}`
`destinations`	List	Required. List of per-recipient destination objects. Each entry requires a `destination` object with at least one of `toAddresses`, `ccAddresses`, or `bccAddresses`. Up to 50 entries per call.	`[{"destination": {"toAddresses": ["alice@example.com"]}, "replacementTemplateData": "{\"name\": \"Alice\"}"}]`
`replyToAddresses`	List	Optional. Reply-to addresses applied to all destinations.	`["support@example.com"]`
`returnPath`	String	Optional. Email address for bounce and complaint notifications.	`bounces@example.com`
`sourceArn`	String	Optional. ARN of a verified identity to use for sending authorization.	`arn:aws:ses:us-east-2:123456789012:identity/example.com`
`returnPathArn`	String	Optional. ARN of a verified identity associated with `returnPath`, for sending authorization.	`arn:aws:ses:us-east-2:123456789012:identity/example.com`
`templateArn`	String	Optional. Cross-account ARN of the template, as an alternative to `template`.	`arn:aws:ses:us-east-2:123456789012:template/WelcomeEmailTemplate`
`configurationSetName`	String	Optional. Name of a configuration set to use for this send.	`my-configuration-set`
`defaultTags`	List	Optional. Default message tags applied to all destinations as a list of `{"Name": "...", "Value": "..."}` objects. Individual destinations can override these with `replacementTags`.	`[{"Name": "campaign", "Value": "welcome-series"}]`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "sendStatuses", "expression": ".response.Status"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the send_bulk_templated_email boto3 reference. Contains a `Status` array with one entry per destination, each with a `Status` string, optional `Error`, and `MessageId`.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (TemplateDoesNotExistException) when calling the SendBulkTemplatedEmail operation: Template (WelcomeEmailTemplate) does not exist"`

Example workflow

name: send-ses-bulk-templated-email
description: 'Send bulk templated emails through Amazon SES'
steps:
  - name: sendBulkWelcomeEmail
    type: action
    action: aws.ses.sendBulkTemplatedEmail
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: us-east-2
      source: no-reply@example.com
      template: WelcomeEmailTemplate
      defaultTemplateData: '{"name": "Guest"}'
      destinations:
        - destination:
            toAddresses:
              - alice@example.com
          replacementTemplateData: '{"name": "Alice"}'
        - destination:
            toAddresses:
              - bob@example.com
          replacementTemplateData: '{"name": "Bob"}'
      selectors:
        - name: sendStatuses
          expression: ".response.Status"
    next: end

Prerequisites.css-21sua1{background:none;border:none;width:0;padding:0;}

Create a template

Important

Update a template

Important

Delete a template

Get a template

List templates

Send an email

Important

Send a templated email

Important

Send bulk templated emails

Important

Prerequisites