Skip to content

Commit 6f554e0

Browse files
ReneWerner87ReneWerner87
authored
Merge pull request #3048 from lee-lou2/feature/aws-ses-sender
feat: Add AWS SES Email Sender Recipe
2 parents 9ffed26 + d010ef3 commit 6f554e0

File tree

17 files changed

+1186
-0
lines changed

17 files changed

+1186
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Here you can find the most **delicious** recipes to cook delicious meals using o
2121
- [AWS Elastic Beanstalk](./aws-eb/README.md) - Deploying to AWS Elastic Beanstalk.
2222
- [AWS SAM](./aws-sam/README.md) - Serverless applications with AWS SAM.
2323
- [AWS SAM Container](./aws-sam-container/README.md) - Containerized serverless applications with AWS SAM.
24+
- [AWS SES Email Sender](./aws-ses-sender/README.md) - AWS SES-based Golang email delivery service. Provides email dispatch processing, status tracking, scheduled sending, and result analysis capabilities.
2425
- [Bootstrap](./bootstrap/README.md) - Integrating Bootstrap.
2526
- [Clean Architecture](./clean-architecture/README.md) - Implementing clean architecture in Go.
2627
- [Clean Code](./clean-code/README.md) - Implementing clean code in Go.

‎aws-ses-sender/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.idea
2+
.env

‎aws-ses-sender/Dockerfile‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
FROM golang:1.24 AS builder
2+
3+
WORKDIR /usr/src/app
4+
5+
COPY go.mod go.sum ./
6+
RUN go mod download && go mod verify
7+
8+
COPY . .
9+
10+
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .
11+
12+
FROM alpine:3.21
13+
14+
RUN apk --no-cache add ca-certificates
15+
16+
WORKDIR /root/
17+
18+
COPY --from=builder /usr/src/app/.env .env
19+
COPY --from=builder /usr/src/app/app .
20+
21+
CMD ["./app"]

