Pigeon Post

An Amazon SES E-Mail Scheduler & Delivery API.

Prerequisites

You will need the following dependencies properly installed on your computer.

• Git
• Node.js (with NPM)
• Redis
• Crontab (Installed by default in OS X & Linux)

Note: Due to the dependency on Crontab, this application will not run easily on Windows.

Installation

npm install pigeonpost

Set your Amazon SES credentials in a JSON file as outlined in their official docs:

{
  "accessKeyId": "test_key",
  "secretAccessKey": "test_secret",
  "region": "us-east-1"
}

Bounce & Complaint handling

Amazon requires handling of bounce and complaint notices to mitigate potential account suspension. PigeonPost requires that you hook up SES to emit bounce and complaint notices through Amazon SNS. Once you have created a topic and marked your verified email user to forward complaints to SNS, you will need to hook up SNS to Amazon SQS. Create a queue and have it subscribe to your SNS topic. On the SQS configuration page you will find a url that points to your queue. Add this to the configuration file discussed above like so:

{
  "accessKeyId": "test_key",
  "secretAccessKey": "test_secret",
  "region": "us-east-1",
  "sqsUrl": "https://sqs.us-east-1.amazonaws.com/12345/SES_UNDELIVERABLE"
}

Usage

By design this application is meant to be standalone on a server and act as a server daemon. If you would like to directly integrate with your pre-existing server, this application also acts as express middleware:

app.use('/email', require('pigeonpost'));

Environment variable configuration

To inform this module where the secrets file lives, set an environment variable AWS_SES_SECRETS to the absolute fully qualified path on disk. It must be absolute as it may be run from various locations.

For example your variable may look like:

export AWS_SES_SECRETS=/mnt/secrets/ses.json

API

The API should follow JSON-API for errors and data. You must set the content type request header to JSON.

Note: jQuery and other popular request libraries may add this automatically.

Content-Type: application/json

Documentation

Sending

This is the endpoint you'll hit when you want to immediately send an email. Useful for one off emails, such as new account registration or forgot password.

Send an email:

Request:

Example:

curl \
  -H "Content-Type: application/json" \
  -X POST \
  -d \
  '{
     "to": ["[email protected]"],
     "from": "[email protected]",
     "subject": "A test subject!",
     "body": "Test message"
   }' \
  http://localhost:8000/send

Response:

{
  "data": {
    "ResponseMetadata": {
      "RequestId":"2263f1cc-fccf-21e4-a378-4350dc3a1cea"
    },

    "MessageId": "1120014e6373fd1e-2bdf239f-21bf-4c1f-b299-36eacb54dbc6-000000"
  }
}

Pollers

These are jobs that are executed on a specific schedule. They are assigned using Crontab, and allow any valid schedule expression within that format. You would use this endpoint to schedule emails to be sent every day/month/year, schedule an email to be sent 5 minutes from now, etc.

Create a new poller:

Request:

Example:

curl \
  -H "Content-Type: application/json" \
  -X POST \
  -d \
  '{
     "id": "test-uuid",
     "template": {
       "test-uuid",
     }
   }' \
  http://localhost:8000/poll

Response:

{
  "data": {}
}

Create or update new poller:

curl \
  -H "Content-Type: application/json" \
  -X PUT \
  -d \
  '{
     "uuid": "test-uuid",
   }' \
  http://localhost:8000/poll

Response:

{
  "data": {}
}

Get all pollers:

Request:

No parameters

Example:

curl \
  -X GET \
  http://localhost:8000/poll

Response:

{
  "data": []
}

Get specific poller:

Request:

Example:

curl \
  -X GET \
  http://localhost:8000/poll/<id>

Response:

{
  "data": {}
}

Delete specific poller:

Request:

Example:

curl \
  -X DELETE \
  http://localhost:8000/poll/<id>

Response:

{
  "data": {}
}

Running / Development

npm start

Visit the server at http://localhost:8000.

Running Tests

npm test