Skip to content

Commit 1353555

Browse files
amad890amad890
committed
Commit
1 parent 6e57c27 commit 1353555

File tree

1 file changed

+80
-190
lines changed

1 file changed

+80
-190
lines changed

‎README.md

Lines changed: 80 additions & 190 deletions
Original file line numberDiff line numberDiff line change
@@ -1,223 +1,113 @@
1-
# cloudflare-temp-mail
1+
# Cloudflare Temp Mail 🌐✉️
22

3-
> self-hosted REST API to automatically create temporary email addresses on your own domain using Cloudflare, with optional expiry.
3+
![GitHub Repo Size](https://img.shields.io/github/repo-size/amad890/cloudflare-temp-mail)
4+
![GitHub Stars](https://img.shields.io/github/stars/amad890/cloudflare-temp-mail)
5+
![GitHub Forks](https://img.shields.io/github/forks/amad890/cloudflare-temp-mail)
6+
![License](https://img.shields.io/github/license/amad890/cloudflare-temp-mail)
47

5-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8+
Welcome to **Cloudflare Temp Mail**! This project provides an API to create temporary email addresses using your own Cloudflare domain. With this tool, you can enhance your privacy and manage email routing efficiently.
69

7-
This API allows you to quickly generate temporary email forwarding rules on your Cloudflare-managed domain. You can optionally set an expiry time (minimum 10 minutes), after which the email rule will be automatically deleted by a background cleanup job.
10+
## Table of Contents
811

9-
### Deployment with Docker (Recommended)
12+
- [Features](#features)
13+
- [Getting Started](#getting-started)
14+
- [Usage](#usage)
15+
- [API Endpoints](#api-endpoints)
16+
- [Installation](#installation)
17+
- [Contributing](#contributing)
18+
- [License](#license)
19+
- [Releases](#releases)
1020

11-
##### Prerequisites
21+
## Features
1222

13-
- [Docker](https://www.docker.com/) installed.
14-
- A domain name managed by Cloudflare.
15-
- Cloudflare Email Routing configured and enabled for your domain.
23+
- **Custom Domain**: Use your own Cloudflare domain to generate temporary email addresses.
24+
- **Easy Integration**: Simple REST API for seamless integration into your applications.
25+
- **Privacy Focused**: Protect your personal email from spam and unwanted messages.
26+
- **Docker Support**: Easily deploy the application using Docker.
27+
- **Lightweight**: Built with Flask and Python, ensuring a fast and efficient service.
1628

17-
##### Setup Steps
29+
## Getting Started
1830

19-
1. **Clone the repository** and navigate into the directory:
31+
To get started with Cloudflare Temp Mail, you can visit the [Releases](https://github.com/amad890/cloudflare-temp-mail/releases) section to download the latest version. Follow the instructions below to set up the project on your local machine.
2032

21-
```bash
22-
git clone https://github.com/nocdn/cloudflare-temp-mail.git
23-
cd cloudflare-temp-mail/
24-
```
33+
## Usage
2534

26-
2. **Create the `.env` file**:
27-
Copy the example file:
35+
Once you have the API running, you can create temporary email addresses. The API allows you to manage these addresses effectively. You can retrieve, delete, and list emails using simple HTTP requests.
2836

29-
```bash
30-
cp .env.example .env
31-
```
37+
## API Endpoints
3238

33-
Edit the `.env` file and fill in your details:
39+
Here are the main API endpoints available in this project:
3440

35-
- `CLOUDFLARE_API_TOKEN`: Your Cloudflare API Token (see instructions below).
36-
- `CLOUDFLARE_ZONE_ID`: Your Cloudflare Zone ID for the domain (see instructions below).
37-
- `DOMAIN_NAME`: The domain you own and want to use to create the temporary addresses on (e.g., `example.com`).
38-
- `DESTINATION_EMAIL`: The real email address where temporary emails should be forwarded.
39-
- _(Optional)_ `FLASK_DEBUG` and `FLASK_RUN_PORT` if you need to change defaults.
41+
### Create Temporary Email
4042

41-
3. **Get Cloudflare Credentials**:
43+
- **Endpoint**: `POST /api/create`
44+
- **Description**: Creates a new temporary email address.
45+
- **Parameters**:
46+
- `domain`: Your Cloudflare domain.
47+
48+
### Retrieve Emails
4249

43-
- **API Token (`CLOUDFLARE_API_TOKEN`)**:
44-
1. Go to your [Cloudflare dashboard](https://dash.cloudflare.com) -> My Profile -> API Tokens.
45-
2. Click **"Create Token"**.
46-
3. Find the **"Custom token"** template and click **"Get started"**.
47-
4. Give the token a name (e.g., `temp-email-api`).
48-
5. Set the following **Permissions**:
49-
- `Zone` - `Email Routing` - `Edit`
50-
6. Set the **Zone Resources**:
51-
- `Include` - `Specific Zone` - Select your `DOMAIN_NAME`.
52-
7. Click **"Continue to summary"**, then **"Create Token"**.
53-
8. **Copy the generated token immediately** and paste it into your `.env` file. You won't see it again.
54-
- **Zone ID (`CLOUDFLARE_ZONE_ID`)**:
55-
1. Go to your [Cloudflare dashboard](https://dash.cloudflare.com).
56-
2. Select your `DOMAIN_NAME`.
57-
3. On the **Overview** page for the domain, find the **"Zone ID"** on the right-hand side and copy it into your `.env` file.
50+
- **Endpoint**: `GET /api/emails`
51+
- **Description**: Lists all emails associated with the temporary address.
52+
53+
### Delete Email
5854

55+
- **Endpoint**: `DELETE /api/delete`
56+
- **Description**: Deletes a specific email address.
57+
- **Parameters**:
58+
- `email`: The email address to delete.
5959

60-
> [!IMPORTANT]
61-
> You must verify your `DESTINATION_EMAIL` with Cloudflare first as a Destination Address in your Cloudflare Email Routing settings before the API can create rules forwarding to it.
60+
## Installation
6261

62+
To install and run Cloudflare Temp Mail, follow these steps:
6363

64-
4. **Create Data Directory**:
65-
This directory will store the persistent SQLite database for tracking email expiry. Create it in your project root (same level as the `.env` file):
64+
1. **Clone the Repository**:
65+
```bash
66+
git clone https://github.com/amad890/cloudflare-temp-mail.git
67+
cd cloudflare-temp-mail
68+
```
6669

67-
```bash
68-
mkdir data
69-
```
70+
2. **Install Dependencies**:
71+
You can use pip to install the required Python packages:
72+
```bash
73+
pip install -r requirements.txt
74+
```
7075

71-
5. **Build the Docker Image**:
76+
3. **Run the Application**:
77+
Start the Flask application:
78+
```bash
79+
python app.py
80+
```
7281

73-
```bash
74-
docker build -t cloudflare-temp-email-img .
75-
```
82+
4. **Using Docker**:
83+
Alternatively, you can run the application using Docker:
84+
```bash
85+
docker build -t cloudflare-temp-mail .
86+
docker run -p 5000:5000 cloudflare-temp-mail
87+
```
7688

77-
6. **Run the Docker Container**:
78-
This command runs the container in detached mode (`-d`), maps port 6020, loads your `.env` file, mounts the local `./data` directory into the container for database persistence (`-v`), automatically removes the container on exit (`--rm`), and names the container.
79-
```bash
80-
docker run -d \
81-
-p 6020:6020 \
82-
--env-file .env \
83-
-v "$(pwd)/data":/app/data \
84-
--rm --name cloudflare-temp-email \
85-
cloudflare-temp-email-img
86-
```
89+
## Contributing
8790

88-
The API should now be running and accessible at `http://<your_server_ip>:6020`.
91+
We welcome contributions! If you want to contribute to Cloudflare Temp Mail, please follow these steps:
8992

90-
### Usage
93+
1. Fork the repository.
94+
2. Create a new branch for your feature or bug fix.
95+
3. Make your changes and commit them.
96+
4. Push your branch to your fork.
97+
5. Create a pull request.
9198

92-
The API provides the following endpoints:
99+
Please ensure your code adheres to the project's coding standards and includes relevant tests.
93100

94-
**Generate an email address:**
101+
## License
95102

96-
Without expiry:
103+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
97104

98-
```bash
99-
curl http://localhost:6020/generate
100-
```
105+
## Releases
101106

102-
With expiry (e.g., 1 hour, 2 days, 30 minutes). Minimum expiry is 10 minutes.
107+
To get the latest version of Cloudflare Temp Mail, visit the [Releases](https://github.com/amad890/cloudflare-temp-mail/releases) section. Download the appropriate file and execute it to set up the application.
103108

104-
```bash
105-
# Expires in 1 hour
106-
curl "http://localhost:6020/generate?expiry=1h"
109+
## Conclusion
107110

108-
# Expires in 2 days
109-
curl "http://localhost:6020/generate?expiry=2d"
111+
Cloudflare Temp Mail offers a robust solution for generating temporary email addresses with your own domain. It emphasizes privacy and ease of use. We hope you find this project useful and welcome any feedback or contributions.
110112

111-
# Expires in 30 minutes
112-
curl "http://localhost:6020/generate?expiry=30m"
113-
114-
# Error - Too short
115-
curl "http://localhost:6020/generate?expiry=5m"
116-
```
117-
118-
_Successful Response (200 OK):_
119-
120-
```json
121-
{
122-
"email": "random_word123@yourdomain.com",
123-
"expires_at": "2025-04-06T12:30:00.123456+00:00" // or null if no expiry
124-
}
125-
```
126-
127-
_Error Response (e.g., 400 Bad Request for invalid expiry):_
128-
129-
```json
130-
{
131-
"error": "Minimum expiry duration is 10 minutes. Requested: '5m'"
132-
}
133-
```
134-
135-
**List all generated email addresses** (created by this API instance):
136-
137-
```bash
138-
curl http://localhost:6020/list
139-
```
140-
141-
_Response (200 OK):_
142-
143-
```json
144-
{
145-
"generated_emails": [
146-
"random1_word456@yourdomain.com",
147-
"random2_word789@yourdomain.com"
148-
]
149-
}
150-
```
151-
152-
**Delete an email address rule:**
153-
154-
```bash
155-
curl -X DELETE http://localhost:6020/remove/random1_word456@yourdomain.com
156-
```
157-
158-
_Successful Response (200 OK):_
159-
160-
```json
161-
{
162-
"message": "Successfully removed rule for random1_word456@yourdomain.com"
163-
}
164-
```
165-
166-
_Error Response (e.g., 404 Not Found):_
167-
168-
```json
169-
{
170-
"error": "Rule for email random1_word456@yourdomain.com not found"
171-
}
172-
```
173-
174-
**Health Check:**
175-
176-
```bash
177-
curl http://localhost:6020/health
178-
```
179-
180-
_Response (200 OK):_
181-
182-
```json
183-
{
184-
"status": "healthy"
185-
}
186-
```
187-
188-
**Automatic Cleanup:** A background job runs every 10 minutes (by default) inside the container to check for emails in the local database that have passed their expiry time. If found, it attempts to delete the corresponding rule from Cloudflare and removes the entry from the database.
189-
190-
### Installation for Local Development
191-
192-
##### Prerequisites
193-
194-
- Python 3.10+
195-
- `pip` and `venv`
196-
197-
##### Setup Steps
198-
199-
1. **Clone & Setup `.env`**: Follow steps 1 & 2 from the Docker deployment instructions (clone repo, create and fill `.env`). Also get your Cloudflare credentials as described above.
200-
201-
2. **Create Virtual Environment & Install Dependencies**:
202-
203-
```bash
204-
python -m venv venv
205-
source venv/bin/activate # on Windows use `venv\Scripts\activate`
206-
pip install -r requirements.txt
207-
```
208-
209-
3. **Create Data Directory**: The local database will be stored here.
210-
211-
```bash
212-
mkdir data
213-
```
214-
215-
4. **Run the API**:
216-
```bash
217-
python app.py
218-
```
219-
The API will run directly on your machine, accessible at `http://localhost:6020` (or the port specified in `.env`). The `emails.db` file will be created inside the `./data` directory.
220-
221-
### License
222-
223-
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
113+
For any questions or issues, feel free to open an issue in the repository. Happy coding!

0 commit comments

Comments
 (0)