README

@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<{ configuration: Object }> ) => generateRequest: function`

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

The configuration 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.

`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.

Usage no npm install needed!