gomail

package module
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 9, 2024 License: MIT Imports: 17 Imported by: 2

README

go-mail

Lightweight email package with multi-provider support (ses, mandrill, postmark)

Release Build Status Report codecov Go
Mergify Status Sponsor Donate


Table of Contents


Installation

go-mail requires a supported release of Go.

go get -u github.com/mrz1836/go-mail

Documentation

View the generated documentation

GoDoc

Features
  • Supports multiple service providers (below)
  • Support basic SMTP
  • Plain-text and HTML content
  • Multiple file attachments
  • Open & click tracking (provider dependant)
  • Inject css into html content
  • Basic template support
  • Max restrictions on To, CC and BCC
Supported Service Providers
Package Dependencies
Library Deployment

goreleaser for easy binary or library deployment to GitHub and can be installed via: brew install goreleaser.

The .goreleaser.yml file is used to configure goreleaser.

Use make release-snap to create a snapshot version of the release, and finally make release to ship to production.

Makefile Commands

View all makefile commands

make help

List of all current commands:

all                  Runs multiple commands
clean                Remove previous builds and any test cache data
clean-mods           Remove all the Go mod cache
coverage             Shows the test coverage
diff                 Show the git diff
generate             Runs the go generate command in the base of the repo
godocs               Sync the latest tag with GoDocs
help                 Show this help message
install              Install the application
install-go           Install the application (Using Native Go)
lint                 Run the golangci-lint application (install if not found)
release              Full production release (creates release in Github)
release              Runs common.release then runs godocs
release-snap         Test the full release (build binaries)
release-test         Full production test release (everything except deploy)
replace-version      Replaces the version in HTML/JS (pre-deploy)
run-examples         Runs all the examples
tag                  Generate a new tag and push (tag version=0.0.0)
tag-remove           Remove a tag if found (tag-remove version=0.0.0)
tag-update           Update an existing tag to current commit (tag-update version=0.0.0)
test                 Runs lint and ALL tests
test-ci              Runs all tests via CI (exports coverage)
test-ci-no-race      Runs all tests via CI (no race) (exports coverage)
test-ci-short        Runs unit tests via CI (exports coverage)
test-no-lint         Runs just tests
test-short           Runs vet, lint and tests (excludes integration tests)
test-unit            Runs tests and outputs coverage
uninstall            Uninstall the application (and remove files)
update-linter        Update the golangci-lint package (macOS only)
vet                  Run the Go vet application

Examples & Tests

All unit tests and examples run via GitHub Actions and uses Go version 1.19.x. View the configuration file.

Run all tests (including integration tests)

make test

Run tests (excluding integration tests)

make test-short

Run the examples:

make run-examples

Benchmarks

Run the Go benchmarks:

make bench

Code Standards

Read more about this Go project's code standards.


Usage

View the examples


Maintainers

MrZ
MrZ

Contributing

View the contributing guidelines and follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Stars


License

License

Documentation

Overview

Package gomail is a lightweight email package with multi-provider support

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Attachment 

type Attachment struct {
	FileName   string    `json:"file_name" mapstructure:"file_name"`
	FileReader io.Reader `json:"-" mapstructure:"-"`
	FileType   string    `json:"file_type" mapstructure:"file_type"`
}

Attachment is the email file attachment

type Email 

type Email struct {
	Attachments      []Attachment `json:"attachments" mapstructure:"attachments"`
	CSS              []byte       `json:"css" mapstructure:"css"`
	Recipients       []string     `json:"recipients" mapstructure:"recipients"`
	RecipientsBcc    []string     `json:"recipients_bcc" mapstructure:"recipients_bcc"`
	RecipientsCc     []string     `json:"recipients_cc" mapstructure:"recipients_cc"`
	Styles           []byte       `json:"styles" mapstructure:"styles"`
	Tags             []string     `json:"tags" mapstructure:"tags"`
	FromAddress      string       `json:"from_address" mapstructure:"from_address"`
	FromName         string       `json:"from_name" mapstructure:"from_name"`
	HTMLContent      string       `json:"html_content" mapstructure:"html_content"`
	PlainTextContent string       `json:"plain_text_content" mapstructure:"plain_text_content"`
	ReplyToAddress   string       `json:"reply_to_address" mapstructure:"reply_to_address"`
	Subject          string       `json:"subject" mapstructure:"subject"`
	AutoText         bool         `json:"auto_text" mapstructure:"auto_text"`
	Important        bool         `json:"important" mapstructure:"important"`
	TrackClicks      bool         `json:"track_clicks" mapstructure:"track_clicks"`
	TrackOpens       bool         `json:"track_opens" mapstructure:"track_opens"`
	ViewContentLink  bool         `json:"view_content_link" mapstructure:"view_content_link"`
}

Email represents the fields of the email to send

DO NOT CHANGE ORDER - Optimized for memory (maligned)

func (*Email) AddAttachment 

func (e *Email) AddAttachment(name, fileType string, reader io.Reader)

AddAttachment adds a new attachment

Example

ExampleEmail_AddAttachment example using the AddAttachment() 

mail := new(MailService)
mail.FromUsername = "no-reply"
mail.FromName = "No Reply"
mail.FromDomain = "example.com"

