An Amazon SES E-Mail Scheduler & Delivery API.
You will need the following dependencies properly installed on your computer.
Note: Due to the dependency on Crontab, this application will not run easily on Windows.
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"
}
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"
}
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'));
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
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
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.
Description | Method | Endpoint |
---|---|---|
Send an email | POST |
/send |
Request:
Param | Type | Required |
---|---|---|
to | Array | yes |
cc | Array | no |
bcc | Array | no |
from | String | yes |
subject | String | yes |
body | String | yes |
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"
}
}
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.
Description | Method | Endpoint |
---|---|---|
Create a new poller | POST |
/poll |
Create or update new poller | PUT |
/poll |
Get all pollers | GET |
/poll |
Get specific poller | GET |
/poll/:id |
Delete specific poller | DELETE |
/poll/:id |
Request:
Param | Type | Required |
---|---|---|
id | String | no |
template | Object | yes |
data | Object | yes |
schedule | String/Number | yes |
handler | String | no |
Example:
curl \
-H "Content-Type: application/json" \
-X POST \
-d \
'{
"id": "test-uuid",
"template": {
"test-uuid",
}
}' \
http://localhost:8000/poll
Response:
{
"data": {}
}
curl \
-H "Content-Type: application/json" \
-X PUT \
-d \
'{
"uuid": "test-uuid",
}' \
http://localhost:8000/poll
Response:
{
"data": {}
}
Request:
Param | Type | Required |
---|---|---|
No parameters |
Example:
curl \
-X GET \
http://localhost:8000/poll
Response:
{
"data": []
}
Request:
Param | Type | Required |
---|---|---|
id | Number | yes |
Example:
curl \
-X GET \
http://localhost:8000/poll/<id>
Response:
{
"data": {}
}
Request:
Param | Type | Required |
---|---|---|
id | Number | yes |
Example:
curl \
-X DELETE \
http://localhost:8000/poll/<id>
Response:
{
"data": {}
}
npm start
Visit the server at http://localhost:8000.
npm test