The [AWS SDK for JavaScript V3 API Reference Guide](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) describes in detail all the API operations for the AWS SDK for JavaScript version 3 (V3).
# Amazon Simple Email Service examples
Amazon Simple Email Service (Amazon SES) is a cloud-based email sending service designed to help digital marketers and application developers send marketing, notification, and transactional emails. It is a reliable, cost-effective service for businesses of all sizes that use email to keep in contact with their customers.
![\[Relationship between JavaScript environments, the SDK, and Amazon SES\]](http://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/images/code-samples-ses.png)
The JavaScript API for Amazon SES is exposed through the `SES` client class. For more information about using the Amazon SES client class, see [Class: SES](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/SES/) in the API Reference.
**Topics**
+ [
# Managing Amazon SES identities
](ses-examples-managing-identities.md)
+ [
# Working with email templates in Amazon SES
](ses-examples-creating-template.md)
+ [
# Sending email using Amazon SES
](ses-examples-sending-email.md)
# Managing Amazon SES identities
![\[JavaScript code example that applies to Node.js execution\]](http://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/images/nodeicon.png)
**This Node.js code example shows:**
+ How to verify email addresses and domains used with Amazon SES.
+ How to assign an AWS Identity and Access Management (IAM) policy to your Amazon SES identities.
+ How to list all Amazon SES identities for your AWS account.
+ How to delete identities used with Amazon SES.
An Amazon SES *identity* is an email address or domain that Amazon SES uses to send email. Amazon SES requires you to verify your email identities, confirming that you own them and preventing others from using them.
For details on how to verify email addresses and domains in Amazon SES, see [Verifying email addresses and domains in Amazon SES](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-addresses-and-domains.html) in the Amazon Simple Email Service Developer Guide. For information about sending authorization in Amazon SES, see [Overview of Amazon SES sending authorization](Amazon Simple Email Service Developer Guidesending-authorization-overview.html).
## The scenario
In this example, you use a series of Node.js modules to verify and manage Amazon SES identities. The Node.js modules use the SDK for JavaScript to verify email addresses and domains, using these methods of the `SES` client class:
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/ListIdentitiesCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/ListIdentitiesCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/DeleteIdentityCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/DeleteIdentityCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/VerifyEmailIdentityCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/VerifyEmailIdentityCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/VerifyDomainIdentityCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/VerifyDomainIdentityCommand/)
## Prerequisite tasks
To set up and run this example, you must first complete these tasks:
+ Set up the project environment to run these Node TypeScript examples, and install the required AWS SDK for JavaScript and third-party modules. Follow the instructions on[ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ses/README.md).
+ Create a shared configurations file with your user credentials. For more information about providing a shared credentials file, see [Shared config and credentials files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) in the *AWS SDKs and Tools Reference Guide*.
**Important**
These examples demonstrate how to import/export client service objects and command using ECMAScript6 (ES6).
This requires Node.js version 13.x or higher. To download and install the latest version of Node.js, see [Node.js downloads.](https://nodejs.org/en/download).
If you prefer to use CommonJS syntax, see [JavaScript ES6/CommonJS syntax](sdk-example-javascript-syntax.md).
## Listing your identities
In this example, use a Node.js module to list email addresses and domains to use with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_listidentities.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the `IdentityType` and other parameters for the `ListIdentitiesCommand` method of the `SES` client class. To call the `ListIdentitiesCommand` method, invoke an Amazon SES service object, passing the parameters object.
The `data` returned contains an array of domain identities as specified by the `IdentityType` parameter.
**Note**
Replace *IdentityType* with the identity type, which can be "EmailAddress" or "Domain".
```
import { ListIdentitiesCommand } from "@aws-sdk/client-ses";
import { sesClient } from "./libs/sesClient.js";
const createListIdentitiesCommand = () =>
new ListIdentitiesCommand({ IdentityType: "EmailAddress", MaxItems: 10 });
const run = async () => {
const listIdentitiesCommand = createListIdentitiesCommand();
try {
return await sesClient.send(listIdentitiesCommand);
} catch (err) {
console.log("Failed to list identities.", err);
return err;
}
};
```
To run the example, enter the following at the command prompt.
```
node ses_listidentities.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_listidentities.js).
## Verifying an email address identity
In this example, use a Node.js module to verify email senders to use with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_verifyemailidentity.js`. Configure the SDK as previously shown, including downloading the required clients and packages.
Create an object to pass the `EmailAddress` parameter for the `VerifyEmailIdentityCommand` method of the `SES` client class. To call the `VerifyEmailIdentityCommand` method, invoke an Amazon SES client service object, passing the parameters.
**Note**
Replace *EMAIL\$1ADDRESS* with the email address, such as name@example.com.
```
// Import required AWS SDK clients and commands for Node.js
import { VerifyEmailIdentityCommand } from "@aws-sdk/client-ses";
import { sesClient } from "./libs/sesClient.js";
const EMAIL_ADDRESS = "name@example.com";
const createVerifyEmailIdentityCommand = (emailAddress) => {
return new VerifyEmailIdentityCommand({ EmailAddress: emailAddress });
};
const run = async () => {
const verifyEmailIdentityCommand =
createVerifyEmailIdentityCommand(EMAIL_ADDRESS);
try {
return await sesClient.send(verifyEmailIdentityCommand);
} catch (err) {
console.log("Failed to verify email identity.", err);
return err;
}
};
```
To run the example, enter the following at the command prompt. The domain is added to Amazon SES to be verified.
```
node ses_verifyemailidentity.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_verifyemailidentity.js).
## Verifying a Domain identity
In this example, use a Node.js module to verify email domains to use with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_verifydomainidentity.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the `Domain` parameter for the `VerifyDomainIdentityCommand` method of the `SES` client class. To call the `VerifyDomainIdentityCommand` method, invoke an Amazon SES client service object, passing the parameters object.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *DOMAIN\$1NAME* with the domain name.
```
import { VerifyDomainIdentityCommand } from "@aws-sdk/client-ses";
import {
getUniqueName,
postfix,
} from "@aws-doc-sdk-examples/lib/utils/util-string.js";
import { sesClient } from "./libs/sesClient.js";
/**
* You must have access to the domain's DNS settings to complete the
* domain verification process.
*/
const DOMAIN_NAME = postfix(getUniqueName("Domain"), ".example.com");
const createVerifyDomainIdentityCommand = () => {
return new VerifyDomainIdentityCommand({ Domain: DOMAIN_NAME });
};
const run = async () => {
const VerifyDomainIdentityCommand = createVerifyDomainIdentityCommand();
try {
return await sesClient.send(VerifyDomainIdentityCommand);
} catch (err) {
console.log("Failed to verify domain.", err);
return err;
}
};
```
To run the example, enter the following at the command prompt. The domain is added to Amazon SES to be verified.
```
node ses_verifydomainidentity.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_verifydomainidentity.js).
## Deleting identities
In this example, use a Node.js module to delete email addresses or domains used with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_deleteidentity.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the `Identity` parameter for the `DeleteIdentityCommand` method of the `SES` client class. To call the `DeleteIdentityCommand` method, create a `request` for invoking an Amazon SES client service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *IDENTITY\$1EMAIL* with the email of the identity to be deleted.
```
import { DeleteIdentityCommand } from "@aws-sdk/client-ses";
import { sesClient } from "./libs/sesClient.js";
const IDENTITY_EMAIL = "fake@example.com";
const createDeleteIdentityCommand = (identityName) => {
return new DeleteIdentityCommand({
Identity: identityName,
});
};
const run = async () => {
const deleteIdentityCommand = createDeleteIdentityCommand(IDENTITY_EMAIL);
try {
return await sesClient.send(deleteIdentityCommand);
} catch (err) {
console.log("Failed to delete identity.", err);
return err;
}
};
```
To run the example, enter the following at the command prompt.
```
node ses_deleteidentity.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_deleteidentity.js).
# Working with email templates in Amazon SES
![\[JavaScript code example that applies to Node.js execution\]](http://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/images/nodeicon.png)
**This Node.js code example shows:**
+ How to get a list of all of your email templates.
+ How to retrieve and update email templates.
+ How to create and delete email templates.
Amazon SES enables you ro send personalized email messages using email templates. For details on how to create and use email templates in Amazon SES, see [Sending personalized email using the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-personalized-email-api.html) in the Amazon Simple Email Service Developer Guide.
## The scenario
In this example, you use a series of Node.js modules to work with email templates. The Node.js modules use the SDK for JavaScript to create and use email templates using these methods of the `SES` client class:
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/ListTemplatesCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/ListTemplatesCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/CreateTemplateCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/CreateTemplateCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/GetTemplateCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/GetTemplateCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/DeleteTemplateCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/DeleteTemplateCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/UpdateTemplateCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/UpdateTemplateCommand/)
## Prerequisite tasks
To set up and run this example, you must first complete these tasks:
+ Set up the project environment to run these Node TypeScript examples, and install the required AWS SDK for JavaScript and third-party modules. Follow the instructions on[ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ses/README.md).
+ Create a shared configurations file with your user credentials. For more information about providing a shared credentials file, see [Shared config and credentials files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) in the *AWS SDKs and Tools Reference Guide*.
**Important**
These examples demonstrate how to import/export client service objects and command using ECMAScript6 (ES6).
This requires Node.js version 13.x or higher. To download and install the latest version of Node.js, see [Node.js downloads.](https://nodejs.org/en/download).
If you prefer to use CommonJS syntax, see [JavaScript ES6/CommonJS syntax](sdk-example-javascript-syntax.md).
## Listing your email templates
In this example, use a Node.js module to create an email template to use with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_listtemplates.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the parameters for the `ListTemplatesCommand` method of the `SES` client class. To call the `ListTemplatesCommand` method, invoke an Amazon SES client service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
```
import { ListTemplatesCommand } from "@aws-sdk/client-ses";
import { sesClient } from "./libs/sesClient.js";
const createListTemplatesCommand = (maxItems) =>
new ListTemplatesCommand({ MaxItems: maxItems });
const run = async () => {
const listTemplatesCommand = createListTemplatesCommand(10);
try {
return await sesClient.send(listTemplatesCommand);
} catch (err) {
console.log("Failed to list templates.", err);
return err;
}
};
```
To run the example, enter the following at the command prompt. Amazon SES returns the list of templates.
```
node ses_listtemplates.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_listtemplates.js).
## Getting an email template
In this example, use a Node.js module to get an email template to use with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_gettemplate.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the `TemplateName` parameter for the `GetTemplateCommand` method of the `SES` client class. To call the `GetTemplateCommand` method, invoke an Amazon SES client service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *TEMPLATE\$1NAME* with the name of the template to return.
```
import { GetTemplateCommand } from "@aws-sdk/client-ses";
import { getUniqueName } from "@aws-doc-sdk-examples/lib/utils/util-string.js";
import { sesClient } from "./libs/sesClient.js";
const TEMPLATE_NAME = getUniqueName("TemplateName");
const createGetTemplateCommand = (templateName) =>
new GetTemplateCommand({ TemplateName: templateName });
const run = async () => {
const getTemplateCommand = createGetTemplateCommand(TEMPLATE_NAME);
try {
return await sesClient.send(getTemplateCommand);
} catch (caught) {
if (caught instanceof Error && caught.name === "MessageRejected") {
/** @type { import('@aws-sdk/client-ses').MessageRejected} */
const messageRejectedError = caught;
return messageRejectedError;
}
throw caught;
}
};
```
To run the example, enter the following at the command prompt. Amazon SES returns the template details.
```
node ses_gettemplate.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_gettemplate.js).
## Creating an email template
In this example, use a Node.js module to create an email template to use with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_createtemplate.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the parameters for the `CreateTemplateCommand` method of the `SES` client class, including `TemplateName`, `HtmlPart`, `SubjectPart`, and `TextPart`. To call the `CreateTemplateCommand` method, invoke an Amazon SES client service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *TEMPLATE\$1NAME* with a name for the new template, *HtmlPart* with the HTML tagged content of email, and *SubjectPart* with the subject of the email.
```
import { CreateTemplateCommand } from "@aws-sdk/client-ses";
import { sesClient } from "./libs/sesClient.js";
import { getUniqueName } from "@aws-doc-sdk-examples/lib/utils/util-string.js";
const TEMPLATE_NAME = getUniqueName("TestTemplateName");
const createCreateTemplateCommand = () => {
return new CreateTemplateCommand({
/**
* The template feature in Amazon SES is based on the Handlebars template system.
*/
Template: {
/**
* The name of an existing template in Amazon SES.
*/
TemplateName: TEMPLATE_NAME,
HtmlPart: `
Hello, {{contact.firstName}}!
Did you know Amazon has a mascot named Peccy?
`,
SubjectPart: "Amazon Tip",
},
});
};
const run = async () => {
const createTemplateCommand = createCreateTemplateCommand();
try {
return await sesClient.send(createTemplateCommand);
} catch (err) {
console.log("Failed to create template.", err);
return err;
}
};
```
To run the example, enter the following at the command prompt. The template is added to Amazon SES.
```
node ses_createtemplate.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_createtemplate.js).
## Updating an email template
In this example, use a Node.js module to create an email template to use with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_updatetemplate.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the `Template` parameter values you want to update in the template, with the required `TemplateName` parameter passed to the `UpdateTemplateCommand` method of the `SES` client class. To call the `UpdateTemplateCommand` method, invoke an Amazon SES service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *TEMPLATE\$1NAME* with a name of the template and *HTML\$1PART* with the HTML tagged content of email.
```
import { UpdateTemplateCommand } from "@aws-sdk/client-ses";
import { getUniqueName } from "@aws-doc-sdk-examples/lib/utils/util-string.js";
import { sesClient } from "./libs/sesClient.js";
const TEMPLATE_NAME = getUniqueName("TemplateName");
const HTML_PART = "Hello, World!
";
const createUpdateTemplateCommand = () => {
return new UpdateTemplateCommand({
Template: {
TemplateName: TEMPLATE_NAME,
HtmlPart: HTML_PART,
SubjectPart: "Example",
TextPart: "Updated template text.",
},
});
};
const run = async () => {
const updateTemplateCommand = createUpdateTemplateCommand();
try {
return await sesClient.send(updateTemplateCommand);
} catch (err) {
console.log("Failed to update template.", err);
return err;
}
};
```
To run the example, enter the following at the command prompt. Amazon SES returns the template details.
```
node ses_updatetemplate.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_updatetemplate.js).
## Deleting an email template
In this example, use a Node.js module to create an email template to use with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_deletetemplate.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the required`TemplateName` parameter to the `DeleteTemplateCommand` method of the `SES` client class. To call the `DeleteTemplateCommand` method, invoke an Amazon SES service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *TEMPLATE\$1NAME* with the name of the template to be deleted.
```
import { DeleteTemplateCommand } from "@aws-sdk/client-ses";
import { getUniqueName } from "@aws-doc-sdk-examples/lib/utils/util-string.js";
import { sesClient } from "./libs/sesClient.js";
const TEMPLATE_NAME = getUniqueName("TemplateName");
const createDeleteTemplateCommand = (templateName) =>
new DeleteTemplateCommand({ TemplateName: templateName });
const run = async () => {
const deleteTemplateCommand = createDeleteTemplateCommand(TEMPLATE_NAME);
try {
return await sesClient.send(deleteTemplateCommand);
} catch (err) {
console.log("Failed to delete template.", err);
return err;
}
};
```
To run the example, enter the following at the command prompt. Amazon SES returns the template details.
```
node ses_deletetemplate.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_deletetemplate.js).
# Sending email using Amazon SES
![\[JavaScript code example that applies to Node.js execution\]](http://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/images/nodeicon.png)
**This Node.js code example shows:**
+ Send a text or HTML email.
+ Send emails based on an email template.
+ Send bulk emails based on an email template.
The Amazon SES API provides two different ways for you to send an email, depending on how much control you want over the composition of the email message: formatted and raw. For details, see [Sending formatted email using the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-formatted.html) and [Sending raw email using the Amazon SES API](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-raw.html).
## The scenario
In this example, you use a series of Node.js modules to send email in a variety of ways. The Node.js modules use the SDK for JavaScript to create and use email templates using these methods of the `SES` client class:
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/SendEmailCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/SendEmailCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/SendTemplatedEmailCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/SendTemplatedEmailCommand/)
+ [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/SendBulkTemplatedEmailCommand/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-ses/Class/SendBulkTemplatedEmailCommand/)
## Prerequisite tasks
To set up and run this example, you must first complete these tasks:
+ Set up the project environment to run these Node TypeScript examples, and install the required AWS SDK for JavaScript and third-party modules. Follow the instructions on[ GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/ses/README.md).
+ Create a shared configurations file with your user credentials. For more information about providing a shared credentials file, see [Shared config and credentials files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) in the *AWS SDKs and Tools Reference Guide*.
**Important**
These examples demonstrate how to import/export client service objects and command using ECMAScript6 (ES6).
This requires Node.js version 13.x or higher. To download and install the latest version of Node.js, see [Node.js downloads.](https://nodejs.org/en/download).
If you prefer to use CommonJS syntax, see [JavaScript ES6/CommonJS syntax](sdk-example-javascript-syntax.md).
## Email message sending requirements
Amazon SES composes an email message and immediately queues it for sending. To send email using the `SendEmailCommand` method, your message must meet the following requirements:
+ You must send the message from a verified email address or domain. If you attempt to send email using a non-verified address or domain, the operation results in an `"Email address not verified"` error.
+ If your account is still in the Amazon SES sandbox, you can only send to verified addresses or domains, or to email addresses associated with the Amazon SES Mailbox Simulator. For more information, see [Verifying email addresses and domains](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-addresses-and-domains.html) in the Amazon Simple Email Service Developer Guide.
+ The total size of the message, including attachments, must be smaller than 10 MB.
+ The message must include at least one recipient email address. The recipient address can be a To: address, a CC: address, or a BCC: address. If a recipient email address is not valid (that is, it is not in the format `UserName@[SubDomain.]Domain.TopLevelDomain`), the entire message is rejected, even if the message contains other recipients that are valid.
+ The message cannot include more than 50 recipients across the To:, CC: and BCC: fields. If you need to send an email message to a larger audience, you can divide your recipient list into groups of 50 or fewer, and then call the `sendEmail` method several times to send the message to each group.
## Sending an email
In this example, use a Node.js module to send email with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_sendemail.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the parameter values that define the email to be sent, including sender and receiver addresses, subject, and email body in plain text and HTML formats, to the `SendEmailCommand` method of the `SES` client class. To call the `SendEmailCommand` method, invoke an Amazon SES service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *toAddress* with the address to send the email to, and *fromAddress* with the email address to the send the email from.
```
import { SendEmailCommand } from "@aws-sdk/client-ses";
import { sesClient } from "./libs/sesClient.js";
const createSendEmailCommand = (toAddress, fromAddress) => {
return new SendEmailCommand({
Destination: {
/* required */
CcAddresses: [
/* more items */
],
ToAddresses: [
toAddress,
/* more To-email addresses */
],
},
Message: {
/* required */
Body: {
/* required */
Html: {
Charset: "UTF-8",
Data: "HTML_FORMAT_BODY",
},
Text: {
Charset: "UTF-8",
Data: "TEXT_FORMAT_BODY",
},
},
Subject: {
Charset: "UTF-8",
Data: "EMAIL_SUBJECT",
},
},
Source: fromAddress,
ReplyToAddresses: [
/* more items */
],
});
};
const run = async () => {
const sendEmailCommand = createSendEmailCommand(
"recipient@example.com",
"sender@example.com",
);
try {
return await sesClient.send(sendEmailCommand);
} catch (caught) {
if (caught instanceof Error && caught.name === "MessageRejected") {
/** @type { import('@aws-sdk/client-ses').MessageRejected} */
const messageRejectedError = caught;
return messageRejectedError;
}
throw caught;
}
};
```
To run the example, enter the following at the command prompt. The email is queued for sending by Amazon SES.
```
node ses_sendemail.js
```
This example code can be found [found here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_sendemail.js).
## Sending an email using a template
In this example, use a Node.js module to send email with Amazon SES. Create a Node.js module with the file name `ses_sendtemplatedemail.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the parameter values that define the email to be sent, including sender and receiver addresses, subject, email body in plain text and HTML formats, to the `SendTemplatedEmailCommand` method of the `SES` client class. To call the `SendTemplatedEmailCommand` method, invoke an Amazon SES client service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *REGION* with your AWS Region, *USER* with the name and email address to send the email to, *VERIFIED\$1EMAIL* with the email address to the send the email from, and *TEMPLATE\$1NAME* with the name of the template.
```
import { SendTemplatedEmailCommand } from "@aws-sdk/client-ses";
import {
getUniqueName,
postfix,
} from "@aws-doc-sdk-examples/lib/utils/util-string.js";
import { sesClient } from "./libs/sesClient.js";
/**
* Replace this with the name of an existing template.
*/
const TEMPLATE_NAME = getUniqueName("ReminderTemplate");
/**
* Replace these with existing verified emails.
*/
const VERIFIED_EMAIL = postfix(getUniqueName("Bilbo"), "@example.com");
const USER = { firstName: "Bilbo", emailAddress: VERIFIED_EMAIL };
/**
*
* @param { { emailAddress: string, firstName: string } } user
* @param { string } templateName - The name of an existing template in Amazon SES.
* @returns { SendTemplatedEmailCommand }
*/
const createReminderEmailCommand = (user, templateName) => {
return new SendTemplatedEmailCommand({
/**
* Here's an example of how a template would be replaced with user data:
* Template: Hello {{contact.firstName}},
Don't forget about the party gifts!
* Destination: Hello Bilbo,
Don't forget about the party gifts!
*/
Destination: { ToAddresses: [user.emailAddress] },
TemplateData: JSON.stringify({ contact: { firstName: user.firstName } }),
Source: VERIFIED_EMAIL,
Template: templateName,
});
};
const run = async () => {
const sendReminderEmailCommand = createReminderEmailCommand(
USER,
TEMPLATE_NAME,
);
try {
return await sesClient.send(sendReminderEmailCommand);
} catch (caught) {
if (caught instanceof Error && caught.name === "MessageRejected") {
/** @type { import('@aws-sdk/client-ses').MessageRejected} */
const messageRejectedError = caught;
return messageRejectedError;
}
throw caught;
}
};
```
To run the example, enter the following at the command prompt. The email is queued for sending by Amazon SES.
```
node ses_sendtemplatedemail.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_sendtemplatedemail.js).
## Sending bulk email using a template
In this example, use a Node.js module to send email with Amazon SES.
Create a `libs` directory, and create a Node.js module with the file name `sesClient.js`. Copy and paste the code below into it, which creates the Amazon SES client object. Replace *REGION* with your AWS Region.
```
import { SESClient } from "@aws-sdk/client-ses";
// Set the AWS Region.
const REGION = "us-east-1";
// Credentials are automatically resolved using the AWS SDK credential provider chain.
// For more information, see https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
// Create SES service object.
const sesClient = new SESClient({ region: REGION });
export { sesClient };
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/libs/sesClient.js).
Create a Node.js module with the file name `ses_sendbulktemplatedemail.js`. Configure the SDK as previously shown, including installing the required clients and packages.
Create an object to pass the parameter values that define the email to be sent, including sender and receiver addresses, subject, and email body in plain text and HTML formats, to the `SendBulkTemplatedEmailCommand` method of the `SES` client class. To call the `SendBulkTemplatedEmailCommand` method, invoke an Amazon SES service object, passing the parameters.
**Note**
This example imports and uses the required AWS Service V3 package clients, V3 commands, and uses the `send` method in an async/await pattern. You can create this example using V2 commands instead by making some minor changes. For details, see [Using v3 commands](migrating.md#using_v3_commands).
**Note**
Replace *USERS* with the names and email addresses to send the email to, *VERIFIED\$1EMAIL\$11* with the email address to the send the email from, and *TEMPLATE\$1NAME* with the name of the template.
```
import { SendBulkTemplatedEmailCommand } from "@aws-sdk/client-ses";
import {
getUniqueName,
postfix,
} from "@aws-doc-sdk-examples/lib/utils/util-string.js";
import { sesClient } from "./libs/sesClient.js";
/**
* Replace this with the name of an existing template.
*/
const TEMPLATE_NAME = getUniqueName("ReminderTemplate");
/**
* Replace these with existing verified emails.
*/
const VERIFIED_EMAIL_1 = postfix(getUniqueName("Bilbo"), "@example.com");
const VERIFIED_EMAIL_2 = postfix(getUniqueName("Frodo"), "@example.com");
const USERS = [
{ firstName: "Bilbo", emailAddress: VERIFIED_EMAIL_1 },
{ firstName: "Frodo", emailAddress: VERIFIED_EMAIL_2 },
];
/**
*
* @param { { emailAddress: string, firstName: string }[] } users
* @param { string } templateName the name of an existing template in SES
* @returns { SendBulkTemplatedEmailCommand }
*/
const createBulkReminderEmailCommand = (users, templateName) => {
return new SendBulkTemplatedEmailCommand({
/**
* Each 'Destination' uses a corresponding set of replacement data. We can map each user
* to a 'Destination' and provide user specific replacement data to create personalized emails.
*
* Here's an example of how a template would be replaced with user data:
* Template: Hello {{name}},
Don't forget about the party gifts!
* Destination 1: Hello Bilbo,
Don't forget about the party gifts!
* Destination 2: Hello Frodo,
Don't forget about the party gifts!
*/
Destinations: users.map((user) => ({
Destination: { ToAddresses: [user.emailAddress] },
ReplacementTemplateData: JSON.stringify({ name: user.firstName }),
})),
DefaultTemplateData: JSON.stringify({ name: "Shireling" }),
Source: VERIFIED_EMAIL_1,
Template: templateName,
});
};
const run = async () => {
const sendBulkTemplateEmailCommand = createBulkReminderEmailCommand(
USERS,
TEMPLATE_NAME,
);
try {
return await sesClient.send(sendBulkTemplateEmailCommand);
} catch (caught) {
if (caught instanceof Error && caught.name === "MessageRejected") {
/** @type { import('@aws-sdk/client-ses').MessageRejected} */
const messageRejectedError = caught;
return messageRejectedError;
}
throw caught;
}
};
```
To run the example, enter the following at the command prompt. The email is queued for sending by Amazon SES.
```
node ses_sendbulktemplatedemail.js
```
This example code can be found [here on GitHub](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/ses/src/ses_sendbulktemplatedemail.js).