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

This library 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)
  • func (w BodyPart) String() string
  • func (w *BodyPart) Write(p []byte) (int, error)
• 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) 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 []byte

BodyPart is a byte slice that implements io.Writer

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

func (BodyPart) String

func (w BodyPart) String() string

String returns the byte slice as a string in fmt.Printx(), etc

func (*BodyPart) Write

func (w *BodyPart) Write(p []byte) (int, error)

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
}

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) 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...)