qlxi / email-server

📧 Email proxy server powered by MailChannels and Cloudflare Workers

Email Server

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 Guide 📖

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

Environment Variables 👀

Github Actions

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.

Cloudflare Worker

• 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.

Setup SPF 🕵🏻‍♂️

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

Usage 🚀

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

Basic Email

The Most basic request would look like this:

{
	"to": "[email protected]",
	"from": "[email protected]",
	"subject": "Hello World",
	"text": "Hello World"
}

HTML Emails

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>"
}

Sender and Recipient Name

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"
}

Sending to Multiple Recipients

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"
}

Sending BCC and CC

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]"
	]
}

Reply To

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"
}

Technology Stack 💻

• Framework - Hono
• Deployment - Cloudflare Workers

Bugs or Requests 🐛

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.

Where to find me? 👀