README.md

Cloudflare Worker Email Server

Send free transactional emails from your Cloudflare Workers using MailChannels.

Getting Started!

1. Clone this repository
2. Install the dependencies with npm install
3. Use the command npx wrangler secret put --env production TOKEN to deploy a securely stored token to Cloudflare. With this command, you will be prompted to enter a random secret value, which will be used to authenticate your requests with the HTTP Authorization header as described below. You can also set this encrypted value directly in your Cloudflare dashboard.
4. Deploy the worker with npm run deploy

Or deploy directly to Cloudflare

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.

1. Add a TXT record to your domain with the following values:

    - Name: `@`
    - Value: `v=spf1 a mx include:relay.mailchannels.net ~all`
   

Note: If you're facing Domain Lockdown error, follow the below steps:

1. Create a TXT record with the following values:

    - Name: `_mailchannels`
    - Value: `v=mc1 cfid=yourdomain.workers.dev` (the value of `cfid` will also be present in the error response)
   

Setup DKIM

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 to set up DKIM for your domain.

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 /api/email endpoint with the following parameters:

• Note you need to pass an Authorization header with the secure token you deployed. 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"
}