gomail

README

GoMail - Email Sender Library

Project Description

This project provides implementations for sending emails using different services including SMTP, Gmail API, Microsoft Graph API, SendGrid, AWS SES, Mailgun, Mandrill, Postmark, and SparkPost. Each implementation follows a common interface, allowing for flexibility and easy integration with various email services.

Features

• Send emails using various providers: SMTP, Gmail API, Microsoft Graph API, SendGrid, AWS SES, Mailgun, Mandrill, Postmark, SparkPost.
• Support for attachments and both plain text and HTML content.
• Easy configuration and setup.

Getting Started

Prerequisites

• Go 1.22+
• Access to the relevant email service provider (SMTP server, Gmail, Microsoft 365, SendGrid, AWS SES, Mailgun, Mandrill, Postmark, SparkPost)

Download

go get github.com/darkrockmountain/gomail 

• Alternatively download repository:

  git clone https://github.com/darkrockmountain/gomail.git
  cd gomail
  

Install dependencies

go mod tidy

Usage

1. SMTP Email Sender

• Configure your SMTP server settings in providers/smpt/smtp_email_sender.go.
• Refer to the SMTP Credentials Documentation for details on obtaining credentials.
• Run the smtpExample() function to send a test email.

2. Gmail Email Sender

• Configure your Gmail API credentials in providers/gmail/gmail_email_sender.go.
• Refer to the Gmail Credentials Documentation for details on obtaining credentials.
• Run the gExample() function to send a test email.

3. Gmail Email Sender using OAuth2

• Configure your Gmail API credentials and token in providers/gmail/gmail_email_sender_oauth2.go.
• Refer to the Gmail OAuth2 Credentials Documentation for details on obtaining credentials.
• Run the gExampleOauth2() function to send a test email.

4. Microsoft 365 Email Sender

• Configure your Microsoft Graph API credentials in providers/microsoft365/microsoft365_email_sender.go.
• Refer to the Microsoft 365 Credentials Documentation for details on obtaining credentials.
• Run the msGraphExample() function to send a test email.

5. SendGrid Email Sender

• Configure your SendGrid API key in providers/sendgrid/sendgrid_email_sender.go.
• Refer to the SendGrid Credentials Documentation for details on obtaining credentials.
• Run the sendgridExample() function to send a test email.

6. AWS SES Email Sender

• Configure your AWS SES credentials in providers/ses/ses_email_sender.go.
• Refer to the AWS SES Credentials Documentation for details on obtaining credentials.
• Run the sesExample() function to send a test email.

7. Mailgun Email Sender

• Configure your Mailgun API key in providers/mailgun/mailgun_email_sender.go.
• Refer to the Mailgun Credentials Documentation for details on obtaining credentials.
• Run the mailgunExample() function to send a test email.

8. Mandrill Email Sender

• Configure your Mandrill API key in providers/mandrill/mandrill_email_sender.go.
• Refer to the Mandrill Credentials Documentation for details on obtaining credentials.
• Run the mandrillExample() function to send a test email.

9. Postmark Email Sender

• Configure your Postmark API key in providers/postmark/postmark_email_sender.go.
• Refer to the Postmark Credentials Documentation for details on obtaining credentials.
• Run the postmarkExample() function to send a test email.

10. SparkPost Email Sender

• Configure your SparkPost API key in providers/sparkpost/sparkpost_email_sender.go.
• Refer to the SparkPost Documentation for details on obtaining credentials.
• Run the sparkpostExample() function to send a test email.

Documentation

For detailed instructions on obtaining the necessary credentials for each implementation, refer to the respective documentation files in the docs directory.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Error Handling and Troubleshooting

Common Errors

• Authentication Failed: Ensure your API keys and credentials are correct and have the necessary permissions.
• Network Issues: Verify your network connectivity and ensure your server can reach the email service provider.
• Invalid Email Addresses: Check that all email addresses are correctly formatted.
• Attachment Issues: Ensure attachments are correctly encoded and within size limits.

Troubleshooting Tips

1. Check Logs: Always check your application logs for detailed error messages.
2. Validate Credentials: Double-check your credentials and permissions.
3. API Limits: Ensure you are not exceeding API rate limits or quotas.
4. Service Status: Verify that the email service provider is operational and not experiencing downtime.

Security Best Practices

1. Environment Variables: Use environment variables to store credentials.
2. Secret Managers: Use secret management services like AWS Secrets Manager, Google Secret Manager, or HashiCorp Vault.
3. Encryption: Encrypt sensitive information both at rest and in transit.
4. Least Privilege: Follow the principle of least privilege for API keys and credentials.

Documentation

Overview

Package gomail provides a unified interface for sending emails using various providers.

Overview

The gomail project allows you to send emails using different email providers such as Gmail, SendGrid, AWS SES, and others. It abstracts the provider-specific details and provides a simple API for sending emails.

This project is organized into several packages:

• providers: Contains implementations for various email providers.
• credentials: Contains implementations for managing email credentials.
• examples: Contains example applications demonstrating how to use the library.
• docs: Contains documentation for configuring different email providers.
• common: Contains shared utilities and types used across the project.
• sanitizer: Contains implementations for sanitizing email content.

Usage

To use the library, you need to import the desired provider package and create an instance of the email sender for your desired provider, then call the SendEmail function.

Example:

