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, v ...interface{}) (*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 SetLocalHost(h string) 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, v ...interface{}) (*File, error)

OpenFile opens a file on disk to create a gomail.File. Overload func(filename, original_filename string)

type Mailer

type Mailer struct {
	io.Closer
	// 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 SetLocalHost

func SetLocalHost(h string) MailerSetting

SetLocalHost allows HELO msg to be send with customized string.

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.