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.

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([]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

• Variables
• type Attachment
• type EmailMessage
• type EmailSender

Variables

var BuildMimeMessage = common.BuildMimeMessage

var GetMimeType = common.GetMimeType

---- Utility functions ----

var NewAttachment = common.NewAttachment

var NewAttachmentFromFile = common.NewAttachmentFromFile

var NewEmailMessage = common.NewEmailMessage

var NewFullEmailMessage = common.NewFullEmailMessage

var ValidateEmail = common.ValidateEmail

---- Validation functions ----

var ValidateEmailSlice = common.ValidateEmailSlice

Types

type Attachment

type Attachment = common.Attachment

---- Attachment and related functions ----

type EmailMessage

type EmailMessage = common.EmailMessage

---- EmailMessage and related functions ----

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.