package main

import (
    "github.com/darkrockmountain/gomail/providers/sendgrid"
)

func main() {
    sender := sendgrid.NewSendGridEmailSender("your-api-key")
    err := sender.SendEmail(gomail.NewEmailMessage("sender@example.com", []string{"recipient@example.com"}, "Subject", "Email body"))
    if err != nil {
        log.Fatal(err)
    }
}

This library supports various email providers and can be extended to include more.

Supported Providers

• Gmail
• SendGrid
• AWS SES
• Mailgun
• Mandrill
• Postmark
• Microsoft365
• SparkPost
• SMTP

For more details, see the documentation for each provider in the providers package.

Index

• func BuildMimeMessage(message *EmailMessage) ([]byte, error)
• func GetMimeType(filename string) string
• func ValidateEmail(email string) string
• func ValidateEmailSlice(emails []string) []string
• type Attachment
  • func NewAttachment(filename string, content []byte) *Attachment
  • func NewAttachmentFromFile(filePath string) (*Attachment, error)
• type EmailMessage
  • func NewEmailMessage(from string, to []string, subject string, body string) *EmailMessage
  • func NewFullEmailMessage(from string, to []string, subject string, cc []string, bcc []string, ...) *EmailMessage
• type EmailSender

Functions

func BuildMimeMessage

func BuildMimeMessage(message *EmailMessage) ([]byte, error)

BuildMimeMessage constructs the MIME message for the email, including text, HTML, and attachments. This function builds a multipart MIME message based on the provided email message. It supports plain text, HTML content, and multiple attachments.

Parameters:

• message: A pointer to an EmailMessage struct containing the details of the email to be sent.

Returns:

• []byte: A byte slice containing the complete MIME message.
• error: An error if constructing the MIME message fails, otherwise nil.

func GetMimeType

func GetMimeType(filename string) string

GetMimeType returns the MIME type based on the file extension. This function takes a filename, extracts its extension, and returns the corresponding MIME type.

Parameters:

• filename: A string containing the name of the file whose MIME type is to be determined.

Returns:

• string: The MIME type corresponding to the file extension.

func ValidateEmail

func ValidateEmail(email string) string

ValidateEmail validates and sanitizes an email address.

Parameters:

• email: The email address to be validated and sanitized.

Returns:

• string: The validated and sanitized email address, or an empty string if invalid.

func ValidateEmailSlice

func ValidateEmailSlice(emails []string) []string

ValidateEmailSlice validates and sanitizes a slice of email addresses.

Parameters:

• emails: A slice of email addresses to be validated and sanitized.

Returns:

• []string: A slice of validated and sanitized email addresses, excluding any invalid addresses.

Types

type Attachment

type Attachment = common.Attachment

Attachment represents an email attachment with its filename and content.

func NewAttachment

func NewAttachment(filename string, content []byte) *Attachment

NewAttachment creates a new Attachment instance with the specified filename and content. It initializes the private fields of the Attachment struct with the provided values.

Parameters:

• filename: The name of the file to be attached.
• content: The content of the file as a byte slice.

Returns:

• *Attachment: A pointer to the newly created Attachment struct.

func NewAttachmentFromFile

func NewAttachmentFromFile(filePath string) (*Attachment, error)

NewAttachmentFromFile creates a new Attachment instance from the specified file path. It reads the content of the file and initializes the private fields of the Attachment struct.

Parameters:

• filePath: The path to the file to be attached.

Returns:

• *Attachment: A pointer to the newly created Attachment struct.
• error: An error if reading the file fails, otherwise nil.

type EmailMessage

type EmailMessage = common.EmailMessage

EmailMessage represents an email message with various fields such as sender, recipients, subject, and content.

func NewEmailMessage

func NewEmailMessage(from string, to []string, subject string, body string) *EmailMessage

NewEmailMessage creates a new EmailMessage with the required fields. If the body contains HTML tags, it sets the HTML field; otherwise, it sets the Text field.

Parameters:

• from: The sender email address.
• to: A slice of recipient email addresses.
• subject: The email subject.
• body: The content of the email, which can be plain text or HTML.

Returns:

• *EmailMessage: A pointer to the newly created EmailMessage struct.

func NewFullEmailMessage

func NewFullEmailMessage(from string, to []string, subject string, cc []string, bcc []string, replyTo string, textBody string, htmlBody string, attachments []Attachment) *EmailMessage

NewFullEmailMessage creates a new EmailMessage with all fields.

Parameters:

• from: The sender email address.
• to: A slice of recipient email addresses.
• subject: The email subject.
• cc: A slice of CC recipient email addresses (optional).
• bcc: A slice of BCC recipient email addresses (optional).
• replyTo: The reply-to email address (optional).
• textBody: The plain text content of the email.
• htmlBody: The HTML content of the email (optional).
• attachments: A slice of attachments (optional).

Returns:

• *EmailMessage: A pointer to the newly created EmailMessage struct.

type EmailSender

type EmailSender interface {
	// SendEmail sends an email with the given message.
	// Parameters:
	// - message: A pointer to an EmailMessage struct containing the details of the email to be sent.
	// Returns:
	// - error: An error if sending the email fails, otherwise nil.
	SendEmail(message *EmailMessage) error
}

EmailSender interface defines the method to send an email. Implement this interface to create different email sending strategies.