Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SLSCMN-8 email service #12

Merged
merged 3 commits into from
Dec 18, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/DOCS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,5 @@ The documentation is organized into sections by module.
1. [Configuration](/docs/services/CONFIG.md)
1. [DynamoDB Client](/docs/services/DYNAMO.md)
1. [SQS Client](/docs/services/SQS.md)
1. [Email Service](/docs//services//EMAIL.md)
1. [Errors](/docs/errors/ERRORS.md)
98 changes: 98 additions & 0 deletions docs/services/EMAIL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
:house: [Home](/README.md) | :books: [Docs](../DOCS.md)

# Email Service

This document describes how to use the Email service component, `EmailService`, to send email messages.

## How it works

There is an Email microservice within the LeanStacks ecosystem. This microservice encapsulates all of the logic to actually send transactional emails. The email microservice receives requests to create and send emails from a AWS SQS Queue.

When another component needs to send an email, it simply needs to send a message to that Queue.

## Using `EmailService`

The `EmailService` uses the `SQSService` to send a message to the email queue. The message bodies must contain all of the information needed by the Email microservice to create the email message.

To send an email message you will need:

- The SQS Queue URL for the LeanStacks Email Microservice
- An AWS SES email template
- The `EmailService` from `@leanstacks/serverless-common`

### The email queue

The LeanStacks email microservice publishes a CloudFormation output variable containing the URL of the AWS SQS queue to which it listens for requests. In Serverless Framework specifications, that CloudFormation variable is referenced as illustrated below.

```yaml
params:
default:
emailResourcesStack: ls-service-email-resources-${sls:stage}

...omitted for brevity...

provider:
environment:
EMAIL_QUEUE_URL: ${cf:${param:emailResourcesStack}.BulkTemplatedEmailQueueUrl}
```

First, the email microservice CloudFormation stack name is referenced in the parameters. Then an environment variable is created which references the stack output variable.

### The SES email template

The LeanStacks email microservice sends email messages using [AWS SES email templates](https://docs.aws.amazon.com/ses/latest/dg/send-personalized-email-api.html). A SES email template may be created in the console or, better yet, in the resources CloudFormation template for your component.

An example CloudFormation SES email template resource is illustrated below. The `{{variable}}` notations are variables which may be used in the subject or body of the template. Template data will be merged with the template replacing the `{{variable}}` in the template.

_Example: CloudFormation SES Template_

```yaml
Resources:
MyEmailTemplate:
Type: AWS::SES::Template
Properties:
Template:
TemplateName: MyEmailTemplate
SubjectPart: 'How to use SES email templates'
TextPart: 'This is an AWS SES email template. It has a variable: {{variable}}.'
HtmlPart: '<p>This is an AWS SES email template. It has a variable:</p><p>{{variable}}</p>'

Outputs:
MyEmailTemplateName:
Description: My SES Template Name
Value: MyEmailTemplate
```

### Sending an email

To send a message, first import the Email service and related types.

```ts
import EmailService, { Email } from '@leanstacks/serverless-common';
```

Next, use the `EmailService.send` function to send an asynchronous request to the Email microservice.

```ts
const queueUrl = config.EMAIL_QUEUE_URL;

const email: Email = {
destinations: [
{
to: ['[email protected]', '[email protected]'],
cc: ['[email protected]'],
bcc: ['[email protected]'],
},
],
templateName: 'MyEmailTemplate',
templateData: {
variable: 'I go in the email template',
},
};

await EmailService.send(email, queueUrl);
```

That's it! The `EmailService` sends a formatted SQS message to the LeanStacks email microservice.

> **NOTE:** The LeanStacks email microservice sends messages in near real time. There is no delay, batching, or scheduling.
7 changes: 7 additions & 0 deletions src/__fixtures__/email-service.fixture.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
import { Email } from '../services';

export const emailFixture: Email = {
destinations: [{ to: ['[email protected]'] }],
templateName: 'template-name',
templateData: { foo: 'bar' },
};
32 changes: 32 additions & 0 deletions src/services/__tests__/email-service.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
import EmailService from '../email-service';

import SQSService from '../sqs-service';
import { emailFixture } from '../../__fixtures__/email-service.fixture';

describe('EmailService', () => {
const QUEUE_URL = 'queue-url';
const sendSpy = jest.spyOn(SQSService, 'sendMessage');

beforeEach(() => {
sendSpy.mockResolvedValue({ $metadata: {} });
});

it('should be defined', () => {
expect(EmailService).toBeDefined();
expect(EmailService.send).toBeDefined();
});

it('should send email', async () => {
await EmailService.send(emailFixture, QUEUE_URL);

expect(sendSpy).toHaveBeenCalledTimes(1);
expect(sendSpy).toHaveBeenCalledWith({
QueueUrl: QUEUE_URL,
MessageBody: JSON.stringify({
data: emailFixture.templateData,
destinations: emailFixture.destinations,
template: emailFixture.templateName,
}),
});
});
});
60 changes: 60 additions & 0 deletions src/services/email-service.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import SQSService from './sqs-service';

/**
* The addresses to which the email should be sent.
*/
export type EmailDestination = {
to: string[];
cc?: string[];
bcc?: string[];
};

/**
* An object containing data to populate the email template. The object keys
* are strings and the values may be strings, numbers, or booleans.
*
* _Example:_
* ```
* {
* name: 'Joe Smith',
* age: 39,
* isEnabled: true
* }
* ```
*/
export type EmailTemplateData = Record<string, string | number | boolean>;

/**
* The `Email` type describes the request to send an email to one or more
* recipients (i.e. destinations).
*/
export type Email = {
destinations: EmailDestination[];
templateName: string;
templateData?: EmailTemplateData;
};

/**
* Sends an email message asynchronously. Provide the `email` and the AWS SQS
* `queueUrl`. The `queueURL` is the LeanStacks Email microservice SQS Queue.
* @param email - The `Email` object describing the email message.
* @param queueUrl - The AWS SQS queue URL for the Email microservice.
*/
const send = async (email: Email, queueUrl: string): Promise<void> => {
await SQSService.sendMessage({
QueueUrl: queueUrl,
MessageBody: JSON.stringify({
data: email.templateData,
destinations: email.destinations,
template: email.templateName,
}),
});
};

/**
* Use the `EmailService` to send an email message. Messages are sent
* asynchronously.
*/
const EmailService = { send };

export default EmailService;
3 changes: 3 additions & 0 deletions src/services/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,6 @@ export {
export { default as DynamoService } from './dynamo.service';

export { default as SQSService } from './sqs-service';

export { Email, EmailDestination, EmailTemplateData } from './email-service';
export { default as EmailService } from './email-service';