@saibotsivad/aws-ses v1.1.0

@saibotsivad/aws-ses

Minimalist request generator for SES (AWS Simple Email Service).

Generates the url, headers, and body for a POST request to the AWS SES API, using the v4 signing algorithm.

Install

Any of the normal ways:

npm install @saibotsivad/aws-ses

Example

Following the documentation, e.g. for sending an email:

import { awsSes, extractResponse } from '@saibotsivad/aws-ses'
import { post } from 'httpie'

const generateRequest = awsSes({
	credentials: {
		region: process.env.AWS_REGION,
		accessKeyId: process.env.AWS_ACCESS_KEY_ID,
		secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
	}
})

const sendEmail = async email => {
	const { url, headers, body } = await generateRequest('SendEmail', email)

	let response
	try {
		response = await post(url, { headers, body })
	} catch (error) {
		response = error
	}

	return {
		success: response.statusCode === 200,
		data: response.data
	}
}

// ...then later:
const { data, success } = await sendEmail({
	Destination: {
		ToAddresses: [
			'user@site.com'
		]
	},
	Message: {
		Body: {
			Text: {
				Charset: 'UTF-8',
				Data: 'Plaintext message body.'
			}
		},
		Subject: {
			Charset: 'UTF-8',
			Data: 'Hello user!'
		},
	},
	ReplyToAddresses: [
		'office@site.com'
	],
	Source: 'office@site.com'
})

// convenience helper function
console.log(extractResponse(data)) // => { messageId, ... }

API

This library exports two functions, extractResponse and awsSes.

extractResponse: function ( String ) => Object

A convenience function which uses a regular expression to extract the <MessageId /> value from the response data, which is an XML string.

Note: If you have an XML parsing library in your project already, it would be safer to use that instead.

Returns an object with the following possible properties:

• messageId: String The id of the sent message, if appropriate to the action.
• requestId: String The id of the API request, generated by AWS.
• errorType: String The error type, if present, e.g. Sender.
• errorCode: String The error code, if present, e.g. MessageRejected.
• errorMessage: String The full error message, if present.

awsSes: function ( Object<{ credentials: Object, url?: String }> ) => generateRequest: function

Instantiates a request generator. Pass in an object with the property credentials containing the AWS configuration and credentials.

The credentials object takes the following properties:

• region: String (required) The AWS region, e.g. us-east-1.
• accessKeyId (required) The identifier of the access key.
• secretAccessKey (required) The key secret.

If the url string is set, it will be used instead of the AWS region-based URL.

generateRequest: async function ( action: String, params: Object ) => Object<{ url, headers, body }>

Generate the request parameters using the v4 signature algorithm.

• action: String (required) Any valid action defined in the documentation.
• params: Object (required) Whatever the parameters are for that action.

Returns an object with parameters necessary for making the POST request.

• url: String The URL for the specified region, e.g. https://email.us-west-2.amazonaws.com/
• headers: Object<String, String> The headers map containing the signed authorization headers.
• body: String The form-url encoded body string.

License

Published and released with love under the Very Open License.