email

README

Email Service Package

Package email cung cấp abstraction layer để gửi email với hỗ trợ nhiều provider khác nhau.

Providers Hỗ Trợ

• ✅ SMTP (standard protocol)
• ✅ SendGrid API
• ✅ AWS Simple Email Service (SES)
• ✅ Mailgun API

Tính Năng

• Gửi email đơn giản với HTML hoặc plain text
• Gửi hàng loạt (bulk sending)
• File đính kèm (attachments)
• Custom headers
• Priority levels
• Validation địa chỉ email

Sử Dụng Cơ Bản

import "github.com/vhvplatform/go-shared/email"

// Tạo client với SMTP
client, err := email.NewClient(email.Config{
    Provider: email.ProviderSMTP,
    From:     "noreply@example.com",
    Options: map[string]string{
        "host": "smtp.gmail.com",
        "port": "587",
        "username": "your-email@gmail.com",
        "password": "your-app-password",
    },
})

// Tạo và gửi message
msg := &email.Message{
    From:    "noreply@example.com",
    To:      []string{"user@example.com"},
    Subject: "Welcome!",
    Body:    "<h1>Welcome to our service</h1>",
    HTML:    true,
}

result, err := client.Send(ctx, msg)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Email sent with ID: %s\n", result.MessageID)

Cấu Hình Providers

SMTP

config := email.Config{
    Provider: email.ProviderSMTP,
    Options: map[string]string{
        "host": "smtp.example.com",
        "port": "587",
        "username": "user",
        "password": "pass",
        "use_tls": "true",
    },
}

SendGrid

config := email.Config{
    Provider: email.ProviderSendGrid,
    Options: map[string]string{
        "api_key": "your-sendgrid-api-key",
    },
}

AWS SES

config := email.Config{
    Provider: email.ProviderAWSSES,
    Options: map[string]string{
        "region": "us-east-1",
        "access_key_id": "your-access-key",
        "secret_access_key": "your-secret-key",
    },
}

Gửi với Attachments

msg := &email.Message{
    From:    "noreply@example.com",
    To:      []string{"user@example.com"},
    Subject: "Invoice",
}

// Đọc file
fileContent, _ := os.ReadFile("invoice.pdf")

// Thêm attachment
msg.AddAttachment("invoice.pdf", fileContent, "application/pdf")

client.Send(ctx, msg)

Gửi Hàng Loạt

messages := []*email.Message{
    {To: []string{"user1@example.com"}, Subject: "Hello 1", Body: "Content 1"},
    {To: []string{"user2@example.com"}, Subject: "Hello 2", Body: "Content 2"},
}

results, err := client.SendBulk(ctx, messages)
for _, result := range results {
    fmt.Printf("Sent: %s\n", result.MessageID)
}

Status

🚧 In Development - Hiện tại package đã có interfaces và structures sẵn sàng, implementations cho các providers đang được phát triển.

Documentation

Overview

Package email provides an abstraction layer for sending emails with support for multiple providers (SMTP, SendGrid, AWS SES, etc.)

Index

• type AWSSESConfig
• type Attachment
• type Client
  • func NewClient(config Config) (Client, error)
• type Config
• type MailgunConfig
• type Message
  • func (m *Message) AddAttachment(filename string, content []byte, contentType string)
  • func (m *Message) AddHeader(key, value string)
  • func (m *Message) SetHTML(html string)
  • func (m *Message) SetText(text string)
  • func (m *Message) Validate() error
• type Priority
• type Provider
• type SMTPConfig
• type SendGridConfig
• type SendResult

Types

type AWSSESConfig

type AWSSESConfig struct {
	Region          string // AWS region
	AccessKeyID     string // AWS access key ID
	SecretAccessKey string // AWS secret access key
	ConfigSetName   string // Optional configuration set name
}

AWSSESConfig contains AWS SES-specific configuration

type Attachment

type Attachment struct {
	Filename    string // Filename to display
	Content     []byte // File content
	ContentType string // MIME type
}

Attachment represents an email attachment

type Client

type Client interface {
	// Send sends an email message
	Send(ctx context.Context, msg *Message) (*SendResult, error)

	// SendBulk sends multiple emails in batch
	SendBulk(ctx context.Context, messages []*Message) ([]*SendResult, error)

	// ValidateAddress checks if an email address is valid
	ValidateAddress(email string) error

	// Close closes the email client and releases resources
	Close() error
}

Client is the interface that all email providers must implement

func NewClient

func NewClient(config Config) (Client, error)

NewClient creates a new email client based on the provider

type Config

type Config struct {
	Provider Provider          // Email provider to use
	From     string            // Default sender address
	Options  map[string]string // Provider-specific options
}

Config contains configuration for email client

type MailgunConfig

type MailgunConfig struct {
	Domain    string // Mailgun domain
	APIKey    string // Mailgun API key
	PublicKey string // Mailgun public key
	BaseURL   string // Mailgun API base URL (optional)
}

MailgunConfig contains Mailgun-specific configuration

type Message

type Message struct {
	From        string            // Sender email address
	To          []string          // Recipient email addresses
	CC          []string          // Carbon copy recipients
	BCC         []string          // Blind carbon copy recipients
	Subject     string            // Email subject
	Body        string            // Email body (plain text or HTML)
	HTML        bool              // Whether body is HTML
	Attachments []Attachment      // File attachments
	Headers     map[string]string // Custom email headers
	ReplyTo     string            // Reply-to address
	Priority    Priority          // Email priority
}

Message represents an email message

func (*Message) AddAttachment

func (m *Message) AddAttachment(filename string, content []byte, contentType string)

AddAttachment adds a file attachment to the message

func (*Message) AddHeader

func (m *Message) AddHeader(key, value string)

AddHeader adds a custom header to the message

func (*Message) SetHTML

func (m *Message) SetHTML(html string)

SetHTML sets the message body as HTML

func (*Message) SetText

func (m *Message) SetText(text string)

SetText sets the message body as plain text

func (*Message) Validate

func (m *Message) Validate() error

Validate checks if a message is valid

type Priority

type Priority int

Priority represents email priority level

const (
	// PriorityLow indicates low priority email
	PriorityLow Priority = iota
	// PriorityNormal indicates normal priority email
	PriorityNormal
	// PriorityHigh indicates high priority email
	PriorityHigh
)

type Provider

type Provider string

Provider represents an email service provider

const (
	// ProviderSMTP uses standard SMTP protocol
	ProviderSMTP Provider = "smtp"
	// ProviderSendGrid uses SendGrid API
	ProviderSendGrid Provider = "sendgrid"
	// ProviderAWSSES uses AWS Simple Email Service
	ProviderAWSSES Provider = "aws_ses"
	// ProviderMailgun uses Mailgun API
	ProviderMailgun Provider = "mailgun"
)

type SMTPConfig

type SMTPConfig struct {
	Host     string // SMTP server hostname
	Port     int    // SMTP server port
	Username string // SMTP username
	Password string // SMTP password
	UseTLS   bool   // Whether to use TLS
}

SMTPConfig contains SMTP-specific configuration

type SendGridConfig

type SendGridConfig struct {
	APIKey string // SendGrid API key
}

SendGridConfig contains SendGrid-specific configuration

type SendResult

type SendResult struct {
	MessageID string    // Unique message identifier
	SentAt    time.Time // Time when email was sent
	Provider  Provider  // Provider used to send the email
}

SendResult contains the result of an email send operation