Temp Mail Worker

Cloudflare Worker that acts as a temporary email inbox.

API documentation: https://api.barid.site

AI-made web client: https://web.barid.site

Table of Contents

• Features
• Supporters
• Community
• Setup Guide
  • Prerequisites
  • Project Setup
  • Cloudflare Configuration
    • D1 Database Setup
    • KV Namespace Setup
    • R2 Bucket Setup
    • Email Routing Setup
• Running the Worker
  • Cloudflare Information Script (Optional)
  • Telegram Logging (Optional)
  • Local Development
  • Deployment

---

Features

• Receives emails via Cloudflare Email Routing.
• Stores email data in a Cloudflare D1 database.
• Attachment Support: Stores email attachments up to 50MB in Cloudflare R2.
• Provides comprehensive API endpoints for emails and attachments.
• Automatically cleans up old emails and attachments.
• Supports multiple file types including documents, images, and archives.

Supporters

A big thank you to the individuals who have donated domains to support this project. Your contributions help keep this service running.

Domain	Donated by
barid.site	vwh
vwh.sh	vwh
iusearch.lol	vwh
lifetalk.us	mm6x
z44d.pro	z44d
wael.fun	blockton
tawbah.site	HprideH
kuruptd.ink	HprideH

How to Donate a Domain

If you have an unused domain and would like to contribute, you can donate it by following these steps:

1. Create a Pull Request: Add your domain and owner information to the config/domains.ts file in the src directory.
2. Nameserver Provisioning: After your pull request, we will provide you with the nameservers to update for your domain.

---

Community

Here are some projects built by the community using or integrating with Temp Mail Worker:

• Rust Library: doomed-neko/tmapi
• Go Library: blockton/barid
• Python Library: superhexa/barid-client
• CLI App: doomed-neko/tmcli

---

Setup Guide

Prerequisites

Before you begin, ensure you have the following:

• Bun: Installed on your system.
• Cloudflare Account: With access to Workers, Email Routing, and D1.

Project Setup

1. Install Dependencies: Install the necessary JavaScript dependencies.

   bun install

2. Login to Cloudflare: You need to log in to your Cloudflare account via Wrangler. This will open a browser for authentication.

   bun wrangler login

Cloudflare Configuration

D1 Database Setup

1. Create the D1 database:

   bun run db:create

2. Copy the database_id: From the output of the above command.
3. Update wrangler.jsonc: Open wrangler.jsonc and replace database_id with the database_id you just copied.
4. Apply Database Schema:

   bun run db:tables

5. Apply Database Indexes:

   bun run db:indexes

KV Namespace Setup

1. Create the KV Namespace:

   bun run kv:create

2. Copy the id: From the output of the above command.
3. Update wrangler.jsonc: Open wrangler.jsonc and replace id and preview_id with the id you just copied.

R2 Bucket Setup

1. Create the R2 Bucket:

   bun run r2:create

2. Create Preview Bucket (for development):

   bun run r2:create-preview

Email Routing Setup

1. Go to your Cloudflare Dashboard: Select your domain (example.com).
2. Navigate to "Email" -> "Email Routing".
3. Enable Email Routing if it's not already enabled.
4. Create a Catch-all Rule:
   • For "Action", choose "Send to Worker".
   • Select your Worker (e.g., temp-mail).
   • Click "Save".

Running the Worker

Cloudflare Information Script (Optional)

To check your Cloudflare Workers, D1 databases, KV namespaces, and domain information directly from your terminal, you can use the cf-info script.

1. Configure API Credentials: Add your Cloudflare Account ID and an API Token with appropriate permissions (e.g., Zone:Read, Worker Scripts:Read, D1:Read, KV Storage:Read, Zone:Email:Read) to your .dev.vars file.

   Example .dev.vars additions:

   CLOUDFLARE_ACCOUNT_ID="YOUR_CLOUDFLARE_ACCOUNT_ID"
   CLOUDFLARE_API_TOKEN="YOUR_CLOUDFLARE_API_TOKEN"
   

2. Run the Script:

   bun run cf-info

Telegram Logging (Optional)

If you wish to enable Telegram logging for your worker, follow these steps:

1. Enable Logging in wrangler.jsonc: Ensure TELEGRAM_LOG_ENABLE is set to true in your wrangler.jsonc file under the vars section.

2. Local Development (.dev.vars): For local development, create a .dev.vars file in your project root with your Telegram bot token and chat ID. This file is used by bun dev.

   Example .dev.vars:

   TELEGRAM_BOT_TOKEN="YOUR_TELEGRAM_BOT_TOKEN"
   TELEGRAM_CHAT_ID="YOUR_TELEGRAM_CHAT_ID"
   

3. Production Deployment (Secrets): For production, you must set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID as secrets using wrangler. This securely stores your sensitive information with Cloudflare.

   Run the following commands in your terminal and enter the respective values when prompted:

   bun wrangler secret put TELEGRAM_BOT_TOKEN
   bun wrangler secret put TELEGRAM_CHAT_ID

Local Development

To run the worker locally:

bun run dev

Deployment

To deploy your worker to Cloudflare:

bun run deploy

Available Scripts

Development & Deployment

• bun run dev - Start local development server
• bun run deploy - Deploy to Cloudflare Workers
• bun run tail - View live logs from deployed worker

Database Management

• bun run db:create - Create D1 database
• bun run db:tables - Apply database schema
• bun run db:indexes - Apply database indexes
• bun run db:migrate-attachments - Add attachment support to existing database

Storage Setup

• bun run kv:create - Create KV namespace
• bun run r2:create - Create R2 bucket for attachments
• bun run r2:create-preview - Create R2 preview bucket

Code Quality

• bun run check - Run all linting and formatting checks
• bun run lint - Run ESLint
• bun run lint:fix - Fix ESLint issues
• bun run format - Format code with Prettier
• bun run tsc - Run TypeScript compiler

Utilities

• bun run cf-info - Display Cloudflare account information
• bun run cf-typegen - Generate TypeScript types for Cloudflare bindings

API Endpoints

Email Endpoints

• GET /emails/{emailAddress} - Get emails for a specific address
• GET /emails/count/{emailAddress} - Get email count for a specific address
• GET /inbox/{emailId} - Get a specific email by ID
• DELETE /emails/{emailAddress} - Delete all emails for a specific address
• DELETE /inbox/{emailId} - Delete a specific email by ID
• GET /domains - Get list of supported domains

Attachment Endpoints

• GET /emails/{emailAddress}/attachments - Get all attachments for emails sent to a specific address
• GET /inbox/{emailId}/attachments - Get attachments for a specific email
• GET /attachments/{attachmentId} - Download a specific attachment
• DELETE /attachments/{attachmentId} - Delete a specific attachment

Attachment Features

• File Size Limit: Up to 50MB per attachment
• File Count Limit: Up to 10 attachments per email
• Supported File Types:
  • Images: JPEG, PNG, GIF, WebP, SVG
  • Documents: PDF, TXT, CSV, Word, Excel, PowerPoint
  • Archives: ZIP, RAR, 7Z
  • Other: JSON, XML

Health Check

• GET /health - Service health status

For complete API documentation with examples, visit: https://api.barid.site