mailyak

README

An elegant MIME mail library with support for attachments

A simple, easy to use email library for Go (golang).

• Full attachment support (attach anything that implements io.Reader)
• Send to multiple addresses at the same time, including BCC addresses.
• Supports composing multi-part messages (HTML and plain text emails for older clients)
• Write templates directly to the email body (implements io.Writer for convenience)
• Production ready - several million emails sent in a production environment
• Comprehensive unit tests

Installation

go get -v github.com/domodwyer/mailyak

Usage

// Create a new email - specify the SMTP host and auth
mail := mailyak.New("mail.host.com:25", smtp.PlainAuth("", "user", "pass", "mail.host.com"))

mail.To("dom@itsallbroken.com")
mail.From("nigerianprince@justneedshelp.com")
mail.FromName("Prince Fournineteen")

mail.Subject("Business proposition")

// mail.HTML() and mail.Plain() implement io.Writer, so you can do handy things like
// parse a template directly into the email body
if err := t.ExecuteTemplate(mail.HTML(), "htmlEmail", data); err != nil {
	panic(" 💣 ")
}

// Or set the body using a string setter
mail.Plain().Set("Get a real email client")

// And you're done! 
if err := mail.Send(); err != nil {
	panic(" 💣 ")
}

To send an attachment:

mail := mailyak.New("mail.host.com:25", smtp.PlainAuth("", "user", "pass", "mail.host.com"))

mail.To("dom@itsallbroken.com")
mail.From("oops@itsallbroken.com")
mail.Subject("I am a teapot")
mail.HTML().Set("Don't panic")

// input can be a bytes.Buffer, os.File, os.Stdin, etc.
// call multiple times to attach multiple files
mail.Attach("filename.txt", &input)

if err := mail.Send(); err != nil {
	panic(" 💣 ")
}

Notes

• Why "MailYak"? Because "MailyMcMailFace" is annoyingly long to type.
• You can use a single instance of mailyak to send multiple emails after changing the to/body/whatever fields, avoiding unnecessary allocation/GC pressure.
• Attachments are read when you call Send() to prevent holding onto multiple copies of the attachment in memory (source and email) - this means changing the attachment data between calling Attach() and Send() will change what's emailed out!
• For your own sanity you should vendor this, and any other libraries when going into production, I recommend govendor.

Documentation

Overview

Package mailyak provides a simple interface for sending MIME compliant emails over SMTP.

Attachments are fully supported (attach anything that implements io.Reader) and the code is tried and tested in a production setting.

For convenience the HTML and Plain methods return a type implementing io.Writer, allowing email bodies to be composed directly from templating engines.

Example

// Create a new email - specify the SMTP host and auth
mail := New("mail.host.com:25", smtp.PlainAuth("", "user", "pass", "mail.host.com"))

mail.To("dom@itsallbroken.com")
mail.From("nigerianprince@justneedshelp.com")
mail.FromName("Prince Anybody")

mail.Subject("Business proposition")

// mail.HTMLWriter() and mail.PlainWriter() implement io.Writer, so you can
// do handy things like parse a template directly into the email body - here
// we just use io.WriteString()
if _, err := io.WriteString(mail.HTML(), "So long, and thanks for all the fish."); err != nil {
	panic(" :( ")
}

// Or set the body using a string helper
mail.Plain().Set("Get a real email client")

// And you're done!
if err := mail.Send(); err != nil {
	panic(" :( ")
}

Example (Attachments)

// This will be our attachment data
buf := bytes.Buffer{}
io.WriteString(&buf, "We're in the stickiest situation since Sticky the Stick Insect got stuck on a sticky bun.")

// Create a new email - specify the SMTP host and auth
mail := New("mail.host.com:25", smtp.PlainAuth("", "user", "pass", "mail.host.com"))

mail.To("dom@itsallbroken.com")
mail.From("nigerianprince@justneedshelp.com")
mail.HTML().Set("I am an email")

// buf could be anything that implements io.Reader
mail.Attach("sticky.txt", &buf)

if err := mail.Send(); err != nil {
	panic(" :( ")
}

Index

• type AttachmentEmailer
• type BodyPart
  • func (w *BodyPart) Set(s string)
• type Emailer
• type MailYak
  • func New(host string, auth smtp.Auth) *MailYak
  • func (m *MailYak) Attach(name string, r io.Reader)
  • func (m *MailYak) Bcc(addrs ...string)
  • func (m *MailYak) ClearAttachments()
  • func (m *MailYak) From(addr string)
  • func (m *MailYak) FromName(name string)
  • func (m *MailYak) HTML() *BodyPart
  • func (m *MailYak) Plain() *BodyPart
  • func (m *MailYak) ReplyTo(addr string)
  • func (m *MailYak) Send() error
  • func (m *MailYak) String() string
  • func (m *MailYak) Subject(sub string)
  • func (m *MailYak) To(addrs ...string)

