mail

README

Go Mail

A cross platform mail driver for GoLang.

Introduction

Go Mail aims to unify multiple popular mail API's (SparkPost, MailGun, SendGrid & SMTP) into a singular easy to use interface. Email sending is seriously simple and great for allowing the developer to choose what platform they use.

cfg := mail.Config{
    URL:         "https://api.eu.sparkpost.com",
    APIKey:      "my-key",
    FromAddress: "hello@gophers.com",
    FromName:    "Gopher",
}

driver, err := mail.NewClient(mail.SparkPost, cfg)
if err != nil {
    fmt.Println(err)
    return
}

tx := &mail.Transmission{
    Recipients:  []string{"hello@gophers.com"},
    Subject:     "My email",
    HTML:        "<h1>Hello from go mail!</h1>",
}

result, err := driver.Send(tx)
if err != nil {
    fmt.Println(err)
    return
}

fmt.Println(result)

Installation

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

Supported API's

Currently, Sparkpost, MailGun and SendGrid is supported, if you want to see more, just submit a feature request or create a new Driver and submit a pull request.

API	Dependency	Examples
SparkPost	github.com/SparkPost/gosparkpost	Here
MailGun	github.com/mailgun/mailgun-go/v4	Here
SendGrid	github.com/sendgrid/sendgrid-go	Here
SMTP	None - only use in development.	Here

Docs

Documentation can be found at the Go Docs, but we have included a kick start guide below to get you started.

Creating a new client:

The driver type is the first argument to be passed to the NewClient function, being one of the following:

• mail.SparkPost
• mail.MailGun
• mail.SendGrid
• mail.SMTP

A new configuration type is needed to create a new mailer as the second argument, each platform requires its own data, for example, MailGun requires a domain, but SparkPost doesn't. This is based of the requirements for the API. For more details see the examples above.

cfg := mail.Config{
    URL:         "https://api.eu.sparkpost.com",
    APIKey:      "my-key",
    FromAddress: "hello@gophers.com",
    FromName:    "Gopher",
}

driver, err := mail.NewClient(mail.SparkPost, cfg)
if err != nil {
    fmt.Println(err)
    return
}

Sending Data

A transmission is required to transmit to a mailer as shown below. Once send is called, a mail.Result and error will be returned indicating if the transmission was successful.

tx := &mail.Transmission{
    Recipients: []string{"hello@gophers.com"},
    Subject:    "My email",
    HTML:       "<h1>Hello from go mail!</h1>",
    PlainText:  "plain text",
}

result, err := driver.Send(tx)
if err != nil {
    fmt.Println(err)
    return
}

fmt.Println(result)

Adding attachments:

Adding attachments to the transmission is as simple as passing a byte slice and filename, Go Mail takes care of the rest for you.

image, err := ioutil.ReadFile("gopher.jpg")
if err != nil {
    fmt.Println(err)
    return
}

tx := &mail.Transmission{
    Recipients: []string{"hello@gophers.com"},
    Subject:    "My email",
    HTML:       "<h1>Hello from go mail!</h1>",
    PlainText:  "plain text",
    Attachments: mail.Attachments{
        mail.Attachment{
            Filename: "gopher.jpg",
            Bytes:    image,
        },
    },
}

Todo

• Add CC & BCC
• Remove external dependencies.

Contributing

We welcome contributors, but please read the contributing document before making a pull request.

Licence

Code Copyright 2021 go mail. Code released under the MIT Licence.

Documentation

Index

• Constants
• type Attachment
  • func (a Attachment) B64() string
  • func (a Attachment) Mime() string
• type Attachments
  • func (a Attachments) Exists() bool
• type Config
  • func (c *Config) Validate() error
• type Mailer
  • func NewClient(driver string, cfg Config) (Mailer, error)
• type Response
• type Transmission
  • func (t *Transmission) Validate() error

Examples

• NewClient

Constants

const (
	// SparkPost driver type.
	SparkPost = "sparkpost"
	// MailGun driver type.
	MailGun = "mailgun"
	// SendGrid driver type.
	SendGrid = "sendgrid"
	// SMTP driver type.
	SMTP = "smtp"
)

const (
	// SparkAPIVersion defines the default API version for
	// SparkPost.
	SparkAPIVersion = 1
)

Types

type Attachment

type Attachment struct {
	Filename string
	Bytes    []byte
}

Attachment defines the mail file that has been uploaded via the forms endpoint. It contains useful information for sending files over the mail driver.

func (Attachment) B64

func (a Attachment) B64() string

Returns the base 64 encode of the byte data.

func (Attachment) Mime

func (a Attachment) Mime() string

Returns the Mime type of the byte data.

type Attachments

type Attachments []Attachment

Attachments defines the slice of mail attachments.

func (Attachments) Exists

func (a Attachments) Exists() bool

Determines if there are any attachments in the slice.

type Config

type Config struct {
	URL         string
	APIKey      string
	Domain      string
	FromAddress string
	FromName    string
	Password    string
	Port        int
}

Config represents the configuration passed when a new client is constructed. FromAddress, FromName and an APIKey are all required to create a new client.

func (*Config) Validate

func (c *Config) Validate() error

Validate runs sanity checks of a Config struct. This is run before a new client is created to ensure there are no invalid API calls.

type Mailer

type Mailer interface {
	Send(t *Transmission) (Response, error)
}

Mailer defines the sender for go-mail returning a Response or error when an email is sent.

func NewClient

func NewClient(driver string, cfg Config) (Mailer, error)

NewClient

Creates a new Mailer based on the input driver. Sparkpost, MailGun or SendGrid can be passed. Returns an error if a driver did not match, Or there was an error creating the client.

Example

Docs

mailer, err := NewClient(SparkPost, Config{
	APIKey:      "my-key",
	FromAddress: "hello@test.com",
	FromName:    "Test",
})

if err != nil {
	fmt.Println(err)
}

fmt.Println(mailer)

type Response

type Response struct {
	StatusCode int                 // e.g. 200
	Body       string              // e.g. {"result: success"}
	Headers    map[string][]string // e.g. map[X-Ratelimit-Limit:[600]]
	ID         string              // e.g "100"
	Message    interface{}         // e.g "Email sent successfully"
}

Response represents the data passed back from a successful transmission. Where possible, a status code, body, headers will be returned within the response.

type Transmission

type Transmission struct {
	Recipients  []string
	Subject     string
	HTML        string
	PlainText   string
	Attachments Attachments
}

Transmission represents the JSON structure accepted by and returned from the driver's API. Recipients, HTML and a subject is required to send the email.

func (*Transmission) Validate

func (t *Transmission) Validate() error

Validate runs sanity checks of a Transmission struct. This is run before any email sending to ensure there are no invalid API calls.