https://github.com/winstxnhdw/mail-worker
A mail worker built with Cloudflare Workers and AWS SES.
https://github.com/winstxnhdw/mail-worker
aws-ses bun cloudflare-workers
Last synced: 6 months ago
JSON representation
A mail worker built with Cloudflare Workers and AWS SES.
- Host: GitHub
- URL: https://github.com/winstxnhdw/mail-worker
- Owner: winstxnhdw
- Created: 2023-03-25T14:57:23.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-22T17:03:22.000Z (6 months ago)
- Last Synced: 2025-04-22T18:30:00.209Z (6 months ago)
- Topics: aws-ses, bun, cloudflare-workers
- Language: TypeScript
- Homepage:
- Size: 2.61 MB
- Stars: 30
- Watchers: 4
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# mail-worker
[](https://github.com/winstxnhdw/mail-worker/actions/workflows/main.yml)
[](https://github.com/winstxnhdw/mail-worker/actions/workflows/deploy.yml)
[](https://github.com/winstxnhdw/mail-worker/actions/workflows/formatter.yml)
`mail-worker` is a robust [Cloudflare Worker](https://workers.cloudflare.com/) built for sending emails with [AWS SES](https://aws.amazon.com/ses/) and [Bun](https://github.com/oven-sh/bun).
## Development
Install all dependencies.
```bash
bun install
```
## Usage
`POST` **`/`** `(send email to recipient(s))`
### Request Headers
> | name | type | description |
> | ------------- | -------- | --------------------------------- |
> | Authorization | optional | `AUTH_TOKEN` environment variable |
### Parameters
#### MailRequestSchema
> | name | type | data type | description |
> | ----------- | -------- | ---------------| ----------------------------- |
> | from | required | `string` | sender's email address |
> | to | required | `string[]` | recipient's email address(es) |
> | cc | optional | `string[]` | cc recipient's email address |
> | bcc | optional | `string[]` | bcc recipient's email address |
> | subject | optional | `string` | email subject |
> | html | optional | `string` | email content |
> | attachments | optional | `Attachment[]` | email attachments |
#### AttachmentSchema
> | name | type | data type | description |
> | ----------- | -------- | ----------| ---------------------------------------- |
> | name | optional | `string` | name of the attachment |
> | content | required | `base64` | base64-encoded content of the attachment |
> | type | required | `string` | MIME type of the attachment |
### Responses
> | http code | content-type | reason |
> | --------- | ------------ | -------------------------------------------------------------------- |
> | `200` | `text/plain` | email sent successfully |
> | `400` | `text/plain` | invalid request body |
> | `401` | `text/plain` | invalid authentication token |
> | `500` | `text/plain` | AWS SES is unavailable/setup incorrectly or the sender is unverified |
### Example cURL
> ```bash
> curl $MAIL_WORKER_ENDPOINT -H "Content-Type: application/json" -d \
> '{
> "to": ["test@test.com"],
> "from": "test@test.com",
> "subject": "test",
> "html": "test"
> }'
> ```
### Example cURL with Attachment(s)
> ```bash
> curl $MAIL_WORKER_ENDPOINT -H "Content-Type: application/json" -d \
> '{
> "to": ["test@test.com"],
> "from": "test@test.com",
> "subject": "test",
> "html": "test",
> "attachments": [{"name": "text.txt", "type": "text/plain", "content": "SGVsbG8gV29ybGQ="}]
> }'
> ```
### Example cURL with Authentication
> ```bash
> curl $MAIL_WORKER_ENDPOINT \
> -H "Authorization: $AUTH_TOKEN" \
> -H "Content-Type: application/json" -d \
> '{
> "to": ["test@test.com"],
> "from": "test@test.com",
> "subject": "test",
> "html": "test"
> }'
> ```
## Setup
### Environment
Your worker must have the following environment variables.
```bash
echo $AWS_REGION | npx wrangler secret put AWS_REGION
echo $AWS_ACCESS_KEY_ID | npx wrangler secret put AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY | npx wrangler secret put AWS_SECRET_ACCESS_KEY
```
### Authentication
Optionally, you may secure your endpoint by setting the following environment variable.
```bash
echo $AUTH_TOKEN | npx wrangler secret put AUTH_TOKEN
```
## Verify Email
To use any sender email, the email must first be verified. The verification will require the following environment variables. You may populate your environment with the following.
```bash
{
echo "AWS_REGION=$AWS_REGION"
echo "AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID"
echo "AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY"
} > .env
```
Now, pipe your email to the `verify-email` script.
```bash
echo $EMAIL_ADDRESS | bun verify-email
```