Sending emails with a Makerkit application
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 environment variables in your production environment.
This is best done from your Hosting provider's safe environment variables, or from your CI/CD pipeline.
EMAIL_HOST=EMAIL_PORT=587EMAIL_USER=EMAIL_PASSWORD=EMAIL_SENDER='MakerKit Team <info@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> );}
Testing Emails
For testing emails, we use Ethereal. It is for testing only, so please don't use it in production.
By default, when running the Local environment, 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.