DEPRECATED: MailChannels is no longer a secure and reliable way to send email using Cloudflare Workers. Consider using an alternative service such as Loops or Brevo. See this forum post for more information.
The unofficial package to make sending emails with Cloudflare Workers easier.
This package exists as an unofficial way to provide a type-safe API for the Cloudflare Workers / MailChannels integration.
Install Flaremailer using:
npm install flaremailerTo send an email with Flaremailer, use the following code:
import { Flaremailer } from "flaremailer";
let response = await Flaremailer.send(
{
personalizations: [{
to: [{ email: "[email protected]", name: "Test Recipient" }],
}],
from: { email: "[email protected]", name: "Test Sender" },
subject: "Test email",
content: [{
type: "text/plain",
value: "Look at all this test email content! How fabulous."
}],
},
);
console.log(response);If the above code is successful, you should see 202 in your console.
From a code standpoint, that's all there is to it! Read on to find out how to configure your Worker and domain DNS settings for a seamless experience.
For TypeScript users, this package include type safety for tested features! Check out the types doc file for more information.
This often occurs because the send email address has MailChannels' Domain Lockdown enabled, thus you cannot impersonate that email address. For more information about this, see the Spoofing Protection section below.
Currently, Flaremailer only supports functionality from a Cloudflare domain. This means that your Worker must be running in edge preview (not local mode, which is default), or published to Cloudflare's edge network. This error most often occurs when you are running your Worker in local mode in a test environment.
Some mailbox providers (namely Gmail) have strict email screen procedures that require you to setup a Sender Policy Framework (SPF) record in your domain's DNS so that it can confirm your Worker is legitimately allowed to send emails from that domain.
At the moment, Flaremailer will silently fail if it cannot reach the mailbox due to SPF invalidity. This is seemingly a limitation with Cloudflare and MailChannels.
In your domain's DNS settings, add a TXT record with the following values, replacing yourdomain.com with your domain:
- Location:
yourdomain.com - Type:
TXT - Value:
v=spf1 include:relay.mailchannels.net ~all
If your domain already has a SPF DNS record configured, insert include:relay.mailchannels.net at the end of the existing record (but before ~all), like so:
- Location:
yourdomain.com - Type:
TXT - Value:
v=spf1 include:_spf.mx.cloudflare.net include:relay.mailchannels.net ~all
And that's it! Your emails should now be accepted by all mailbox providers.
MailChannels - Setting up SPF records
MailChannels' Domain Lockdown feature uses the DNS to prove that you control the domains you want to send from via your Worker. The Domain Lockdown allows you to indicate a list of senders and accounts permitted to send emails from your domain. Any other accounts that attempt to send from your domain will be rejected with an error.
Currently, three lockdown identifiers are supported:
auth- This identifies a MailChannels customer, such as a web hosting provider, by specifying the authentication username of the customer.authcodes are a sequence of letters and numbers, such asmyhostingcompany.senderid- This identifies a specific sender identity, such as a PHP script or authenticated webmail user account.senderidstrings specify the provider, type of identity, and the identity, all in a single string. An example of asenderidismyhostingcompany|x-authuser|myusername.cfid- This identifies a Cloudflare Worker and is used to prevent spoofing from your domain if you wish to send email from Cloudflare Workers using the MailChannels/sendAPI. An example of acfidisusername.workers.dev.
Implementing Domain Lockdown:
Create a DNS TXT record like so (replacing yourdomain.com with your literal domain name):
Value:
_mailchannels.yourdomain.comType:TXTContent:v=mc1 ...
What to include in the Content field:
Other than v=mc1, other values are optional. The record can contain any number or combination of auth, senderid and cfid fields, including leaving the list blank. Each field must specify only one value.
- To completely block MailChannels from sending any emails using your domain, leave the TXT record as:
v=mc1
- To lock the domain to a specific Cloudflare Workers account, use:
v=mc1 cfid=username.workers.dev
- To lock the domain to a single provider, use:
v=mc1 auth=myhostingcompany
- To lock the domain to two different providers, use:
v=mc1 auth=myhostingcompany auth=anotherprovider
- To lock the domain to a specific Sender-ID, use:
v=mc1 senderid=myhostingcompany|x-authuser|myusername
- Go to https://dash.cloudflare.com/
- Select "Workers & Pages" from the left navigation bar
- Find your ID in the Subdomain section of your Account Details on the right
Alternatively, you can just try sending without a Domain Lockdown record present and MailChannels will generate an error message that contains your cfid for convenience. Cut and paste that into your _mailchannels DNS record.
Every message sent through MailChannels carries two headers that can be used to identify the auth and senderid of the message:
X-MailChannels-Auth-Id- this header carries theauthX-MailChannels-Sender-Id- this header carries thesenderid
Specifying auth=cloudflare in your Domain Lockdown record will authorize every Cloudflare Worker to send from your domain. For obvious reasons, this is not recommended.