vrr/cf-emailrouter
2
0
Fork 0
mirror of https://github.com/kennyparsons/cf-emailrouter.git synced 2025-09-04 11:40:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merged post with readme

Browse source
This commit is contained in:
Kenny Parsons 2025-04-11 09:43:14 -05:00
parent 49b9119934
commit 02255d73fe
1 changed files with 96 additions and 70 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

166
README.md
View file

@ -1,17 +1,76 @@
# Email Router # Email Router
A Cloudflare Worker for routing emails based on dynamic configurations stored in KV. A Cloudflare Worker for dynamic email routing with on-the-fly alias creation.
## Features ## What is this?
- **Email Routing:** Processes incoming emails and forwards them based on configuration. Email Router is a Cloudflare Worker that lets you create and manage email aliases dynamically without having to update your worker code each time. Think of it like DuckDuckGo's email alias service, but with more powerful routing logic and customization options.
- **Configuration Management:** Manage email routing settings via API endpoints.
- **API Endpoints:** Under the hood, it's just a worker that accepts incoming emails from your Cloudflare zone. When configured with a catch-all rule in your zone, you can route any email address on your domain to this single worker, which then determines how to handle it based on configurations stored in KV.
- **GET /api/email/{email}**: Retrieve configuration data.
- **PUT /api/email/{email}**: Update configuration. ## Core Features
- **DELETE /api/email/{email}**: Delete configuration.
- **GET /api/email/list**: List all configurations. - **Dynamic Email Aliases**: Create unlimited email aliases on your domain without modifying the worker code
- **Filtering & Logging:** Supports filtering on email subjects and detailed logging for debugging. - **Granular Sender Control**: Allow or block specific domains and email addresses
- **Smart Routing**: Forward emails to one or more recipients based on custom rules
- **API Management**: RESTful API for creating, updating, and managing aliases
- **Configuration in KV**: All alias settings stored in Cloudflare KV for easy management
## How It Works
1. An email comes in to `purple.taco.engineer@yourdomain.com`
2. The worker looks up the configuration for this alias from KV storage
3. It checks if the sender is allowed based on the configuration rules
4. If allowed, it forwards the email to the designated recipient(s)
5. If denied, it rejects the email with an appropriate message
## Sample Configuration
Each alias is defined by a KV entry where the key is the email alias and the value is a JSON configuration object:
```javascript
{
"name": "Some Obscure Shopping Site",
"created": "2025-04-08T12:00:00Z",
"enabled": true,
"site_origin": "totallylegitshopping.domain",
"forward_to": ["user@example.com"],
"allow": {
"domains": ["totallylegitshopping.domain"],
"emails": ["admin@totallylegitshopping.domain"]
},
"deny": {
"domains": ["spam.com"],
"emails": ["spam@spam.com"]
},
"filtering": [
{
"subjectContains": "Important",
"action": "mark-important"
}
],
"junk": false,
"mailing_list": true,
"logging": {
"log_sender_domain": true,
"log_subject": false,
"log_body": false
}
}
```
Note: Currently, only the `enabled`, `forward_to`, `allow`, and `deny` fields are implemented. Other features will be added in future updates.
## API Endpoints
The worker exposes several API endpoints for managing configurations:
- **GET /api/email/{email}**: Retrieve configuration data for an alias
- **PUT /api/email/{email}**: Update configuration for an alias
- **DELETE /api/email/{email}**: Delete an alias configuration
- **GET /api/email/list**: List all configured aliases
All API endpoints are protected by an API key stored in a separate KV namespace.
## Setup ## Setup
@ -19,75 +78,42 @@ A Cloudflare Worker for routing emails based on dynamic configurations stored in
2. **Configuration:** 2. **Configuration:**
- Ensure `wrangler.toml` is configured with the correct project details and KV namespaces. Use wrangler-example.toml as a reference. - Ensure `wrangler.toml` is configured with the correct project details and KV namespaces. Use wrangler-example.toml as a reference.
- This project requires 2 KV namespaces. The wrangler-example.toml has the bindings, which are: - This project requires 2 KV namespaces:
- `EMAIL-KV`: For storing email routing configurations. - `EMAIL-KV`: For storing email routing configurations
- `API-AUTH`: API key management for authentication. - `API-AUTH`: API key management for authentication
- This KV is a personal decision, where all workers requiring auth have a KV of wokername:APIKEY
- As such, this is a single user worker, as it assumes 1 key per worker.
3. **Deploy:** 3. **Deploy:**
```sh ```sh
npx wrangler deploy npx wrangler deploy
``` ```
4. **Configure Email Routing in Cloudflare:**
- Set up a catch-all rule in your Cloudflare zone to direct all emails to this worker
## Project Structure ## Project Structure
- **src/index.js:** Main entry point handling HTTP routes and email events. - **src/index.js:** Main entry point handling HTTP routes and email events
- **src/schema.js:** Contains default configuration and helper utilities. - **src/schema.js:** Contains default configuration and helper utilities
- **wrangler.toml:** Configuration for Cloudflare Worker and KV namespaces. - **src/auth.js:** API key management and authentication
- **src/routes/email.js:** Handles email routing logic
- **src/routes/api.js:** API endpoints for managing configurations
- **wrangler.toml:** Configuration for Cloudflare Worker and KV namespaces
## Sample Configuration Using Schema ## Future Plans
Below is an example configuration object that follows the schema defined in `src/schema.js`. - Web UI with authentication/SSO for managing aliases and configurations
- Browser extension to detect the current website and create/retrieve aliases
```javascript - Advanced filtering options for incoming emails
// Sample configuration using the schema from src/schema.js - More comprehensive logging and analytics
const sampleConfig = {
name: "Example Email Route",
created: "2025-04-08T12:00:00Z", // ISO timestamp format
enabled: true,
site_origin: "https://example.com",
forward_to: ["user@example.com"],
allow: {
domains: ["example.com"],
emails: ["admin@example.com"]
},
deny: {
domains: ["spam.com"],
emails: ["spam@spam.com"]
},
filtering: [
{
subjectContains: "Important",
action: "mark-important"
}
],
junk: false,
mailing_list: true,
logging: {
log_sender_domain: true,
log_subject: false,
log_body: false
}
};
export default sampleConfig;
```
Note: At this time, the only features of the schema in use are:
- `enabled`
- `forward_to`
- `allow`
- `deny`
The other features will be implemented later.
## API Docs
TBD
## To Do ## To Do
- [ ] Add API documentation.
- [ ] Implement filtering and logging features. - [ ] Add comprehensive API documentation
- [ ] Switch if else to case statements for better readability. - [ ] Implement filtering and logging features
- [ ] Add UI for configuration management. - [ ] Switch if-else to case statements for better readability
- [ ] Add UI for configuration management
- [ ] Create browser extension for quick alias creation
## Contributing
PRs and suggestions are welcome! This project is in beta, so feedback is greatly appreciated.