Examples

• Package
• Package (Attachments)
• BodyPart (String)
• BodyPart (Templates)

Types

type AttachmentEmailer

type AttachmentEmailer interface {
	Emailer
	Attach(name string, data io.Reader)
	ClearAttachments()
}

AttachmentEmailer extends the Emailer interface to provide attachment support

type BodyPart

type BodyPart struct{ bytes.Buffer }

BodyPart is a buffer.

Example (String)

// Create a new email - specify the SMTP host and auth
mail := New("mail.host.com:25", smtp.PlainAuth("", "user", "pass", "mail.host.com"))

// Set the plain text email content using a string
mail.Plain().Set("Get a real email client")

Example (Templates)

// Create a new email
mail := New("mail.host.com:25", smtp.PlainAuth("", "user", "pass", "mail.host.com"))

// Our pretend template data
tmplData := struct {
	Language string
}{"Go"}

// Compile a template
tmpl, err := template.New("html").Parse("I am an email template in {{ .Language }}")
if err != nil {
	panic(" :( ")
}

// Execute the template directly into the email body
if err := tmpl.Execute(mail.HTML(), tmplData); err != nil {
	panic(" :( ")
}

func (*BodyPart) Set

func (w *BodyPart) Set(s string)

Set accepts a string as the contents of a BodyPart and replaces any existing data.

type Emailer

type Emailer interface {
	To(addrs ...string)
	Bcc(addrs ...string)
	Subject(sub string)
	From(addr string)
	FromName(name string)
	ReplyTo(addr string)
	Send() error
	HTML() *BodyPart
	Plain() *BodyPart
}

Emailer defines the interface implemented by MailYak

type MailYak

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

MailYak holds all the necessary information to send an email. It also implements the Emailer interface.

func New

func New(host string, auth smtp.Auth) *MailYak

New returns an instance of MailYak initialised with the given SMTP address and authentication credentials

Note: the host string should include the port (i.e. "smtp.itsallbroken.com:25")

mail := mailyak.New("smtp.itsallbroken.com:25", smtp.PlainAuth(
	"",
	"username",
	"password",
	"stmp.itsallbroken.com",
))

func (*MailYak) Attach

func (m *MailYak) Attach(name string, r io.Reader)

Attach adds an attachment to the email with the given filename.

Note: The attachment data isn't read until Send() is called

func (*MailYak) Bcc

func (m *MailYak) Bcc(addrs ...string)

Bcc sets a list of blind carbon copy (BCC) addresses

You can pass one or more addresses to this method, none of which are viewable to the recipients.

mail.Bcc("dom@itsallbroken.com", "another@itsallbroken.com")

or pass a slice of strings:

bccs := []string{
	"one@itsallbroken.com",
	"two@itsallbroken.com"
}

mail.Bcc(bccs...)

func (*MailYak) ClearAttachments

func (m *MailYak) ClearAttachments()

ClearAttachments removes all current attachments

func (*MailYak) From

func (m *MailYak) From(addr string)

From sets the sender email address

func (*MailYak) FromName

func (m *MailYak) FromName(name string)

FromName sets the sender name

func (*MailYak) HTML

func (m *MailYak) HTML() *BodyPart

HTML returns a BodyPart for the HTML email body

func (*MailYak) Plain

func (m *MailYak) Plain() *BodyPart

Plain returns a BodyPart for the plain-text email body

func (*MailYak) ReplyTo

func (m *MailYak) ReplyTo(addr string)

ReplyTo sends the Reply-To email address

func (*MailYak) Send

func (m *MailYak) Send() error

Send attempts to send the built email

Attachments are read when Send() is called, and any errors will be returned here.

func (*MailYak) String

func (m *MailYak) String() string

String makes MailYak struct printable for debugging purposes (conforms to the Stringer interface).

func (*MailYak) Subject

func (m *MailYak) Subject(sub string)

Subject sets the email subject line

func (*MailYak) To

func (m *MailYak) To(addrs ...string)

To sets a list of recipient addresses to send the email to

You can pass one or more addresses to this method, all of which are viewable to the recipients.

mail.To("dom@itsallbroken.com", "another@itsallbroken.com")

or pass a slice of strings:

tos := []string{
	"one@itsallbroken.com",
	"two@itsallbroken.com"
}

mail.To(tos...)