Nimara Mailer

TypeScript serverless app for sending emails from Saleor. And more!

App designed to work in AWS cloud using lambda functions, SQS and secret manager. It has two main components:

• events-receiver - responsible for receiving events from Saleor (or custom ones via http) and pushing them to SQS queue.
• email-sender - responsible for receiving events from SQS queue via lambda triggers and sending emails.

Upon build, it outputs two files. Each, for one component. Both share same environment variables. When deployed to lambda, specify the following handlers:

• events-receiver.handler
• emails-sender.handler

When installing the app in Saleor, it will store it's configuration in the secret manager. Therfore, the secret should be created beforehand with empty object ({}) and the name should be specified in SECRET_MANAGER_APP_CONFIG_PATH env.

If you want to change supported events, you can do it in the const file editing SALEOR_EVENTS or CUSTOM_EVENTS constants.

When adding new events, remember to update TEMPLATES_MAP constant with the proper template and extract email function.

---

Local development

1. Setup required envs. You can copy .env.example to .env and adjust it.
2. nvm use - to set proper node version.
3. pnpm install - to install dependencies.
4. pnpm dev - to start the app.

Docker

Alternatively, you can use docker to run the app.

1. Setup required envs. You can copy .env.example to .env and adjust it.
2. docker compose build - build the app.
3. docker compose run --rm --service-ports app - run the app.

Localstack

Localstack is used for local development to replace need of usage AWS services. Everything needed is automatically configured on container startup.

Running localstack

To run localstack in the background:

$ docker compose up localstack -d

On startup:

• sqs queue will be created automatically with name nimara-mailer-queue.
• secret value will be created ($SECRET_MANAGER_APP_CONFIG_PATH env)
• email identity will be confirmed in SNS ($FROM_EMAIL env).
• domain will be confirmed in SNS ($FROM_DOMAIN env).

Check the init-aws.sh script for more details.

Helpful commands:

Requires awscli-local, to install:

$ brew install awscli-local

or

$ pip3 install awscli-local

Creating queue:

$ awslocal sqs create-queue --region ap-southeast-1 --queue-name nimara-mailer-queue

Purging queue:

$ awslocal sqs purge-queue --region ap-southeast-1 --queue-url http://localhost:4566/000000000000/nimara-mailer-queue

Verifying email identity:

$ awslocal ses verify-email-identity --region ap-southeast-1 --email-address [email protected] --endpoint-url=http://localhost:4566

Verifying domain identity:

$ awslocal ses verify-domain-identity --region ap-southeast-1 --domain mirumee.com --endpoint-url=http://localhost:4566

Using AWS

You can use AWS services directly, without using localstack.

You will need:

• set your AWS envs:
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION
• create a SQS queue and set the SQS_QUEUE_URL env.
• create a secret manager entry and set the SECRET_MANAGER_APP_CONFIG_PATH env. The initial secret should be pre populated with empty object {}.

Email providers

To change the email provider, change the EMAIL_PROVIDER to the provider of your choice. One of:

• AWS_SES
• NODE_MAILER

Amazon Simple Email Service

Set correct envs:

EMAIL_PROVIDER=AWS_SES

AWS_ACCESS_KEY_ID=<correct values>
AWS_REGION=<correct values>
AWS_SECRET_ACCESS_KEY=<correct values>

Moreover, in AWS you will have to:

• verify domain identity from FROM_EMAIL env.
• verify email identity from FROM_DOMAIN env.

Nodemailer

Set correct envs:

EMAIL_PROVIDER=NODE_MAILER

SMTP_HOST=<correct values>
SMTP_PORT=<correct values>

// true for port 465, false for other ports
SMTP_SECURE=<correct values>

// optional
SMTP_USER=<correct values>
SMTP_PASSWORD=<correct values>

Local mail testing

You can test your emails using dockerized Mailpit. To make it work you will need to select a mail provider, which sends mails to the SMTP server.

You can use nodemailer provider for that. Envs from the .env.example are sufficient to make it work.

Then simply run the container

$ docker compose up mailpit -d

You can access the mailbox at http://localhost:8025/

Local email development

App is using React Email for email templating.

To start development server run:

$ pnpm dev:emails

or using docker

$ docker compose up emails

Now you can see emails preview in the browser - http://localhost:3002/

Tests

App is using vitest for testing.

To run tests:

$ pnpm test

or

$ pnpm test:watch

Crafted with ❤️ by Mirumee Software

[email protected]