A free email proxy server powered by Mailchannels and Cloudflare Workers
Why free? · Bug report · Feature request
Self host your free email proxy server powered by MailChannels and Cloudflare Workers.
Warning
Mailchannels have dropped their support for Free emails from Cloudflare workers, so this no longer works. The code will still be up but now you need a paid account on Mailchannels in order to send out emails. Read more about this on their blog
Self hosting this is pretty straight forward, there are two ways.
The simplest way is to use the "Deploy with Workers" button and deploy the current version of service on your Cloudflare account.
Another way is to fork this repository under your own Github account which will run the deploy-to-cf Github action workflow.
Note: This workflow requires some environment variables so make sure add those as mentioned below
Add these to the forked repository github actions variables.
CF_API_TOKEN-> This is your Cloudflare API token which has permissions for Worker scripts.CF_ACCOUNT_ID-> This would be your Cloudflare Account ID.
-
TOKEN- Generate a random token that will be used in the "Authorization" header to make authenticated calls to your proxy server to send emails.Generate random tokens quickly
Pro tip! If you just want some random string for generating the token, use this command in your linux/mac system
head -c 20 /dev/urandom | base64
Once these are added, run the workflow and you should see the service being deployed on Cloudflare workers.
SPF is a DNS record that helps prevent email spoofing. You will need to add an SPF record to your domain to allow MailChannels to send emails on your behalf. This step is required.
Add a TXT record to your domain with the following values:
| Name | Value |
|---|---|
| @ | v=spf1 a mx include:relay.mailchannels.net ~all |
If you already have a SPF record added for your domain, note that you cannot add another TXT record for spf. In such cases merge the existing SPF record with mailchannels.
For example if your current SPF record is added for zoho like this v=spf1 include:zoho.in ~all then append the include:relay.mailchannels.net to the same value.
So the new record value will be like this v=spf1 include:zoho.in include:relay.mailchannels.net ~all
Mailchannels imposes domain lockdown to avoid domain spoofing, basically this is a security check to prevent attackers from using your domain to send out emails.
To validate you own the domain from which you will be sending out the emails, you need to add this TXT record.
| Name | Value |
|---|---|
| _mailchannels | v=mc1 cfid=yourdomain.workers.dev |
Replace yourdomain with your workers subdomain which you can find on the Workers & Pages section of Cloudflare
This step is optional, but highly recommended. DKIM is a DNS record that helps prevent email spoofing. You may follow the steps listed in the MailChannels documentation under subsection of Creating a DKIM private and public key and Creating the public DNS records to set up DKIM for your domain.
If you are setting up DKIM, then make sure you add these two additional environment variables for your worker.
DKIM_DOMAIN- This would be your email domain.DKIM_PRIVATE_KEY- This would be the private key that you generated based on the documentation of MailChannels.
Once you have deployed this worker function to Cloudflare Workers, you can send emails by making a POST request to the worker on the /send endpoint with the following parameters:
You need to pass an Authorization header with the secure token. Like the following: Authorization: TOKEN
The Most basic request would look like this:
{
"to": "john@example.com",
"from": "me@example.com",
"subject": "Hello World",
"text": "Hello World"
}You can also send HTML emails by adding an html parameter to the request. This can be used in conjunction with the text parameter to send a multi-part email.
{
"to": "john@example.com",
"from": "me@example.com",
"subject": "Hello World",
"html": "<h1>Hello World</h1>"
}You can also specify a sender and recipient name by adding a name parameter to the request. This can be used for both the to and from parameters.
{
"to": { "email": "john@example.com", "name": "John Doe" },
"from": { "email": "me@example.com", "name": "Jane Doe" },
"subject": "Hello World",
"text": "Hello World"
}You may also send to multiple recipients by passing an array of emails, or an array of objects with email and name properties.
{
"to": [
"john@example.com",
"rose@example.com"
],
"from": "me@example.com",
"subject": "Hello World",
"text": "Hello World"
}OR
{
"to": [
{ "email": "john@example.com", "name": "John Doe" },
{ "email": "rose@example.com", "name": "Rose Doe" }
],
"from": "me@example.com",
"subject": "Hello World",
"text": "Hello World"
}You can also send BCC and CC emails by passing an array of emails, an object with email and name properties, or an array of either, similar to the to parameter.
{
"to": "john@example.com",
"from": "me@example.com",
"subject": "Hello World",
"text": "Hello World",
"cc": [
"jim@example.com",
"rose@example.com"
],
"bcc": [
"gil@example.com"
]
}You can also specify a reply to email address by adding a replyTo parameter to the request. Again, you can use an email string, an object with email and name properties, or an array of either.
{
"to": "john@example.com",
"from": "me@example.com",
"replyTo": "support@example.com",
"subject": "Hello World",
"text": "Hello World"
}- Framework - Hono
- Deployment - Cloudflare Workers
If you encounter any problems feel free to open an issue. If you feel the project is missing a feature, please raise a ticket on GitHub and I'll look into it. Pull requests are also welcome.
