Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/akashrajpurohit/email-server
📧 Free email proxy server powered by MailChannels and Cloudflare Workers
https://github.com/akashrajpurohit/email-server
cloudflare-workers email-server mailchannels
Last synced: 14 days ago
JSON representation
📧 Free email proxy server powered by MailChannels and Cloudflare Workers
- Host: GitHub
- URL: https://github.com/akashrajpurohit/email-server
- Owner: AkashRajpurohit
- License: mit
- Created: 2023-06-15T16:14:44.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-02T06:18:53.000Z (5 months ago)
- Last Synced: 2024-07-04T21:42:06.879Z (5 months ago)
- Topics: cloudflare-workers, email-server, mailchannels
- Language: TypeScript
- Homepage:
- Size: 196 KB
- Stars: 8
- Watchers: 3
- Forks: 9
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://blog.mailchannels.com/mailchannels-enables-free-email-sending-for-cloudflare-workers-customers) 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](https://support.mailchannels.com/hc/en-us/articles/26814255454093-End-of-Life-Notice-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.
[](https://deploy.workers.cloudflare.com/?url=https://github.com/AkashRajpurohit/email-server)
Another way is to [fork this repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) 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](https://docs.github.com/en/actions/learn-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`
## Domain Lockdown 🙅🏻♂️
Mailchannels imposes [domain lockdown](https://support.mailchannels.com/hc/en-us/articles/16918954360845-Secure-your-domain-name-against-spoofing-with-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
## Setup DKIM (Optional) 🏃🏻
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](https://support.mailchannels.com/hc/en-us/articles/7122849237389-Adding-a-DKIM-Signature) 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.
# 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](#cloudflare-worker). Like the following: `Authorization: TOKEN`
## Basic Email
The Most basic request would look like this:
```json
{
"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.
```json
{
"to": "[email protected]",
"from": "[email protected]",
"subject": "Hello World",
"html": "
Hello World
"
}
```
## 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.
```json
{
"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.
```json
{
"to": [
"[email protected]",
"[email protected]"
],
"from": "[email protected]",
"subject": "Hello World",
"text": "Hello World"
}
```
OR
```json
{
"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.
```json
{
"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.
```json
{
"to": "[email protected]",
"from": "[email protected]",
"replyTo": "[email protected]",
"subject": "Hello World",
"text": "Hello World"
}
```
# Technology Stack 💻
- Framework - [Hono](https://honojs.dev/)
- Deployment - [Cloudflare Workers](https://workers.cloudflare.com/)
# Bugs or Requests 🐛
If you encounter any problems feel free to open an [issue](https://github.com/AkashRajpurohit/email-server/issues/new?template=bug_report.md). If you feel the project is missing a feature, please raise a [ticket](https://github.com/AkashRajpurohit/email-server/issues/new?template=feature_request.md) on GitHub and I'll look into it. Pull requests are also welcome.
# Where to find me? 👀
[](https://akashrajpurohit.com/)
[](https://twitter.com/AkashWhoCodes)
[](https://linkedin.com/in/AkashRajpurohit)
[](https://instagram.com/akashwho.codes/)
[](https://t.me/AkashRajpurohit)