mailyak

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Apr 25, 2017 License: MIT Imports: 10 Imported by: 0

README

Build Status GoDoc

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(" :( ")
}

Output:
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(" :( ")
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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

Output:
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(" :( ")
}

Output:

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) Cc added in v1.2.0 

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

Cc sets a list of carbon copy (CC) addresses

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

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

or pass a slice of strings: 

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

mail.Cc(ccs...)

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) MimeBuf added in v1.1.0 

func (m *MailYak) MimeBuf() (*bytes.Buffer, error)

MimeBuf returns the buffer containing the RAW MIME data

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 added in v1.0.4 

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

Source Files

View all Source files

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.