https://github.com/4msar/email-api
Cloudflare email API worker
https://github.com/4msar/email-api
cloudflare cloudflare-email-sender email-api email-sender email-sending
Last synced: 21 days ago
JSON representation
Cloudflare email API worker
- Host: GitHub
- URL: https://github.com/4msar/email-api
- Owner: 4msar
- Created: 2026-07-03T17:55:30.000Z (22 days ago)
- Default Branch: main
- Last Pushed: 2026-07-03T18:57:43.000Z (22 days ago)
- Last Synced: 2026-07-03T20:20:12.437Z (22 days ago)
- Topics: cloudflare, cloudflare-email-sender, email-api, email-sender, email-sending
- Language: TypeScript
- Homepage: https://email-api.msar.me/
- Size: 32.2 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Cloudflare Email API
Minimal authenticated HTTP email API built with Cloudflare Workers and Cloudflare Email Service.
## Endpoints
- `GET /health`
- `POST /send`
## URLs
- Production: https://email-api.msar.me
- Development: https://email-api.msar.workers.dev
## Setup
### 1. Configure Cloudflare Email Service
Onboard your sending domain in Cloudflare Email Service.
Update `allowed_sender_addresses` in `wrangler.jsonc` to match your verified sender addresses.
### 2. Install dependencies
```bash
yarn install
```
### 3. Configure environment variables
The Worker requires three values: `API_KEY`, `FROM_EMAIL`, and `FROM_NAME`. These are declared in `wrangler.jsonc` and are not committed to the repo.
```jsonc
{
"secrets": {
"required": ["API_KEY", "FROM_EMAIL", "FROM_NAME"]
}
}
```
#### Local development
Copy the example file and set your values:
```bash
cp .dev.vars.example .dev.vars
```
```env
FROM_EMAIL=noreply@msar.me
FROM_NAME=Saiful Alam
API_KEY=replace-with-a-long-random-secret
```
Never commit `.dev.vars`.
#### Production
Set each value as a Wrangler secret:
```bash
yarn wrangler secret put API_KEY
yarn wrangler secret put FROM_EMAIL
yarn wrangler secret put FROM_NAME
# Inbound email forwarding
yarn wrangler secret put FORWARD_TO
```
`wrangler deploy` will fail if any required secret is missing.
### 4. Start development server
```bash
yarn dev
```
### 5. Deploy
```bash
yarn deploy
```
## Health check
```bash
curl https://email-api.msar.me/health
```
Response:
```json
{
"success": true,
"status": "ok"
}
```
## Send an email
```bash
curl -X POST \
"https://email-api.msar.me/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "recipient@example.com",
"subject": "Hello from Cloudflare",
"text": "Plain text fallback",
"html": "
Hello
Sent from my Worker.
",
"replyTo": "hello@msar.me"
}'
```
At least one of `text` or `html` is required.
## Successful response
```json
{
"success": true,
"message": "Email sent successfully",
"messageId": "..."
}
```
## Validation error
```json
{
"success": false,
"error": "A valid to email address is required"
}
```
## Unauthorized response
```json
{
"success": false,
"error": "Unauthorized"
}
```
## Security
The sender email address is configured server-side.
The API does not accept a `from` field from the request body.
The `/send` endpoint requires Bearer token authentication.
Do not expose the API key in frontend or browser-side JavaScript.
Use this API from trusted backend applications.