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.Writerfor 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"), &tls.Config{})
mail.To("dom@itsallbroken.com")
mail.From("jsmith@example.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"), &tls.Config{})
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 callingAttach()andSend()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 generating MIME compliant emails, and optionally sending them over SMTP.
Both plain-text and HTML email body content is supported, and their types implement io.Writer allowing easy composition directly from templating engines, etc.
Attachments are fully supported (attach anything that implements io.Reader).
The raw MIME content can be retrieved using MimeBuf(), typically used with an API service such as Amazon SES that does not require using an SMTP interface.
Example ¶
// Create a new email - specify the SMTP host and auth
mail := New("mail.host.com:25", smtp.PlainAuth("", "user", "pass", "mail.host.com"), &tls.Config{})
mail.To("dom@itsallbroken.com")
mail.From("jsmith@example.com")
mail.FromName("Prince Anybody")
mail.Subject("Business proposition")
// Add a custom header
mail.AddHeader("X-TOTALLY-NOT-A-SCAM", "true")
// 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"), &tls.Config{})
mail.To("dom@itsallbroken.com")
mail.From("jsmith@example.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 ¶
- type BodyPart
- type MailYak
- func (m *MailYak) AddHeader(name, value string)
- func (m *MailYak) Attach(name string, r io.Reader)
- func (m *MailYak) AttachInline(name string, r io.Reader)
- func (m *MailYak) AttachInlineWithMimeType(name string, r io.Reader, mimeType string)
- func (m *MailYak) AttachWithMimeType(name string, r io.Reader, mimeType string)
- func (m *MailYak) Bcc(addrs ...string)
- func (m *MailYak) Cc(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) MimeBuf() (*bytes.Buffer, error)
- 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)
- func (m *MailYak) WriteBccHeader(shouldWrite bool)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BodyPart ¶
BodyPart is a buffer holding the contents of an email MIME part.
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"), &tls.Config{})
// 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"), &tls.Config{})
// 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:
type MailYak ¶
type MailYak struct {
// contains filtered or unexported fields
}
MailYak represents an email.
func New ¶
New returns an instance of MailYak using host as the SMTP server, and authenticating with auth where required.
host must include the port number (i.e. "smtp.itsallbroken.com:25")
mail := mailyak.New("smtp.itsallbroken.com:25", smtp.PlainAuth(
"",
"username",
"password",
"stmp.itsallbroken.com",
))
func (*MailYak) AddHeader ¶
AddHeader adds an arbitrary email header.
If value contains non-ASCII characters, it is Q-encoded according to RFC1342. As always, validate any user input before adding it to a message, as this method may enable an attacker to override the standard headers and, for example, BCC themselves in a password reset email to a different user.
func (*MailYak) Attach ¶
Attach adds the contents of r to the email as an attachment with name as the filename.
r is not read until Send is called and the MIME type will be detected using https://golang.org/pkg/net/http/#DetectContentType
func (*MailYak) AttachInline ¶
AttachInline adds the contents of r to the email as an inline attachment. Inline attachments are typically used within the email body, such as a logo or header image. It is up to the user to ensure name is unique.
Files can be referenced by their name within the email using the cid URL protocol:
<img src="cid:myFileName"/>
r is not read until Send is called and the MIME type will be detected using https://golang.org/pkg/net/http/#DetectContentType
func (*MailYak) AttachInlineWithMimeType ¶
AttachInlineWithMimeType adds the contents of r to the email as an inline attachment with mimeType as the specified MIME type of the content. Inline attachments are typically used within the email body, such as a logo or header image. It is up to the user to ensure name is unique and the specified mimeType is correct.
Files can be referenced by their name within the email using the cid URL protocol:
<img src="cid:myFileName"/>
r is not read until Send is called.
func (*MailYak) AttachWithMimeType ¶
AttachWithMimeType adds the contents of r to the email as an attachment with name as the filename and mimeType as the specified MIME type of the content. It is up to the user to ensure the mimeType is correct.
r is not read until Send is called
func (*MailYak) Bcc ¶
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
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 ¶
From sets the sender email address.
Users should also consider setting FromName().
func (*MailYak) FromName ¶
FromName sets the sender name.
If set, emails typically display as being from:
From Name <sender@example.com>
If name contains non-ASCII characters, it is Q-encoded according to RFC1342.
func (*MailYak) MimeBuf ¶ added in v1.1.0
MimeBuf returns the buffer containing all the RAW MIME data.
MimeBuf is typically used with an API service such as Amazon SES that does not use an SMTP interface.
func (*MailYak) ReplyTo ¶
ReplyTo sets the Reply-To email address.
Setting a ReplyTo address is optional.
func (*MailYak) Send ¶
Send attempts to send the built email via the configured SMTP server.
Attachments are read when Send() is called, and any connection/authentication errors will be returned by Send().
func (*MailYak) String ¶ added in v1.0.4
String returns a redacted description of the email state, typically for logging or debugging purposes.
Authentication information is not included in the returned string.
func (*MailYak) Subject ¶
Subject sets the email subject line.
If sub contains non-ASCII characters, it is Q-encoded according to RFC1342.
func (*MailYak) To ¶
To sets a list of recipient addresses.
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...)
func (*MailYak) WriteBccHeader ¶
WriteBccHeader writes the BCC header to the MIME body when true. Defaults to false.
This is usually required when writing the MIME body to an email API such as Amazon's SES, but can cause problems when sending emails via a SMTP server.
Specifically, RFC822 says:
Some systems may choose to include the text of the "Bcc" field only in the author(s)'s copy, while others may also include it in the text sent to all those indicated in the "Bcc" list.
This ambiguity can result in some SMTP servers not stripping the BCC header and exposing the BCC addressees to recipients. For more information, see:
https://github.com/domodwyer/mailyak/issues/14
Source Files