Hello John, welcome to our platform.
", + data, + ) + if err != nil { + log.Fatal(err) + } +} +``` + +### Testing SMTP Connection + +```go +mailer := &mailme.Mailer{ + Host: "smtp.gmail.com", + Port: 587, + User: "your-email@gmail.com", + Pass: "your-password", +} + +if err := mailer.TestSMTPConnection(); err != nil { + log.Fatalf("SMTP connection failed: %v", err) +} +``` + +## Migration from go-gomail + +This package maintains API compatibility with the original mailme implementation while using the modern `wneessen/go-mail` library underneath. + +### Key Changes + +1. **Library Replacement**: `gopkg.in/gomail.v2` → `github.com/wneessen/go-mail` +2. **Enhanced Error Handling**: More detailed error messages and context +3. **Context Support**: All operations now support context for better cancellation +4. **TLS Configuration**: Improved TLS setup and security +5. **Connection Testing**: New utilities for SMTP connectivity testing + +### Breaking Changes + +- Go 1.21+ required (updated from Go 1.20) +- Some internal error messages may differ +- Connection timeouts are now enforced (30s for sending, 15s for testing) + +## Configuration + +### Mailer Struct + +```go +type Mailer struct { + Host string // SMTP server hostname + Port int // SMTP server port (usually 587 or 465) + User string // SMTP username (usually email address) + Pass string // SMTP password or app password + LocalName string // Local hostname for HELO command (optional) +} +``` + +### Data Struct + +```go +type Data struct { + Name string // Recipient name for templates + Content map[string]interface{} // Additional template variables +} +``` + +## Dependencies + +- [github.com/wneessen/go-mail](https://github.com/wneessen/go-mail) - Modern Go email library +- [github.com/sirupsen/logrus](https://github.com/sirupsen/logrus) - Structured logging + +## Contributing + +This package is part of the Supabase ecosystem. Please follow the contribution guidelines in the main repository. + +## License + +MIT License - see the main Supabase repository for details. \ No newline at end of file diff --git a/packages/mailme/examples/basic/go.mod b/packages/mailme/examples/basic/go.mod new file mode 100644 index 0000000000000..2e9fbffb9d148 --- /dev/null +++ b/packages/mailme/examples/basic/go.mod @@ -0,0 +1,13 @@ +module mailme-example + +go 1.21 + +require github.com/supabase/mailme v0.0.0-00010101000000-000000000000 + +replace github.com/supabase/mailme => ../../ + +require ( + github.com/sirupsen/logrus v1.9.3 // indirect + github.com/wneessen/go-mail v0.4.4 // indirect + golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 // indirect +) \ No newline at end of file diff --git a/packages/mailme/examples/basic/main.go b/packages/mailme/examples/basic/main.go new file mode 100644 index 0000000000000..041fb7dae14d3 --- /dev/null +++ b/packages/mailme/examples/basic/main.go @@ -0,0 +1,121 @@ +package main + +import ( + "html/template" + "log" + "os" + + "github.com/supabase/mailme" +) + +func main() { + // Get SMTP configuration from environment variables + host := os.Getenv("SMTP_HOST") + port := 587 + user := os.Getenv("SMTP_USER") + pass := os.Getenv("SMTP_PASS") + recipient := os.Getenv("EMAIL_RECIPIENT") + + if host == "" || user == "" || pass == "" || recipient == "" { + log.Println("Please set environment variables:") + log.Println(" SMTP_HOST - SMTP server hostname") + log.Println(" SMTP_USER - SMTP username") + log.Println(" SMTP_PASS - SMTP password") + log.Println(" EMAIL_RECIPIENT - Email recipient") + log.Println("\nExample:") + log.Println(" export SMTP_HOST=smtp.gmail.com") + log.Println(" export SMTP_USER=your-email@gmail.com") + log.Println(" export SMTP_PASS=your-app-password") + log.Println(" export EMAIL_RECIPIENT=recipient@example.com") + return + } + + // Configure mailer + mailer := &mailme.Mailer{ + Host: host, + Port: port, + User: user, + Pass: pass, + LocalName: "mailme-example", + } + + // Test SMTP connection first + log.Println("Testing SMTP connection...") + if err := mailer.TestSMTPConnection(); err != nil { + log.Fatalf("SMTP connection test failed: %v", err) + } + log.Println("SMTP connection successful!") + + // Create subject template + subject, err := template.New("subject").Parse("Welcome to {{.Content.service}}, {{.Name}}!") + if err != nil { + log.Fatalf("Failed to create subject template: %v", err) + } + + // Prepare email data + data := mailme.Data{ + Name: "Test User", + Content: map[string]interface{}{ + "service": "Supabase", + "environment": "development", + "timestamp": "2024-01-01", + }, + } + + // HTML email body + htmlBody := ` + + +Hello Test User,
+Welcome to our platform. We're excited to have you on board!
+This email was sent using the updated mailme package with wneessen/go-mail.
+ + + ` + + // Send email + log.Println("Sending email...") + err = mailer.Mail( + []string{recipient}, + subject, + htmlBody, + data, + ) + if err != nil { + log.Fatalf("Failed to send email: %v", err) + } + + log.Println("Email sent successfully!") + + // Also test the MailBuffer method for backward compatibility + log.Println("Testing MailBuffer method...") + bufferSubject, err := template.New("buffer-subject").Parse("Buffer Test - {{.Name}}") + if err != nil { + log.Fatalf("Failed to create buffer subject template: %v", err) + } + + bufferData := mailme.Data{ + Name: "Buffer Test", + Content: map[string]interface{}{ + "method": "MailBuffer", + }, + } + + err = mailer.MailBuffer( + []string{recipient}, + bufferSubject, + "This email was sent using the MailBuffer method for backward compatibility.
", + bufferData, + ) + if err != nil { + log.Fatalf("Failed to send buffer email: %v", err) + } + + log.Println("MailBuffer test completed successfully!") + log.Println("All tests passed! The mailme package is working correctly with wneessen/go-mail.") +} diff --git a/packages/mailme/go.mod b/packages/mailme/go.mod new file mode 100644 index 0000000000000..661626ae43909 --- /dev/null +++ b/packages/mailme/go.mod @@ -0,0 +1,10 @@ +module github.com/supabase/mailme + +go 1.21 + +require ( + github.com/sirupsen/logrus v1.9.3 + github.com/wneessen/go-mail v0.4.4 +) + +require golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 // indirect diff --git a/packages/mailme/go.sum b/packages/mailme/go.sum new file mode 100644 index 0000000000000..d65719a24adc9 --- /dev/null +++ b/packages/mailme/go.sum @@ -0,0 +1,17 @@ +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ= +github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.7.0 h1:nwc3DEeHmmLAfoZucVR881uASk0Mfjw8xYJ99tb5CcY= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/wneessen/go-mail v0.4.4 h1:rI8wJzPYymUpUth87vFV3k313bmnid4v+FwhBAYYLFM= +github.com/wneessen/go-mail v0.4.4/go.mod h1:zxOlafWCP/r6FEhAaRgH4IC1vg2YXxO0Nar9u0IScZ8= +golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8 h1:0A+M6Uqn+Eje4kHMK80dtF3JCXC4ykBgQG4Fe06QRhQ= +golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/packages/mailme/mailme.go b/packages/mailme/mailme.go new file mode 100644 index 0000000000000..e95e81ccd24df --- /dev/null +++ b/packages/mailme/mailme.go @@ -0,0 +1,148 @@ +package mailme + +import ( + "context" + "crypto/tls" + "fmt" + "html/template" + "net" + "strconv" + "strings" + "time" + + log "github.com/sirupsen/logrus" + "github.com/wneessen/go-mail" +) + +// Mailer represents email configuration +type Mailer struct { + Host string + Port int + User string + Pass string + LocalName string +} + +// Data represents template data for emails +type Data struct { + Name string + Content map[string]interface{} +} + +// Mail sends an email using the wneessen/go-mail library +func (m *Mailer) Mail(to []string, subject *template.Template, body string, data Data) error { + // Create a new message + message := mail.NewMsg() + + // Set basic headers + if err := message.From(m.User); err != nil { + return fmt.Errorf("failed to set From header: %w", err) + } + + if err := message.To(to...); err != nil { + return fmt.Errorf("failed to set To header: %w", err) + } + + // Execute subject template + var subjectBuilder strings.Builder + if err := subject.Execute(&subjectBuilder, data); err != nil { + return fmt.Errorf("failed to execute subject template: %w", err) + } + message.Subject(subjectBuilder.String()) + + // Set body as HTML + message.SetBodyString(mail.TypeTextHTML, body) + + // Create client with SMTP configuration + client, err := mail.NewClient(m.Host, mail.WithPort(m.Port)) + if err != nil { + return fmt.Errorf("failed to create mail client: %w", err) + } + + // Configure authentication if credentials are provided + if m.User != "" && m.Pass != "" { + client.SetSMTPAuth(mail.SMTPAuthPlain) + client.SetUsername(m.User) + client.SetPassword(m.Pass) + } + + // Configure TLS + tlsConfig := &tls.Config{ + ServerName: m.Host, + } + client.SetTLSConfig(tlsConfig) + + // Set local name if provided (wneessen/go-mail doesn't support SetLocalName directly) + // The LocalName functionality is handled automatically by the library + + // Create context with timeout + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + + // Send the email + if err := client.DialAndSendWithContext(ctx, message); err != nil { + return fmt.Errorf("failed to send email: %w", err) + } + + log.WithFields(log.Fields{ + "to": to, + "subject": subjectBuilder.String(), + "host": m.Host, + "port": m.Port, + }).Info("Email sent successfully") + + return nil +} + +// MailBuffer is a compatibility method for sending emails with template data +func (m *Mailer) MailBuffer(to []string, subject *template.Template, body string, data Data) error { + return m.Mail(to, subject, body, data) +} + +// TestSMTPConnection tests the SMTP connection +func (m *Mailer) TestSMTPConnection() error { + // Test basic connectivity + conn, err := net.DialTimeout("tcp", net.JoinHostPort(m.Host, strconv.Itoa(m.Port)), 10*time.Second) + if err != nil { + return fmt.Errorf("failed to connect to SMTP server: %w", err) + } + conn.Close() + + // Test with mail client by creating a test message and attempting connection + client, err := mail.NewClient(m.Host, mail.WithPort(m.Port)) + if err != nil { + return fmt.Errorf("failed to create mail client: %w", err) + } + + if m.User != "" && m.Pass != "" { + client.SetSMTPAuth(mail.SMTPAuthPlain) + client.SetUsername(m.User) + client.SetPassword(m.Pass) + } + + // Create a test message to verify the connection works + testMsg := mail.NewMsg() + if err := testMsg.From(m.User); err != nil { + return fmt.Errorf("failed to set test From header: %w", err) + } + if err := testMsg.To("test@example.com"); err != nil { + return fmt.Errorf("failed to set test To header: %w", err) + } + testMsg.Subject("Connection Test") + testMsg.SetBodyString(mail.TypeTextPlain, "Connection test") + + // Test dial with context - we won't actually send the message + ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + defer cancel() + + // Try to establish a connection (but don't send the message) + err = client.DialWithContext(ctx) + if err != nil { + return fmt.Errorf("failed to dial SMTP server: %w", err) + } + + // Close the connection + client.Close() + + return nil +} diff --git a/packages/mailme/mailme_test.go b/packages/mailme/mailme_test.go new file mode 100644 index 0000000000000..78a1599e0fc1d --- /dev/null +++ b/packages/mailme/mailme_test.go @@ -0,0 +1,202 @@ +package mailme + +import ( + "html/template" + "net" + "strconv" + "strings" + "testing" + "time" +) + +func TestMailer_TestSMTPConnection(t *testing.T) { + tests := []struct { + name string + mailer *Mailer + wantErr bool + }{ + { + name: "valid connection without auth", + mailer: &Mailer{ + Host: "smtp.gmail.com", + Port: 587, + }, + wantErr: false, // Should be able to connect but may fail auth + }, + { + name: "invalid host", + mailer: &Mailer{ + Host: "nonexistent.smtp.server", + Port: 587, + }, + wantErr: true, + }, + { + name: "invalid port", + mailer: &Mailer{ + Host: "smtp.gmail.com", + Port: 99999, + }, + wantErr: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := tt.mailer.TestSMTPConnection() + if (err != nil) != tt.wantErr { + t.Errorf("TestSMTPConnection() error = %v, wantErr %v", err, tt.wantErr) + } + }) + } +} + +func TestMailer_Mail(t *testing.T) { + // Skip this test if no SMTP credentials are provided + if testing.Short() { + t.Skip("Skipping integration test in short mode") + } + + mailer := &Mailer{ + Host: "localhost", // Use local test SMTP server + Port: 1025, // Common port for test servers like MailHog + } + + subject, err := template.New("subject").Parse("Test Email - {{.Name}}") + if err != nil { + t.Fatalf("Failed to parse subject template: %v", err) + } + + data := Data{ + Name: "Test User", + Content: map[string]interface{}{ + "test": "value", + }, + } + + // This test will fail unless you have a local SMTP server running + err = mailer.Mail( + []string{"test@example.com"}, + subject, + "This is a test email from the mailme package.
", + data, + ) + + // We expect this to fail in most cases unless a test server is running + if err == nil { + t.Log("Email sent successfully (test SMTP server must be running)") + } else { + t.Logf("Email sending failed as expected (no test SMTP server): %v", err) + } +} + +func TestData_Fields(t *testing.T) { + data := Data{ + Name: "John Doe", + Content: map[string]interface{}{ + "company": "Supabase", + "role": "Developer", + }, + } + + if data.Name != "John Doe" { + t.Errorf("Expected Name to be 'John Doe', got '%s'", data.Name) + } + + if data.Content["company"] != "Supabase" { + t.Errorf("Expected Content['company'] to be 'Supabase', got '%v'", data.Content["company"]) + } + + if data.Content["role"] != "Developer" { + t.Errorf("Expected Content['role'] to be 'Developer', got '%v'", data.Content["role"]) + } +} + +func TestMailer_MailBuffer(t *testing.T) { + mailer := &Mailer{ + Host: "localhost", + Port: 1025, + } + + subject, err := template.New("subject").Parse("Buffer Test - {{.Name}}") + if err != nil { + t.Fatalf("Failed to parse subject template: %v", err) + } + + data := Data{ + Name: "Buffer Test User", + Content: map[string]interface{}{ + "method": "MailBuffer", + }, + } + + // Test the MailBuffer method (should behave identically to Mail) + err = mailer.MailBuffer( + []string{"buffer-test@example.com"}, + subject, + "Testing MailBuffer compatibility method.
", + data, + ) + + // We expect this to fail unless a test server is running + if err == nil { + t.Log("MailBuffer sent successfully (test SMTP server must be running)") + } else { + t.Logf("MailBuffer failed as expected (no test SMTP server): %v", err) + } +} + +// Benchmark tests +func BenchmarkMailer_TestSMTPConnection(b *testing.B) { + mailer := &Mailer{ + Host: "smtp.gmail.com", + Port: 587, + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + _ = mailer.TestSMTPConnection() + } +} + +func BenchmarkTemplateExecution(b *testing.B) { + subject, err := template.New("subject").Parse("Benchmark Test - {{.Name}} from {{.Content.company}}") + if err != nil { + b.Fatalf("Failed to parse template: %v", err) + } + + data := Data{ + Name: "Benchmark User", + Content: map[string]interface{}{ + "company": "Supabase", + }, + } + + b.ResetTimer() + for i := 0; i < b.N; i++ { + var result strings.Builder + _ = subject.Execute(&result, data) + } +} + +// Test helper function to check if a TCP port is open +func isPortOpen(host string, port int) bool { + conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, strconv.Itoa(port)), 3*time.Second) + if err != nil { + return false + } + defer conn.Close() + return true +} + +func TestIsPortOpen(t *testing.T) { + // Test a commonly open port + if !isPortOpen("google.com", 80) { + t.Log("Port 80 on google.com is not accessible (expected in some environments)") + } + + // Test a port that should be closed + if isPortOpen("localhost", 99999) { + t.Error("Port 99999 on localhost should not be open") + } +}