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.

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:

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.

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.

1. DKIM_DOMAIN - This would be your email domain.
2. 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": "[email protected]",
	"from": "[email protected]",
	"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": "[email protected]",
	"from": "[email protected]",
	"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": "[email protected]",  "name": "John Doe" },
	"from": { "email": "[email protected]", "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": [
		"[email protected]",
		"[email protected]"
 	],
	"from": "[email protected]",
	"subject": "Hello World",
	"text": "Hello World"
}

OR

{
	"to": [
		{ "email": "[email protected]", "name": "John Doe" },
		{ "email": "[email protected]", "name": "Rose Doe" }
 	],
	"from": "[email protected]",
	"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": "[email protected]",
	"from": "[email protected]",
	"subject": "Hello World",
	"text": "Hello World",
	"cc": [
		"[email protected]",
		"[email protected]"
	],
	"bcc": [
		"[email protected]"
	]
}

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": "[email protected]",
	"from": "[email protected]",
	"replyTo": "[email protected]",
	"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.