mail

README

go-mail

• Load template files from disk or embedded store.
• Preview rendered template files with example data in browser with go-mail-preview tool.
• Automatically inlines CSS.
• Powered by Go's html/template and text/template engine.
• Supports markdown to HTML parsing inside template.
• Use provider to send an email.

Usage

import (
  "github.com/mattes/go-mail"
  "github.com/mattes/go-mail/provider/mailgun"
)

// load templates
tpl, err := mail.NewTemplates(mail.FilesFromLocalDir("./templates"))

// create mail envelope
m := mail.New()
m.Subject = "Advice to self"
m.To("Mattes", "mattes@example.com")
m.Template(tpl, "simple", mail.Vars{
  "Body": "no ice cream after midnight",
})

// send email with mailgun (or any other provider)
p, err := mailgun.New("mailgun-domain", "mailgun-key")
err = p.Send(m)

Templates

Structure

Emails can have a HTML and/or text body. Templates are recognized by their file extension.

my-template.html         -> used for html body, processed with Go's html/template engine
my-template.txt          -> used for text body, processed with Go's text/template engine
my-template.example.yaml -> used for preview

Embed templates into Go binary

To embed templates into your Go binary, you can use a tool like go.rice.

Install go.rice first:

go get github.com/GeertJohan/go.rice
go get github.com/GeertJohan/go.rice/rice

Update your go code:

//go:generate rice embed-go

var MyTemplates = rice.MustFindBox("./path/to/templates")

Run go generate to generate the embedded file. See files.go and files_test.go for an example.

Nice templates

There is a couple of tested email templates available, please have a look at:

• https://github.com/wildbit/postmark-templates
• https://github.com/mailgun/transactional-email-templates
• https://github.com/leemunroe/responsive-html-email-template
• https://github.com/leemunroe/amp-email-templates

Documentation

Index

• Constants
• type Files
  • func FilesFromLocalDir(dir string) Files
  • func FilesFromRiceBox(box *rice.Box) Files
  • func SimpleTemplate() Files
• type Mail
  • func New() *Mail
  • func (m *Mail) From(name, address string)
  • func (m *Mail) FromStr() string
  • func (m *Mail) Render() error
  • func (m *Mail) Template(t *Templates, name string, vars Vars)
  • func (m *Mail) To(name, address string)
  • func (m *Mail) ToStr() string
• type MissingVar
• type Provider
• type RenderOption
  • func AddFunc(name string, fn interface{}) RenderOption
  • func AddFuncs(funcMap map[string]interface{}) RenderOption
  • func DisableInlineCSS() RenderOption
  • func OnMissingVar(mode MissingVar) RenderOption
  • func SetDelims(left, right string) RenderOption
• type Templates
  • func NewTemplates(files Files, opts ...RenderOption) (*Templates, error)
  • func (t *Templates) Render(name string, vars Vars) ([]byte, error)
  • func (t *Templates) RenderWithExampleData(name string) ([]byte, error)
• type Vars
• type WalkFunc

Constants

const (
	HTMLExtension     = "html"
	TextExtension     = "txt"
	YAMLExtension     = "yaml"
	ExampleFileSuffix = "example" // i.e. file.example.yaml
)

Types

type Files

type Files interface {
	Open(name string) (io.ReadCloser, error)
	Walk(WalkFunc) error
}

func FilesFromLocalDir

func FilesFromLocalDir(dir string) Files

func FilesFromRiceBox

func FilesFromRiceBox(box *rice.Box) Files

func SimpleTemplate

func SimpleTemplate() Files

Simple is a simple default template ready to be used. See https://github.com/leemunroe/responsive-html-email-template

type Mail

type Mail struct {
	FromName, FromAddress string
	ToName, ToAddress     string
	Subject               string

	HTML, Text []byte
	// contains filtered or unexported fields
}

func New

func New() *Mail

func (*Mail) From

func (m *Mail) From(name, address string)

func (*Mail) FromStr

func (m *Mail) FromStr() string

func (*Mail) Render

func (m *Mail) Render() error

Render renders HTML and/or Text portion of email with given Template.

func (*Mail) Template

func (m *Mail) Template(t *Templates, name string, vars Vars)

Template sets the template to be used for this email. Make sure to call mail.Render() afterwards. If both name.html and name.txt are available, both will be included in mail. If only name.html or name.txt are available, the one available will be used. If neither name.html nor name.txt are available, an error is returned when Rendered.

func (*Mail) To

func (m *Mail) To(name, address string)

func (*Mail) ToStr

func (m *Mail) ToStr() string

type MissingVar

type MissingVar int

const (
	HaltOnError MissingVar = iota
	ContinueOnError
	ZeroValueOnError
)

type Provider

type Provider interface {

	// Send sends a mail. The implementing provider must call
	// Mail.Render() before accessing Mail.HTML or Mail.Text.
	Send(*Mail) error
}

Provider interface just exists to lousily enforce some consistency across mail providers. Mail only works for basic emails.

type RenderOption

type RenderOption func(*Templates)

func AddFunc

func AddFunc(name string, fn interface{}) RenderOption

Func adds a function to the template's function map.

func AddFuncs

func AddFuncs(funcMap map[string]interface{}) RenderOption

Funcs adds the elements of the argument map to the template's function map.

func DisableInlineCSS

func DisableInlineCSS() RenderOption

func OnMissingVar

func OnMissingVar(mode MissingVar) RenderOption

func SetDelims

func SetDelims(left, right string) RenderOption

Delims sets the delimiters

type Templates

type Templates struct {
	// contains filtered or unexported fields
}

func NewTemplates

func NewTemplates(files Files, opts ...RenderOption) (*Templates, error)

func (*Templates) Render

func (t *Templates) Render(name string, vars Vars) ([]byte, error)

Render renders template with vars. It's goroutine-safe.

func (*Templates) RenderWithExampleData

func (t *Templates) RenderWithExampleData(name string) ([]byte, error)

RenderWithExample will render a template and use example data provided in name.example.yaml. It's goroutine-safe.

type Vars

type Vars map[string]interface{}

type WalkFunc

type WalkFunc func(name string, body io.ReadCloser) error