README

email

Build Status GoDoc

Robust and flexible email library for Go

Email for humans

The email package is designed to be simple to use, but flexible enough so as not to be restrictive. The goal is to provide an email interface for humans.

The email package currently supports the following:

  • From, To, Bcc, and Cc fields
  • Email addresses in both "test@example.com" and "First Last <test@example.com>" format
  • Text and HTML Message Body
  • Attachments
  • Read Receipts
  • Custom headers
  • More to come!
Installation

go get github.com/jordan-wright/email

Note: Version > 1 of this library requires Go v1.5 or above.

If you need compatibility with previous Go versions, you can use the previous package at gopkg.in/jordan-wright/email.v1

Examples
Sending email using Gmail
e := email.NewEmail()
e.From = "Jordan Wright <test@gmail.com>"
e.To = []string{"test@example.com"}
e.Bcc = []string{"test_bcc@example.com"}
e.Cc = []string{"test_cc@example.com"}
e.Subject = "Awesome Subject"
e.Text = []byte("Text Body is, of course, supported!")
e.HTML = []byte("<h1>Fancy HTML is supported, too!</h1>")
e.Send("smtp.gmail.com:587", smtp.PlainAuth("", "test@gmail.com", "password123", "smtp.gmail.com"))
Another Method for Creating an Email

You can also create an email directly by creating a struct as follows:

e := &email.Email {
	To: []string{"test@example.com"},
	From: "Jordan Wright <test@gmail.com>",
	Subject: "Awesome Subject",
	Text: []byte("Text Body is, of course, supported!"),
	HTML: []byte("<h1>Fancy HTML is supported, too!</h1>"),
	Headers: textproto.MIMEHeader{},
}
Creating an Email From an io.Reader

You can also create an email from any type that implements the io.Reader interface by using email.NewEmailFromReader.

Attaching a File
e := NewEmail()
e.AttachFile("test.txt")
A Pool of Reusable Connections
(var ch <-chan *email.Email)
p := email.NewPool(
	"smtp.gmail.com:587",
	4,
	smtp.PlainAuth("", "test@gmail.com", "password123", "smtp.gmail.com"),
)
for i := 0; i < 4; i++ {
	go func() {
		for e := range ch {
			p.Send(e, 10 * time.Second)
		}
	}()
}
Documentation

http://godoc.org/github.com/jordan-wright/email

Other Sources

Sections inspired by the handy gophermail project.

Contributors

I'd like to thank all the contributors and maintainers of this package.

A special thanks goes out to Jed Denlea jeddenlea for his numerous contributions and optimizations.

Expand ▾ Collapse ▴

Documentation

Overview

    Package email is designed to provide an "email interface for humans." Designed to be robust and flexible, the email package aims to make sending email easy without getting in the way.

    Index

    Constants

    View Source
    const (
    	MaxLineLength = 76 // MaxLineLength is the maximum line length per RFC 2045
    
    )

    Variables

    View Source
    var (
    	ErrClosed  = errors.New("pool closed")
    	ErrTimeout = errors.New("timed out")
    )
    View Source
    var ErrMissingBoundary = errors.New("No boundary found for multipart entity")

      ErrMissingBoundary is returned when there is no boundary given for a multipart entity

      View Source
      var ErrMissingContentType = errors.New("No Content-Type found for MIME entity")

        ErrMissingContentType is returned when there is no "Content-Type" header for a MIME entity

        Functions

        This section is empty.

        Types

        type Attachment

        type Attachment struct {
        	Filename    string
        	ContentType string
        	Header      textproto.MIMEHeader
        	Content     []byte
        	HTMLRelated bool
        }

          Attachment is a struct representing an email attachment. Based on the mime/multipart.FileHeader struct, Attachment contains the name, MIMEHeader, and content of the attachment in question

          type Email

          type Email struct {
          	ReplyTo     []string
          	From        string
          	To          []string
          	Bcc         []string
          	Cc          []string
          	Subject     string
          	Text        []byte // Plaintext message (optional)
          	HTML        []byte // Html message (optional)
          	Sender      string // override From as SMTP envelope sender (optional)
          	Headers     textproto.MIMEHeader
          	Attachments []*Attachment
          	ReadReceipt []string
          }

            Email is the type used for email messages

            func NewEmail

            func NewEmail() *Email

              NewEmail creates an Email, and returns the pointer to it.

              func NewEmailFromReader

              func NewEmailFromReader(r io.Reader) (*Email, error)

                NewEmailFromReader reads a stream of bytes from an io.Reader, r, and returns an email struct containing the parsed data. This function expects the data in RFC 5322 format.

                func (*Email) Attach

                func (e *Email) Attach(r io.Reader, filename string, c string) (a *Attachment, err error)

                  Attach is used to attach content from an io.Reader to the email. Required parameters include an io.Reader, the desired filename for the attachment, and the Content-Type The function will return the created Attachment for reference, as well as nil for the error, if successful.

                  func (*Email) AttachFile

                  func (e *Email) AttachFile(filename string) (a *Attachment, err error)

                    AttachFile is used to attach content to the email. It attempts to open the file referenced by filename and, if successful, creates an Attachment. This Attachment is then appended to the slice of Email.Attachments. The function will then return the Attachment for reference, as well as nil for the error, if successful.

                    func (*Email) Bytes

                    func (e *Email) Bytes() ([]byte, error)

                      Bytes converts the Email object to a []byte representation, including all needed MIMEHeaders, boundaries, etc.

                      func (*Email) Send

                      func (e *Email) Send(addr string, a smtp.Auth) error

                        Send an email using the given host and SMTP auth (optional), returns any error thrown by smtp.SendMail This function merges the To, Cc, and Bcc fields and calls the smtp.SendMail function using the Email.Bytes() output as the message

                        func (*Email) SendWithStartTLS

                        func (e *Email) SendWithStartTLS(addr string, a smtp.Auth, t *tls.Config) error

                          SendWithStartTLS sends an email over TLS using STARTTLS with an optional TLS config.

                          The TLS Config is helpful if you need to connect to a host that is used an untrusted certificate.

                          func (*Email) SendWithTLS

                          func (e *Email) SendWithTLS(addr string, a smtp.Auth, t *tls.Config) error

                            SendWithTLS sends an email over tls with an optional TLS config.

                            The TLS Config is helpful if you need to connect to a host that is used an untrusted certificate.

                            type Pool

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

                            func NewPool

                            func NewPool(address string, count int, auth smtp.Auth, opt_tlsConfig ...*tls.Config) (pool *Pool, err error)

                            func (*Pool) Close

                            func (p *Pool) Close()

                              Close immediately changes the pool's state so no new connections will be created, then gets and closes the existing ones as they become available.

                              func (*Pool) Send

                              func (p *Pool) Send(e *Email, timeout time.Duration) (err error)

                                Send sends an email via a connection pulled from the Pool. The timeout may be <0 to indicate no timeout. Otherwise reaching the timeout will produce and error building a connection that occurred while we were waiting, or otherwise ErrTimeout.

                                func (*Pool) SetHelloHostname

                                func (p *Pool) SetHelloHostname(h string)

                                  SetHelloHostname optionally sets the hostname that the Go smtp.Client will use when doing a HELLO with the upstream SMTP server. By default, Go uses "localhost" which may not be accepted by certain SMTP servers that demand an FQDN.

                                  Source Files