@mjburtenshaw/macmail
v6.0.3
Published
A library to streamline the composition of SMTP compliant emails using react-email templates to send off to mail vendors.
Downloads
34
Readme
macmail
A library to streamline the composition of SMTP compliant emails using react-email templates to send off to mail vendors.
Table of Contents
Installation
npm install @mjburtenshaw/macmailConfiguration
Add a macmail.config.yml to your project's root directory:
# Required. An email address appended to BCC headers on production environments.
production_dev_recipient: [email protected]
# Required. Overrides recipients with configured recipients (production_dev_recipient or my_email_address) when true to protect against false firings. This should be false in production environments.
override_recipients: true
# Required. The directory from which your application is being run from. Typically `src`, `dist`, `build`, etc.
source_dir: src
# Optional. An email address only used in non-production environments.
my_email_address: [email protected]
# Optional. A string. A companion to my_email_address.
my_name: Firstname LastnameOur config will magically index files in your project ending in .letter.tsx.
See Letters for details on configuring letter templates.
Usage
composeMessage() is the main function of the library:
Example
# macmail.config.yml
production_dev_recipient: [email protected]
my_email_address: [email protected]
my_name: Firstname Lastname// Test.letter.tsx
import {
Body,
Container,
Head,
Heading,
Html,
Preview,
} from '@react-email/components';
import React from 'react';
type TestLetterProps = {
foo: string;
bar: string;
}
const bodyStyles = {
backgroundColor: '#ffffff',
};
const containerStyles = {
paddingLeft: '12px',
paddingRight: '12px',
margin: '0 auto',
};
const h1Styles = {
color: '#333',
fontFamily:
"-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif",
fontSize: '24px',
fontWeight: 'bold',
margin: '40px 0',
padding: '0',
};
export const LETTER_NAME = 'TestLetter';
export const requiredProps = ['foo', 'bar'];
export function TestLetter({ foo, bar }: TestLetterProps) {
return (
<Html>
<Head />
<Preview>This is a test letter</Preview>
<Body style={bodyStyles}>
<Container style={containerStyles}>
<Heading style={h1Styles}>{`${foo}${bar}`}</Heading>
</Container>
</Body>
</Html>
);
}
export default TestLetter;
// useMacmail.ts
import macmail, {
type ComposeMessageOptions,
type RequestedLetter
} from '@mjburtenshaw/macmail';
async function useMacmail(file: Express.Multer.File) {
const sender = '[email protected]';
const recipient = '[email protected]'; // can support an array.
const subject = 'This is a Test!';
const requestedLetter: RequestedLetter = {
name: LETTER_NAME,
props: {
foo: 'fizz',
bar: 'buzz',
},
};
const attachment = await macmail.mail.buildAttachment(file);
const composeMessageOptions: ComposeMessageOptions = {
blindCarbonCopy: '[email protected]', // can support an array.
bodyContentType: mail.CONTENT_TYPES.TEXT_HTML,
carbonCopy: '[email protected]', // can support an array.
attachments: attachment, // can support an array.
};
const message = macmail.mail.composeMessage(
sender,
recipient,
subject,
requestedLetter,
composeMessageOptions
);
return message;
}
Library
The purpose of mail utilities is to parse input in a way that's Simple Mail Transfer Protocol (SMTP) compliant.
composeMessage is the main function of the utility library.
Participants
formatParticipants is the main function of the participant utilities.
The API uses participants defined using an address, e.g., [email protected], or a username-address combination in JSON:
{
"address": "[email protected]",
"username": "Harry Potter"
}The username-address combination is preferred when possible.
When formatting for SMTP, we format the username-address combination like so: Harry Potter <[email protected]>.
We delimit multiple participants using a comma and space. It is valid to have a mix of addresses and username-address combinations in the same participant string.
Headers
composeHeaders is the main function of the header utilities.
SMTP requires the following headers:
- From: an SMTP participant.
- To: an SMTP participant or series of them.
- Subject: a string.
- Content-Type: a MIME type.
- MIME-Version: 1.0.
🚨 Google will override the From header with the authenticated client user when using them as a mail client.
🔤 The header keys should be Pascal-Kebab case, but SMTP isn't picky about this.
🤖 We will encode the subject header in case it has stuff like emojis.
🤷♂️ CC and BCC are optional headers. Content-Transfer-Encoding and a boundary are required, depending on the MIME type.
🎯 We want to prevent misfires to recipients when operating in non-production environments, so we will override the recipients with the developer's address if it's defined, otherwise a configured MACMAIL_PRODUCTION_DEV_RECIPIENT.
🕵️ We also want to add a configured MACMAIL_PRODUCTION_DEV_RECIPIENT as a blind carbon copy on everything we send out for auditing purposes.
Body
composeBody is the main function of the body utilities.
The body is required to render a letter merged with data. Preferably the body content type is HTML, but plain text is available.
If the email has mixed content, the body section must have its own Content-Type headers and boundary.
Attachments
📖 In this context, we refer to files as inputs and attachments as outputs.
composeAttachments is the main function of the attachment utilities.
SMTP-compliant attachments contain the following information:
- The file name.
- The file MIME type.
- The file data.
We have a utility, buildAttachment that accepts a Multer file and packages it as an SMTP-compliant attachment.
An attachment will always have a boundary because email's content type will always be multipart/mixed if it contains attachments. Whether or not the boundary is NEXT or END simply depends on if it is the last attachment.
Letters
The objective of letter utilities is to facilitate the composition and formatting of letters to serve over SMTP.
render serves as the main function of the utilities in this directory.
Letter templates are coded using React Email. They provide an elegant solution for creating email template on a server.
A letter template MUST have the following properties:
- A React function component as the default export.
- The same React function component as a named export.
- An array of strings matching the keys of required component props assigned to a constant named
requiredPropsas a named export. - A PascalCase filename followed by
.letter.tsx, e.g.FooBar.letter.tsx