Using IP address filters for email receipt in Amazon SES - Amazon SDK for JavaScript
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

The Amazon SDK for JavaScript V3 API Reference Guide describes in detail all the API operations for the Amazon SDK for JavaScript version 3 (V3).

Starting October 1, 2022, Amazon SDK for JavaScript (v3) will end support for Internet Explorer 11 (IE 11). For details, see Announcing the end of support for Internet Explorer 11 in the Amazon SDK for JavaScript (v3).

Using IP address filters for email receipt in Amazon SES

JavaScript code example that applies to Node.js execution

This Node.js code example shows:

  • How to create IP address filters to accept or reject mail that originates from an IP address or range of IP addresses.

  • How to list your current IP address filters.

  • How to delete an IP address filter.

In Amazon SES, a filter is a data structure that consists of a name, an IP address range, and the functionality to allow or block mail from it. IP addresses you want to block or allow are specified as a single IP address or a range of IP addresses in Classless Inter-Domain Routing (CIDR) notation. For details on how Amazon SES receives email, see Amazon SES email-receiving concepts in the Amazon Simple Email Service Developer Guide.

The scenario

In this example, a series of Node.js modules are used 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:

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 Amazon SDK for JavaScript and third-party modules. Follow the instructions on GitHub.

  • Create a shared configurations file with your user credentials. For more information about providing a shared credentials file, see Loading credentials in Node.js from the shared credentials file.

Important

These examples demonstrate how to import/export client service objects and command using ECMAScript6 (ES6).

Creating an IP address filter

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 Amazon Region.

import { SESClient } from "@aws-sdk/client-ses"; // Set the AWS Region. const REGION = "us-east-1"; // Create SES service object. const sesClient = new SESClient({ region: REGION }); export { sesClient };

This example code can be found here on GitHub.

Create a Node.js module with the file name ses_createreceiptfilter.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 IP filter, including the filter name, an IP address or range of addresses to filter, and whether to allow or block email traffic from the filtered addresses. To call the CreateReceiptFilterCommand method, invoke an Amazon SES service object, passing the parameters.

Note

This example imports and uses the required Amazon 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.

Note

Replace IP_ADDRESS_OR_RANGE with the IP address or range of addresses to filter, POLICY with with ALLOW or BLOCK, and NAME with the filter name.

import { CreateReceiptFilterCommand, ReceiptFilterPolicy, } from "@aws-sdk/client-ses"; import { sesClient } from "./libs/sesClient.js"; import { getUniqueName } from "../../libs/utils/util-string.js"; const createCreateReceiptFilterCommand = ({ policy, ipOrRange, name }) => { return new CreateReceiptFilterCommand({ Filter: { IpFilter: { Cidr: ipOrRange, // string, either a single IP address (10.0.0.1) or an IP address range in CIDR notation (10.0.0.1/24)). Policy: policy, // enum ReceiptFilterPolicy, email traffic from the filtered addressesOptions. }, /* The name of the IP address filter. Only ASCII letters, numbers, underscores, or dashes. Must be less than 64 characters and start and end with a letter or number. */ Name: name, }, }); }; const FILTER_NAME = getUniqueName("ReceiptFilter"); const run = async () => { const createReceiptFilterCommand = createCreateReceiptFilterCommand({ policy: ReceiptFilterPolicy.Allow, ipOrRange: "10.0.0.1", name: FILTER_NAME, }); try { return await sesClient.send(createReceiptFilterCommand); } catch (err) { console.log("Failed to create filter.", err); return err; } };

To run the example, enter the following at the command prompt. The filter is created in Amazon SES.

node ses_createreceiptfilter.js

This example code can be found here on GitHub.

Listing your IP address filters

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 Amazon Region.

import { SESClient } from "@aws-sdk/client-ses"; // Set the AWS Region. const REGION = "us-east-1"; // Create SES service object. const sesClient = new SESClient({ region: REGION }); export { sesClient };

This example code can be found here on GitHub.

Create a Node.js module with the file name ses_listreceiptfilters.js. Configure the SDK as previously shown, including installing the required clients and packages.

Create an empty parameters object. To call the ListReceiptFiltersCommand method, invoking an Amazon SES service object, passing the parameters.

import { ListReceiptFiltersCommand } from "@aws-sdk/client-ses"; import { sesClient } from "./libs/sesClient.js"; const createListReceiptFiltersCommand = () => new ListReceiptFiltersCommand({}); const run = async () => { const listReceiptFiltersCommand = createListReceiptFiltersCommand(); try { return await sesClient.send(listReceiptFiltersCommand); } catch (err) { console.log("Failed to list receipt filters.", err); return err; } };

To run the example, enter the following at the command prompt. Amazon SES returns the filter list.

node ses_listreceiptfilters.js

This example code can be found here on GitHub.

Deleting an IP address filter

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 Amazon Region.

import { SESClient } from "@aws-sdk/client-ses"; // Set the AWS Region. const REGION = "us-east-1"; // Create SES service object. const sesClient = new SESClient({ region: REGION }); export { sesClient };

This example code can be found here on GitHub.

Create a Node.js module with the file name ses_deletereceiptfilter.js. Configure the SDK as previously shown, including installing the required clients and packages.

Create an object to pass the name of the IP filter to delete. To call the DeleteReceiptFilterCommand method, invoke an Amazon SES client service object, passing the parameters.

Note

This example imports and uses the required Amazon 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.

Note

Replace FILTER_NAME with the name of the IP filter to delete.

import { DeleteReceiptFilterCommand } from "@aws-sdk/client-ses"; import { sesClient } from "./libs/sesClient.js"; import { getUniqueName } from "../../libs/utils/util-string.js"; const RECEIPT_FILTER_NAME = getUniqueName("ReceiptFilterName"); const createDeleteReceiptFilterCommand = (filterName) => { return new DeleteReceiptFilterCommand({ FilterName: filterName }); }; const run = async () => { const deleteReceiptFilterCommand = createDeleteReceiptFilterCommand(RECEIPT_FILTER_NAME); try { return await sesClient.send(deleteReceiptFilterCommand); } catch (err) { console.log("Error deleting receipt filter.", err); return err; } };

To run the example, enter the following at the command prompt. The filter is deleted from Amazon SES.

node ses_deletereceiptfilter.js

This example code can be found here on GitHub.