This project implements the scenario that an email goes out via Mailgun (mailgun.com). Once it’s out, Mailgun sends various events back (open, clicked, etc). We have sent an email via Mailgun and now we expect those events sent to us via webhooks, hitting an API Gateway and then that information is proxied to a Lambda. The Lambda should do two things: save a copy of the raw webhook and publish a transformed version into SNS.
This project has been generated using the aws-nodejs-typescript
template from the Serverless framework.
For detailed instructions, please refer to the documentation.
Clone this repository to your local machine by running the git clone https://github.com/GwamakaCharles/email-status.git
command
Depending on your preferred package manager, follow the instructions below to deploy your project.
Requirements: NodeJS
lts/fermium (v.14.15.0)
. If you're using nvm, runnvm use
to ensure you're using the same Node version in local and in your lambda's runtime.
- Run
npm i
to install the project dependencies
- Run
yarn
to install the project dependencies
It is important to change configuration settings before building, packaging and deployment. |
This project by default deploys to us-east-1
to change it, add --region [REGION_NAME] when building and deploying
:info: INFO |
---|
The SNS service is deployed to us-east-1 , change to this region to see cloudwatch logs |
Go to the src/functions/db.ts
file to change Mongodb database configuration parameters to deploy with your own database
For security, this guide will help to store secrets using Parameter Store provided by Systems Manager in AWS.
These keys need to be stored on AWS as the Lambda functions will need them to run.
To store a key, make sure you are authenticated via the AWS CLI and run the following command:
aws ssm put-parameter --name NAME_OF_SECRET \
--value 'my super safe secret' \
--type SecureString
Below are the keys needed to run these lambda functions:
AccountId="xxxxxxxxxxx" (This is your AWS account ID)
MAILGUN_API_KEY="XXXXXXXXXXXXXXX" (API key from Mailgun)
MAILGUN_DOMAIN="mailgun.XXXXXXXX.com" (Domain on mailgun)
- Connect to AWS from AWS CLI from your teminal by using the aws configure command.
- Run
npx sls package --package dist
to build from typescript to javascript files and package it in to the dist folder with cloudformation configuration files - Run
npx sls deploy --package dist
to deploy this stack to AWS
NOTE:: This project by default deploys to
us-east-1
to build and deploy to othe regions, add --region [REGION_NAME] flag when building and deploying
Alternatively: You can also install the serverless package globally by runing
npm install -g serverless
and then, run thenpm run build-deploy
command to both build and deploy to AWS
This template contains a two lambda functions triggered by an HTTP request made
on the provisioned API Gateway REST API /sendEmail
and /webhook
routes with POST
method. The request body must be provided as application/json
. The body
structure is tested by API Gateway against src/functions/sendEmail/schema.ts
and src/functions/webhook/schema.ts
JSON-Schema definitions: must contain the from, to, subject, html
and
event-data, signature
properties respectively.
- requesting any other path than
/sendEmail
or/webhook
with any other method thanPOST
will result in API Gateway returning a404
HTTP error code - sending a
POST
request to/sendEmail
or/webhook
with a payload not containing the reuqired string properties will result in API Gateway returning a400
HTTP error code - sending a
POST
request to/sendEmail
or/webhook
with a payload containing the required string properteis will result in API Gateway returning a200
HTTP status code.
In order to test the sendEmail and webhook functions locally, run the following command:
-
npx sls invoke local -f sendEmail --path src/functions/sendEmail/mock.json
if you're using NPM -
yarn sls invoke local -f sendEmail --path src/functions/sendEmail/mock.json
if you're using Yarn -
npx sls invoke local -f webhook --path src/functions/webhook/mock.json
if you're using NPM -
yarn sls invoke local -f webhook --path src/functions/webhook/mock.json
if you're using Yarn
Check the sls invoke local command documentation for more information.
Two API endpoints will be generated after the deployment, found after running npx sls deploy
command. Output should be in the format
-
https://ApiEndpoint/dev/sendEmail - This is the endpoint for sending email.
-
https://ApiEndpoint/dev/webhook - This webhook should be configured on your mailgun account to send events (e.g opened, delivered, click e.t.c)
Copy and replace your url
- found in Serverless deploy
command output - and from, to, subject, html
parameters in the following curl
command in your terminal or in Postman to test your newly deployed application.
curl --location --request POST 'https://ApiEndpoint/dev/sendEmail' \
--header 'Content-Type: application/json' \
--data-raw '{
"to": ["[email protected]"],
"from": "[email protected]", # Sender's email from your mailgun account
"subject": "Email Service"
"html":"This is a test email from email service" # Body of the email
}'
⚠️ As is, this template, once deployed, opens a public endpoint within your AWS account resources. Anybody with the URL can actively execute the API Gateway endpoint and the corresponding lambda.
The project code base is mainly located within the src
folder. This folder is divided in:
functions
- containing code base and configuration for the lambda functionslibs
- containing shared code base between lambdas
.
├── src
│ ├── functions # Lambda configuration and source code folder
│ │ ├── sendEmail
│ │ │ ├── handler.ts # `sendEmail` lambda source code
│ │ │ ├── index.ts # `sendEmail` lambda Serverless configuration
│ │ │ ├── mock.json # `sendEmail` lambda input parameter, if any, for local invocation
│ │ │ └── schema.ts # `sendEmail` lambda input event JSON-Schema
│ │ ├── webhook
│ │ │ ├── handler.ts # `webhook` lambda source code
│ │ │ ├── index.ts # `webhook` lambda Serverless configuration
│ │ │ ├── mock.json # `webhook` lambda input parameter, if any, for local invocation
│ │ │ └── schema.ts # `webhook` lambda input event JSON-Schema
│ │ │
│ │ ├── keyStoreModule.ts # This module connects to stored secrets and keys using Parameter Store provided by Systems Manager in AWS.
│ │ ├── db.ts # mongodb database connection abstactions.
│ │ └── index.ts # Import/export of all lambda configurations
│ │
│ └── libs # Lambda shared code
│ └── apiGateway.ts # API Gateway specific helpers
│ └── handlerResolver.ts # Sharable library for resolving lambda handlers
│ └── lambda.ts # Lambda middleware
│
├── package.json
├── serverless.ts # Serverless service file
├── tsconfig.json # Typescript compiler configuration
├── tsconfig.paths.json # Typescript paths
└── webpack.config.js # Webpack configuration
- json-schema-to-ts - uses JSON-Schema definitions used by API Gateway for HTTP request validation to statically generate TypeScript types in your lambda's handler code base
- middy - middleware engine for Node.Js lambda. This template uses http-json-body-parser to convert API Gateway
event.body
property, originally passed as a stringified JSON, to its corresponding parsed object - @serverless/typescript - provides up-to-date TypeScript definitions for your
serverless.ts
service file