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
- type Mailer
- type MailerSetting
- type 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) Reset()
- 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)
- func (msg *Message) SetRawHeader(field string, value ...string)
- type MessageSetting
- type SendMailFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
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. If used, gomail will // encode the data in base64 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" // Base64PreEncoded represents data that has already been base64 encoded Base64PreEncoded Encoding = "base64preencoded" )
type File ¶
type File struct {
Name string
MimeType string
Content []byte
ContentID string
// contains filtered or unexported fields
}
A File represents a file that can be attached or embedded in an email.
func CreateFile ¶
CreateFile creates a gomail.File from the given name and content.
func (*File) SetEncoding ¶
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"))
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 ¶
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>")
func (*Message) Embed ¶
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) FormatAddress ¶
FormatAddress formats an address and a name as a valid RFC 5322 address.
func (*Message) FormatDate ¶
FormatDate formats a date as a valid RFC 5322 date.
func (*Message) GetBodyWriter ¶
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) Reset ¶
func (msg *Message) Reset()
Reset resets all state in Message and returns all used buffers to the pool. The initial settings used to create the instance are preserved so the instance can be safely reused to create a new message.
func (*Message) SetAddressHeader ¶
SetAddressHeader sets an address to the given header field.
func (*Message) SetDateHeader ¶
SetDateHeader sets a date to the given header field.
func (*Message) SetHeaders ¶
SetHeaders sets the message headers.
Example:
msg.SetHeaders(map[string][]string{
"From": {"alex@example.com"},
"To": {"bob@example.com", "cora@example.com"},
"Subject": {"Hello"},
})
func (*Message) SetRawHeader ¶
SetRawHeader sets a value to the given header field without encoding
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))
Source Files
Directories