gomail

README

Gomail

Introduction

Gomail is a very simple and powerful package to send emails.

It requires Go 1.3 or newer.

Features

• Dead-simple API
• Highly flexible
• Backward compatibility promise
• Supports HTML and text templates
• Attachments
• Embedded images
• SSL/TLS support
• Automatic encoding of special characters
• Well-documented
• High test coverage

Documentation

https://godoc.org/gopkg.in/gomail.v1

Download

go get gopkg.in/gomail.v1

Example

package main

import (
	"gopkg.in/gomail.v1"
)

func main() {
	msg := gomail.NewMessage()
	msg.SetHeader("From", "alex@example.com")
	msg.SetHeader("To", "bob@example.com", "cora@example.com")
	msg.SetAddressHeader("Cc", "dan@example.com", "Dan")
	msg.SetHeader("Subject", "Hello!")
	msg.SetBody("text/html", "Hello <b>Bob</b> and <i>Cora</i>!")

	f, err := gomail.OpenFile("/home/Alex/lolcat.jpg")
	if err != nil {
		panic(err)
	}
	msg.Attach(f)

	// Send the email to Bob, Cora and Dan
	mailer := gomail.NewMailer("smtp.example.com", "user", "123456", 587)
	if err := mailer.Send(msg); err != nil {
		panic(err)
	}
}

FAQ

x509: certificate signed by unknown authority

If you get this error it means the certificate used by the SMTP server is not considered valid by the client running Gomail. As a quick workaround you can bypass the verification of the server's certificate chain and host name by using SetTLSConfig:

mailer := gomail.NewMailer("smtp.example.com", "user", "123456", 587, gomail.SetTLSConfig(&tls.Config{InsecureSkipVerify: true}))

Note, however, that this is insecure and should not be used in production.

504 5.7.4 Unrecognized authentication type

If you get this error, you should try using the LOGIN authentication mechanism:

addr := "smtp.example.com:587"
auth := gomail.LoginAuth("username", "password", "smtp.example.com")
mailer := gomail.NewCustomMailer(addr, auth)

See issue #16.

Contact

You are more than welcome to open issues and send pull requests if you find a bug or need a new feature.

You can also ask questions on the Gomail thread in the Go mailing-list or via Twitter @alexandrecesaro.

Documentation

Overview

Package gomail provides a simple interface to send emails.

More info on Github: https://github.com/go-gomail/gomail

Index

• func LoginAuth(username, password, host string) smtp.Auth
• type Encoding
• type File
  • func CreateFile(name string, content []byte) *File
  • func OpenFile(filename string) (*File, error)
• type Mailer
  • func NewCustomMailer(addr string, auth smtp.Auth, settings ...MailerSetting) *Mailer
  • func NewMailer(host string, username string, password string, port int, ...) *Mailer
  • func (m *Mailer) Send(msg *Message) error
• type MailerSetting
  • func SetSendMail(s SendMailFunc) MailerSetting
  • func SetTLSConfig(c *tls.Config) MailerSetting
• type Message
  • func NewMessage(settings ...MessageSetting) *Message
  • func (msg *Message) AddAlternative(contentType, body string)
  • func (msg *Message) Attach(f ...*File)
  • func (msg *Message) DelHeader(field string)
  • func (msg *Message) Embed(image ...*File)
  • func (msg *Message) Export() *mail.Message
  • func (msg *Message) FormatAddress(address, name string) string
  • func (msg *Message) FormatDate(date time.Time) string
  • func (msg *Message) GetBodyWriter(contentType string) io.Writer
  • func (msg *Message) GetHeader(field string) []string
  • func (msg *Message) SetAddressHeader(field, address, name string)
  • func (msg *Message) SetBody(contentType, body string)
  • func (msg *Message) SetDateHeader(field string, date time.Time)
  • func (msg *Message) SetHeader(field string, value ...string)
  • func (msg *Message) SetHeaders(h map[string][]string)
• type MessageSetting
  • func SetCharset(charset string) MessageSetting
  • func SetEncoding(enc Encoding) MessageSetting
• type SendMailFunc

Functions

func LoginAuth

func LoginAuth(username, password, host string) smtp.Auth

LoginAuth returns an Auth that implements the LOGIN authentication mechanism.

Types

type Encoding

type Encoding string

Encoding represents a MIME encoding scheme like quoted-printable or base64.

const (
	// QuotedPrintable represents the quoted-printable encoding as defined in
	// RFC 2045.
	QuotedPrintable Encoding = "quoted-printable"
	// Base64 represents the base64 encoding as defined in RFC 2045.
	Base64 Encoding = "base64"
	// Unencoded can be used to avoid encoding the body of an email. The headers
	// will still be encoded using quoted-printable encoding.
	Unencoded Encoding = "8bit"
)

type File

type File struct {
	Name      string
	MimeType  string
	Content   []byte
	ContentID string
}

A File represents a file that can be attached or embedded in an email.

func CreateFile

func CreateFile(name string, content []byte) *File

CreateFile creates a gomail.File from the given name and content.

func OpenFile

func OpenFile(filename string) (*File, error)

