Setup Mailgun 📧

Create a Mailgun account.

The Mailgun Pay-As-You-Go plan still exists but is no longer prominently advertised. To access it, sign up for the free trial, then cancel to be automatically downgraded to the Pay-As-You-Go plan, which costs $1 for 1,000 emails sent.

Setup a Sandbox Domain (Development)

1. Navigate to the Mailgun Domains page.

2. Select the Mailgun sandbox domain and add it to the .env.local file in the apps/web directory.

3. Click on the sandbox domain and add your email to the Authorized Recipients list for testing email sending functionality.

4. Access the API Keys page and create a new API key.

5. Add this API key to the .env.local file in the apps/web directory.

Create an email template

• Go to the Mailgun Templates page and create a template with the name contact-us.

• Add the name, email and message variables to the template as shown below (style it as you like):

• Create another template called thanks-for-your-purchase for the purchase confirmation email. It will receive the {{ name }} variable so use it as you like.

Go to packages/models/src/entities/MailerAPI.ts to see the interfaces for these template emails. This is where you can create more templates to use when you use the mailerService.

For example, if you open apps/web/src/app/api/webhooks/stripe/route.ts, you can see the following code showing how to send an email using the templates.

await mailService()
	.send({
		template: {
			id: "thanks-for-your-purchase",
			variables: {
				name: name ?? "there",
			},
		},
		// Attach a local zip file to the email
		// attachment: [
		// 	{
		// 		filename: "example.zip",
		// 		data: Buffer.from("Hello, World!"),
		// 		contentType: "application/zip",
		// 	},
		// ],
		to: [email],
	})
	.catch((error) => {
		throw new Error(`Could not send email: ${error}`);
	});

Test Email Sending

Add your personal email (that you added to the Authorized Recipients list) to the getAppConfig.ts under contact.supportEmail.

With the local development server running, go to the Contact Us form and submit a message. You should receive an email at the address you added to the Authorized Recipients list.

Be sure to check your spam folder if you don't see the email in your inbox. The sandbox domain raises the spam score.

Setup a Custom Domain (Production)

The Mailgun Pay-As-You-Go plan still exists but is no longer prominently advertised. To access it, sign up for the free trial, then cancel to be automatically downgraded to the Pay-As-You-Go plan, which costs $1 for 1,000 emails sent.

1. Go to the Mailgun Domains page.

2. Register a custom domain for sending emails, such as mail.yourdomain.com or mg.yourdomain.com.

3. Follow the instructions on the Mailgun DNS settings page to add required DNS records.

4. Add a DMARC record to enhance email deliverability. Here's a basic DMARC record example:

• Type: TEXT

• Host: _dmarc.mail.yourdomain.com

• Value: v=DMARC1; p=none; rua=mailto:postmaster@mail.yourdomain.com

• TTL: 600

Don't forget:

1. To add your custom domain and API key to your production environment variables.

2. To recreate your templates for the new domain.

Now you can set your support email to anything@mail.yourdomain.com in the getAppConfig.ts file under contact.supportEmail.

You'll just need to set up a route on Mailgun to forward emails to your personal email address.

Create a Route

Go to the Routes page and create a new route with the following settings:

• Expression Type: Catch All

• Forward: your@email.com

Send from your custom domain via Gmail

You should have already set your DNS records in the previous step.

1. Reset your postmaster password in the Mailgun settings at `Send > Sending > Domain Settings > SMTP Credentials`. Keep them handy.

2. Go to your Gmail settings: `Settings > See All Settings > Accounts and Import > Send mail as: > Add another email address`.

3. Enter email e.g. `support@mail.yourdomain.com`, keep “Treat as alias ticked” > Next Step.

4. Change SMTP Server to http://smtp.mailgun.org use port 587 with TLS.

5. Enter the username and password for Mailgun that your reset in step 1.

6. Back to the Send mail as panel, tick “Reply from the same address the message was sent to”.