A robust, lightweight gRPC microservice built in Go for managing email templates, sending transactional emails via the Brevo API, and logging outgoing email events to a PostgreSQL database using GORM.
- Features
- Tech Stack
- Architecture & Directory Structure
- Prerequisites
- Environment Variables
- Getting Started
- gRPC API Specifications
- Testing with
grpcurl - Database Models
- License
- gRPC API: Fast, strongly-typed gRPC endpoints for adding templates and sending email notifications.
- Template Management: Store static and dynamic HTML email templates in PostgreSQL.
- Transactional Email Integration: Sends emails using Brevo (formerly Sendinblue) HTTP API.
- Outgoing Email Audit Log: Automatically records sent emails and recipient metrics in PostgreSQL.
- Input Validation: Enforces string and email format constraints using
buf.validate. - Clean Architecture: Separated into API, business service logic, data models, repositories, and configuration layers.
- Language: Go 1.25+
- API Protocol: gRPC & Protocol Buffers (v3)
- Database / ORM: PostgreSQL & GORM
- Email Service Provider: Brevo SDK / REST API
- Validation: buf.build protovalidate
- Messaging (Optional Config): RabbitMQ (amqp091-go)
go-email-service/
βββ api/ # Generated gRPC & Protobuf Go code
β βββ email/
β βββ emailservice.pb.go
β βββ emailservice_grpc.pb.go
βββ cmd/ # Application entry points
β βββ server/
β βββ main.go # Main server bootstrap
βββ internal/ # Private application and business logic
β βββ config/ # Service dependencies (DB, Brevo, RabbitMQ, Interceptor)
β β βββ brevo.go
β β βββ database.go
β β βββ loggingInterceptor.go
β β βββ rabbitmq.go
β βββ data/ # Persistence layer
β β βββ models/ # GORM database entities (EmailTemplate, OutgoingEmail)
β β βββ repositories/ # Data access interfaces and implementations
β βββ service/ # gRPC server implementation (EmailServer)
βββ proto/ # Protocol Buffer definitions
β βββ email/
β βββ emailservice.proto
βββ third_party/ # Protobuf third-party dependencies (protovalidate)
βββ .env.example # Sample environment configuration file
βββ Dockerfile # Container build file
βββ go.mod # Go module definition
βββ go.sum # Go dependency lock file
Before running the application, ensure you have the following installed:
- Go:
v1.25or higher - PostgreSQL: A running instance of PostgreSQL database
- Brevo Account: Active Brevo account and an API key with sending capabilities
Create a .env file in the root of the project using .env.example as a template:
cp .env.example .envConfigure the following variables in .env:
| Variable | Description | Example / Default |
|---|---|---|
DB_HOST |
PostgreSQL host address | localhost |
DB_USER |
PostgreSQL user | postgres |
DB_PASSWORD |
PostgreSQL user password | yourpassword |
DB_NAME |
Database name | email_service_db |
DB_PORT |
PostgreSQL port | 5432 |
BREVO_API_KEY |
Brevo API key | xkeysib-xxxxxxxx... |
BREVO_URL |
Brevo transactional email endpoint URL | https://api.brevo.com/v3/smtp/email |
SENDER_EMAIL |
Verified sender email address | no-reply@yourdomain.com |
RABBITMQ_URL (optional) |
RabbitMQ connection string | amqp://guest:guest@localhost:5672/ |
git clone https://github.com/TheDurodola/go-email-service.git
cd go-email-service
go mod downloadPopulate your .env file with your database credentials and Brevo API details.
Start the gRPC server:
go run cmd/server/main.goBy default, the gRPC server listens on TCP port :50051. Upon startup, GORM auto-migrates the database schemas (EmailTemplate and OutgoingEmail).
The gRPC definitions are declared in proto/email/emailservice.proto.
| Method | Request | Response | Description |
|---|---|---|---|
AddEmailTemplate |
EmailTemplateRequest |
EmailTemplateResponse |
Registers a new HTML email template in the database. |
SendEmail |
SendEmailRequest |
SendEmailResponse |
Retrieves a template by name, dispatches the email via Brevo, and logs the outgoing email. |
enum TemplateType {
STATIC = 0;
DYNAMIC = 1;
}
message EmailTemplateRequest {
string template_name = 1;
TemplateType template_type = 2;
string template_body = 3;
string template_subject = 4;
}message EmailTemplateResponse {
bool is_added = 1;
string message = 2;
}message SendEmailRequest {
string firstname = 1;
string to = 2; // Must be a valid email format
string template_name = 3;
string app_name = 4;
}message SendEmailResponse {
bool is_sent = 1;
}You can test the gRPC server directly using grpcurl.
grpcurl -plaintext -d '{
"template_name": "welcome_email",
"template_type": "STATIC",
"template_subject": "Welcome to Our Platform!",
"template_body": "<h1>Welcome</h1><p>Thank you for signing up!</p>"
}' localhost:50051 emailservice.EmailService/AddEmailTemplategrpcurl -plaintext -d '{
"firstname": "John",
"to": "user@example.com",
"template_name": "welcome_email",
"app_name": "MyAwesomeApp"
}' localhost:50051 emailservice.EmailService/SendEmailStores reusable HTML email templates.
| Field | Type | Description |
|---|---|---|
id |
uint |
Primary key (GORM) |
name |
string |
Unique template identifier (e.g. welcome_email) |
type |
string |
Template type (STATIC or DYNAMIC) |
subject |
string |
Email subject line |
body |
string |
HTML content of the email |
Logs outgoing emails for auditing and analytics.
| Field | Type | Description |
|---|---|---|
id |
uint |
Primary key (GORM) |
template_name |
string |
Template used for sending |
app_name |
string |
Application triggering the email |
recipient |
string |
Target email recipient |
first_name |
string |
Recipient's first name |
This project is open source and available under the standard MIT license.