OpenFile opens a file on disk to create a gomail.File.

type Mailer

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

A Mailer represents an SMTP server.

func NewCustomMailer

func NewCustomMailer(addr string, auth smtp.Auth, settings ...MailerSetting) *Mailer

NewCustomMailer creates a mailer with the given authentication mechanism.

Example:

gomail.NewCustomMailer("host:587", smtp.CRAMMD5Auth("username", "secret"))

func NewMailer

func NewMailer(host string, username string, password string, port int, settings ...MailerSetting) *Mailer

NewMailer returns a mailer. The given parameters are used to connect to the SMTP server via a PLAIN authentication mechanism.

func (*Mailer) Send

func (m *Mailer) Send(msg *Message) error

Send sends the emails to all the recipients of the message.

type MailerSetting

type MailerSetting func(m *Mailer)

A MailerSetting can be used in a mailer constructor to configure it.

func SetSendMail

func SetSendMail(s SendMailFunc) MailerSetting

SetSendMail allows to set the email-sending function of a mailer.

Example:

myFunc := func(addr string, a smtp.Auth, from string, to []string, msg []byte) error {
	// Implement your email-sending function similar to smtp.SendMail
}
mailer := gomail.NewMailer("host", "user", "pwd", 465, SetSendMail(myFunc))

func SetTLSConfig

func SetTLSConfig(c *tls.Config) MailerSetting

SetTLSConfig allows to set the TLS configuration used to connect the SMTP server.

type Message

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

Message represents an email.

func NewMessage

func NewMessage(settings ...MessageSetting) *Message

NewMessage creates a new message. It uses UTF-8 and quoted-printable encoding by default.

func (*Message) AddAlternative

func (msg *Message) AddAlternative(contentType, body string)

AddAlternative adds an alternative body to the message. Commonly used to send HTML emails that default to the plain text version for backward compatibility.

Example:

msg.SetBody("text/plain", "Hello!")
msg.AddAlternative("text/html", "<p>Hello!</p>")

More info: http://en.wikipedia.org/wiki/MIME#Alternative

func (*Message) Attach

func (msg *Message) Attach(f ...*File)

Attach attaches the files to the email.

func (*Message) DelHeader

func (msg *Message) DelHeader(field string)

DelHeader deletes a header field.

func (*Message) Embed

func (msg *Message) Embed(image ...*File)

Embed embeds the images to the email.

Example:

f, err := gomail.OpenFile("/tmp/image.jpg")
if err != nil {
	panic(err)
}
msg.Embed(f)
msg.SetBody("text/html", `<img src="cid:image.jpg" alt="My image" />`)

func (*Message) Export

func (msg *Message) Export() *mail.Message

Export converts the message into a net/mail.Message.

func (*Message) FormatAddress

func (msg *Message) FormatAddress(address, name string) string

FormatAddress formats an address and a name as a valid RFC 5322 address.

func (*Message) FormatDate

func (msg *Message) FormatDate(date time.Time) string

FormatDate formats a date as a valid RFC 5322 date.

func (*Message) GetBodyWriter

func (msg *Message) GetBodyWriter(contentType string) io.Writer

GetBodyWriter gets a writer that writes to the body. It can be useful with the templates from packages text/template or html/template.

Example:

w := msg.GetBodyWriter("text/plain")
t := template.Must(template.New("example").Parse("Hello {{.}}!"))
t.Execute(w, "Bob")

func (*Message) GetHeader

func (msg *Message) GetHeader(field string) []string

GetHeader gets a header field.

func (*Message) SetAddressHeader

func (msg *Message) SetAddressHeader(field, address, name string)

SetAddressHeader sets an address to the given header field.

func (*Message) SetBody

func (msg *Message) SetBody(contentType, body string)

SetBody sets the body of the message.

func (*Message) SetDateHeader

func (msg *Message) SetDateHeader(field string, date time.Time)

SetDateHeader sets a date to the given header field.

func (*Message) SetHeader

func (msg *Message) SetHeader(field string, value ...string)

SetHeader sets a value to the given header field.

func (*Message) SetHeaders

func (msg *Message) SetHeaders(h map[string][]string)

SetHeaders sets the message headers.

Example:

msg.SetHeaders(map[string][]string{
	"From":    {"alex@example.com"},
	"To":      {"bob@example.com", "cora@example.com"},
	"Subject": {"Hello"},
})

type MessageSetting

type MessageSetting func(msg *Message)

A MessageSetting can be used as an argument in NewMessage to configure an email.

func SetCharset

func SetCharset(charset string) MessageSetting

SetCharset is a message setting to set the charset of the email.

Example:

msg := gomail.NewMessage(SetCharset("ISO-8859-1"))

func SetEncoding

func SetEncoding(enc Encoding) MessageSetting

SetEncoding is a message setting to set the encoding of the email.

Example:

msg := gomail.NewMessage(SetEncoding(gomail.Base64))

type SendMailFunc

type SendMailFunc func(addr string, a smtp.Auth, from string, to []string, msg []byte) error

A SendMailFunc is a function to send emails with the same signature than smtp.SendMail.