‎aws-ses-sender/README.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: AWS SES Email Sender
3+
keywords: [aws, ses, golang, email, sender]
4+
description: AWS SES-based Golang email delivery service. Provides email dispatch processing, status tracking, scheduled sending, and result analysis capabilities.
5+
---
6+
7+
# AWS SES Email Sender
8+
9+
[![Github](https://img.shields.io/static/v1?label=&message=Github&color=2ea44f&style=for-the-badge&logo=github)](https://github.com/gofiber/recipes/tree/master/aws-ses-sender) [![StackBlitz](https://img.shields.io/static/v1?label=&message=StackBlitz&color=2ea44f&style=for-the-badge&logo=StackBlitz)](https://stackblitz.com/github/gofiber/recipes/tree/master/aws-ses-sender)
10+
11+
This is an AWS SES-based Golang email delivery service that extracts only the basic sending functionality from [my open-source project](https://github.com/lee-lou2/aws-ses-sender-go).
12+
13+
## Features
14+
- [x] Email sending using AWS SES
15+
- [x] Designed with daily limits and per-second sending rates in mind
16+
- [x] Scheduled sending and message grouping
17+
- [x] Email open tracking and result collection
18+
- [x] View daily sending counts and delivery results by message group
19+
20+
## Flowchart
21+
22+
```mermaid
23+
flowchart TD
24+
A[Client] -->|Email Send Request| B[API Server]
25+
B -->|DB Storage| C[Scheduler]
26+
C -->|Query Pending| D[Sender]
27+
D -->|SES Send| E[AWS SES]
28+
E -->|Email Received| F[Recipient]
29+
E -->|SNS Callback| G[API Server]
30+
G -->|DB Storage| H[Results/Statistics]
31+
F -->|Open Tracking| I[API Server]
32+
I -->|DB Storage| J[Open Events]
33+
H -->|Stats/Results Query| K[Client]
34+
J -->|Stats/Results Query| K[Client]
35+
```
36+
37+
## Requirements
38+
39+
### Essential Requirements
40+
- Go 1.22 or higher
41+
- AWS account and configuration
42+
- AWS SES service activated
43+
- Sender email or domain verification completed
44+
- IAM user with SES permissions
45+
- AWS Access Key and Secret Key
46+
- PostgreSQL 14.0 or higher
47+
- (Optional) Docker
48+
49+
### AWS SES Configuration
50+
1. Verify sender email/domain in AWS SES console
51+
2. Request removal from SES sandbox mode (for production)
52+
3. Create SNS topic and set up SES feedback notifications
53+
4. Grant following permissions to IAM user
54+
- `ses:SendEmail`
55+
- `ses:SendRawEmail`
56+
- `sns:Publish` (if using SNS for delivery notifications)
57+
- `sns:Subscribe` (if using SNS for delivery notifications)
58+
59+
## Project Structure
60+
```plaintext
61+
aws-ses-sender/
62+
├── main.go # Application entry point
63+
├── api/ # HTTP API related code
64+
│ ├── handler.go # API handler functions
65+
│ ├── route.go # API routing configuration
66+
│ ├── server.go # HTTP server setup/execution
67+
│ └── middlewares.go # API authentication middleware
68+
├── cmd/ # Background job code
69+
│ ├── scheduler.go # Pending email scheduler
70+
│ └── sender.go # SES email sending processor
71+
├── config/ # Application settings
72+
│ ├── env.go # Environment variable management
73+
│ └── db.go # Database connection settings
74+
├── model/ # Database models
75+
│ └── email.go # GORM model definitions
76+
└── pkg/aws/ # AWS service integration
77+
└── ses.go # SES email sending
78+
```
79+
80+
## Setup
81+
82+
### Prerequisites
83+
84+
- Go language development environment
85+
- AWS account and SES service configuration
86+
- Sender email/domain verification
87+
- IAM user creation with SES permissions
88+
- PostgreSQL database
89+
- (Optional) Sentry DSN
90+
91+
### Configuration
92+
93+
Create a `.env` file in the project root and set the following environment variables:
94+
95+
```env
96+
# AWS Related
97+
AWS_ACCESS_KEY_ID=your_access_key
98+
AWS_SECRET_ACCESS_KEY=your_secret_key
99+
AWS_REGION=ap-northeast-2
100+
[email protected]
101+
102+
# Server and API
103+
SERVER_PORT=3000
104+
API_KEY=your_api_key
105+
SERVER_HOST=http://localhost:3000
106+
107+
# Database (PostgreSQL)
108+
DB_HOST=localhost
109+
DB_PORT=5432
110+
DB_USER=postgres
111+
DB_PASSWORD=postgres
112+
DB_NAME=postgres
113+
114+
# Sending rate per second
115+
EMAIL_RATE=14
116+
117+
# Sentry (Optional)
118+
SENTRY_DSN=your_sentry_dsn
119+
```
120+
121+
### Installation and Execution
122+
123+
1. Clone repository:
124+
```bash
125+
git clone <repository_URL>
126+
cd aws-ses-sender
127+
```
128+
129+
2. Install dependencies:
130+
```bash
131+
go mod tidy
132+
```
133+
134+
3. Run application:
135+
```bash
136+
go run main.go
137+
```
138+
139+
## API Endpoints
140+
141+
### Email Sending Request
142+
```http
143+
POST /v1/messages
144+
```
145+
146+
Request body example:
147+
```json
148+
{
149+
"messages": [
150+
{
151+
"topicId": "promotion-event-2024",
152+
"emails": ["[email protected]", "[email protected]"],
153+
"subject": "Special Promotion Notice",
154+
"content": "<h1>Hello!</h1><p>Check out our special promotion details.</p>",
155+
"scheduledAt": "2024-12-25T10:00:00+09:00"
156+
}
157+
]
158+
}
159+
```
160+
161+
### View Topic Sending Statistics
162+
```http
163+
GET /v1/topics/:topicId
164+
```
165+
166+
### Email Open Tracking
167+
```http
168+
GET /v1/events/open?requestId={requestId}
169+
```
170+
171+
### View Sending Statistics
172+
```http
173+
GET /v1/events/counts/sent?hours={hours}
174+
```
175+
176+
### Receive Sending Results (AWS SNS)
177+
```http
178+
POST /v1/events/results
179+
```

0 commit comments

Comments
 (0)