MakerKit uses the popular package nodemailer to allow you to send emails.
Normally, you would use a service for sending transactional emails such as SendGrid, Mailjet, MailGun, Postmark, and so on.
These are all valid, and it doesn't really matter what you use. In fact, as long as you provide the SMTP credentials for your service, you shouldn't be needing any other change.
Email Configuration
To add your service's configuration, fill the email object in your configuration file at src/configuration.ts:
email: {
host: '',
port: 0,
user: '',
password: '',
senderAddress: 'MakerKit Team <test@makerkit.dev>',
}The details above are provided by the service you're using.
When running the emulators, by default, Makerkit uses Ethereal for sending emails, and not your production service. Read below for more info.
Sending Emails
To send emails, import and use the sendEmail function, such as below:
interface SendEmailParams {
from: string;
to: string;
subject: string;
text?: string;
html?: string;
}
import { sendEmail } from '~/core/email/send-email';
function sendTransactionalEmail() {
const sender = configuration.email.senderAddress;
return sendEmail({
to: `youruser@email.com`,
from: sender,
subject: `Achievement Unlocked!`,
html: `Yay, you unlocked an achievement!`,
});
}Using react.email to render emails
Makerkit's newest versions use react-email to render emails: this is a great library that allows us to write emails using React components.
By default, Makerkit's only email is the one sent when inviting members to a Makerkit application - but you can leverage this library to write your own emails for your application.
For example, here's the code for the email sent when inviting members:
interface Props {
organizationName: string;
organizationLogo?: string;
inviter: Maybe<string>;
invitedUserEmail: string;
link: string;
productName: string;
}
export default function renderInviteEmail(props: Props) {
const title = `You have been invited to join ${props.organizationName}`;
return render(
<Html>
<Head>
<title>{title}</title>
</Head>
<Preview>{title}</Preview>
<Body style={{ width: '500px', margin: '0 auto', font: 'helvetica' }}>
<EmailNavbar />
<Section style={{ width: '100%' }}>
<Column>
<Text>Hi,</Text>
<Text>
{props.inviter} with {props.organizationName} has invited you to
use {props.productName} to collaborate with them.
</Text>
<Text>
Use the button below to set up your account and get started:
</Text>
</Column>
</Section>
<Section>
<Column align="center">
<CallToActionButton href={props.link}>
Join {props.organizationName}
</CallToActionButton>
</Column>
</Section>
<Section>
<Column>
<Text>Welcome aboard,</Text>
<Text>The {props.productName} Team</Text>
</Column>
</Section>
</Body>
</Html>
);
}Using MJML to render emails (deprecated)
If you're using a newer version of Makerkit, this section is deprecated..
Thanks to MJML, we can write emails using handy web components (or HTML tags).
In addition, using react-mjml, we can use React components to compose our emails. Wonderful, right?
Makerkit provides two MJML emails:
- The email sent when inviting members
- The email sent when an asynchronous payment
You can find these emails at src/lib/emails.
Using MJML with React
Let's assume we want to write a Welcome email using React and the sendEmail utility above.
function renderWelcomeEmail(props: {
name: string;
link: string;
}) {
const title = `Hey, ${props.name}, Welcome!`;
return render(
<Mjml>
<MjmlHead>
<MjmlTitle>{title}</MjmlTitle>
<MjmlPreview>{title}</MjmlPreview>
</MjmlHead>
<MjmlBody width={500}>
<EmailNavbar />
<MjmlSection fullWidth>
<MjmlColumn>
<MjmlText>Hi ${props.name}</MjmlText>
<MjmlText>
We're super glad to have you with us!
</MjmlText>
</MjmlColumn>
</MjmlSection>
<MjmlSection>
<MjmlColumn>
<CallToActionButton href={props.link}>
Sign In
</CallToActionButton>
</MjmlColumn>
</MjmlSection>
<MjmlSection>
<MjmlColumn>
<MjmlText>Welcome aboard</MjmlText>
</MjmlColumn>
</MjmlSection>
</MjmlBody>
</Mjml>,
{ validationLevel: 'soft' }
);
}Now, let's write a function that renders the MJML email and sends it to our user:
function sendTransactionalWelcomeEmail(props: {
user: string;
email: string;
}) {
const { html, errors } = renderInviteEmail({
link: `https://makerkit.dev/sign-in`,
name: props.user,
});
if (errors.length) {
throw new Error(
`Found errors while rendering email: ${JSON.stringify(errors)}`
);
}
return sendEmail({
to: props.email,
from: configuration.email.senderAddress,
subject: `Welcome to Makerkit`,
html,
});
}That's it! Learn more about react-mjml.
Testing Emails
By default, when running the Firebase Emulators, Makerkit will use Ethereal as an email transport provider. This service allows us to test our emails for free.
To configure Ethereal, subscribe to the service and grab the credentials generated for you. Then, add them as environment variables:
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=
Alternatively, Makerkit will generate these credentials for you. Every time you send an email, the credentials are printed to the console so that you can grab them and inspect the emails sent: feel free to add these as your environment variables if you haven't added them yet. In this way, you will always reuse the same Ethereal account.