email := mail.NewEmail()
email.AddAttachment("testName", "testType", nil)

fmt.Printf("attachment: %s", email.Attachments[0].FileName)

Output:

attachment: testName

func (*Email) ApplyTemplates added in v0.0.4 

func (e *Email) ApplyTemplates(htmlTemplate *template.Template, textTemplate *template.Template, emailData interface{}) (err error)

ApplyTemplates will take the template files and process them with the email data (can be e or overridden)

func (*Email) ParseHTMLTemplate added in v0.0.5 

func (e *Email) ParseHTMLTemplate(htmlLocation string) (htmlTemplate *template.Template, err error)

ParseHTMLTemplate parse the template with inline style injection (html) This method returns the template which should be stored in memory for quick access

func (*Email) ParseTemplate added in v0.0.4 

func (e *Email) ParseTemplate(filename string) (parsed *template.Template, err error)

ParseTemplate parse the template, fire error if parse fails This method returns the template which should be stored in memory for quick access

type MailService 

type MailService struct {
	AvailableProviders  []ServiceProvider `json:"available_providers" mapstructure:"available_providers"`     // list of providers that loaded successfully
	EmailCSS            []byte            `json:"email_css" mapstructure:"email_css"`                         // default css pre-parsed into bytes
	AwsSesAccessID      string            `json:"aws_ses_access_id" mapstructure:"aws_ses_access_id"`         // aws iam access id for ses service
	AwsSesEndpoint      string            `json:"aws_ses_endpoint" mapstructure:"aws_ses_endpoint"`           // ie: https://email.us-east-1.amazonaws.com
	AwsSesSecretKey     string            `json:"aws_ses_secret_key" mapstructure:"aws_ses_secret_key"`       // aws iam secret key for corresponding access id
	AwsSesRegion        string            `json:"aws_ses_region" mapstructure:"aws_ses_region"`               // AWS region
	FromDomain          string            `json:"from_domain" mapstructure:"from_domain"`                     // ie: example.com
	FromName            string            `json:"from_name" mapstructure:"from_name"`                         // ie: No Reply
	FromUsername        string            `json:"from_username" mapstructure:"from_username"`                 // ie: no-reply
	MandrillAPIKey      string            `json:"mandrill_api_key" mapstructure:"mandrill_api_key"`           // mandrill api key
	PostmarkServerToken string            `json:"postmark_server_token" mapstructure:"postmark_server_token"` // ie: abc123...
	SMTPHost            string            `json:"smtp_host" mapstructure:"smtp_host"`                         // ie: example.com
	SMTPPassword        string            `json:"smtp_password" mapstructure:"smtp_password"`                 // ie: secretPassword

	SMTPUsername     string `json:"smtp_username" mapstructure:"smtp_username"`           // ie: testuser
	MaxBccRecipients int    `json:"max_bcc_recipients" mapstructure:"max_bcc_recipients"` // max amount for BCC
	MaxCcRecipients  int    `json:"max_cc_recipients" mapstructure:"max_cc_recipients"`   // max amount for CC
	MaxToRecipients  int    `json:"max_to_recipients" mapstructure:"max_to_recipients"`   // max amount for TO
	SMTPPort         int    `json:"smtp_port" mapstructure:"smtp_port"`                   // ie: 25
	AutoText         bool   `json:"auto_text" mapstructure:"auto_text"`                   // whether to automatically generate a text part for messages that are not given text
	Important        bool   `json:"important" mapstructure:"important"`                   // whether this message is important, and should be delivered ahead of non-important messages
	TrackClicks      bool   `json:"track_clicks" mapstructure:"track_clicks"`             // whether to turn on click tracking for the message
	TrackOpens       bool   `json:"track_opens" mapstructure:"track_opens"`               // whether to turn on open tracking for the message
	// contains filtered or unexported fields
}

MailService is the configuration to use for loading the service and provider's clients

DO NOT CHANGE ORDER - Optimized for memory (maligned)

func (*MailService) NewEmail 

func (m *MailService) NewEmail() (email *Email)

NewEmail creates a new email using defaults from the service configuration

Example

ExampleMailService_NewEmail example using the NewEmail() 

mail := new(MailService)
mail.FromUsername = "no-reply"
mail.FromName = "No Reply"
mail.FromDomain = "example.com"

email := mail.NewEmail()
fmt.Printf("new email with from address: %s", email.FromAddress)

Output:

new email with from address: no-reply@example.com

func (*MailService) SendEmail 

func (m *MailService) SendEmail(ctx context.Context, email *Email, provider ServiceProvider) (err error)

SendEmail will send an email using the given provider

func (*MailService) StartUp 

func (m *MailService) StartUp() (err error)

StartUp is fired once to load the email service

type ServiceProvider 

type ServiceProvider int

ServiceProvider is the provider 

const (
	AwsSes   ServiceProvider = iota // AWS SES Email Service
	Mandrill                        // Mandrill Email Service
	Postmark                        // Postmark Email Service
	SMTP                            // SMTP Email Service
)

Email Service Providers

Source Files

View all Source files

Directories

Path Synopsis
Package main is examples using the go-mail package
 Package main is examples using the go-mail package

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.