README
¶
A Go package for composing and sending email messages
This package implements a simple yet powerful API for email message composition and sending via an authenticating SMTP server, in Go.
Project Status
v0.2.1 Edge: Breaking changes to the API unlikely but possible until the v1.0 release. May be robust enough to use in production, though provided on "AS IS" basis. Vendoring recommended.
This package is under active development. If you encounter any problems or have any suggestions for improvement, please open an issue. Pull requests are welcome.
Overview
This package provides a fluid API for composing and sending email messages.
Any application needs one (and usually only one) Sender, representing an SMTP account connection information plus a sender Address.
A Message contains all the information required to create an email message. Usually, at least some parts of each message are templates to be filled with data from the rest of the application. Also, it is often convenient to define base messages on program initialization, and clone them for fine-tuning and send-out when needed.
Below is an overly-simplified example, to showcase the basic functionality. Note that by not defining From: and To: addresses for a message, they default to the sender address, which is convenient for system messaging.
package main
import (
"log"
"github.com/agext/email"
)
var (
host = "smtp.example.com"
user = "username"
pass = "password"
name = "Application mail"
addr = "app@example.com"
sender *email.Sender
contactFormMessage *email.Message
)
func main() {
var err error
// create a sender with a given configuration
sender, err = email.NewSender(host, user, pass, name, addr)
if err != nil {
log.Fatalln("invalid sender configuration: " + err.Error())
}
// create a message from scratch, to be used as a base for the actual messages
contactFormMessage = email.NewMessage(nil).
SubjectTemplate("Contact form message from {{.first}} {{.last}}").
TextTemplate(`
First Name: {{.first}}
Last Name: {{.last}}
Phone: {{.phone}}
Email: {{.email}}
`)
// ...
}
func sendContact(data map[string]interface{}) error {
// create a message from the base we created in main() - basically, clone all its data
msg := email.NewMessage(contactFormMessage)
// customize / adapt the message as needed...
// if the base messages are well thought out, the need should be minimal, if at all
// as an example, we could set the To: address based on the form data, to dispatch the messages
// to the person in the company who is most capable to handle it.
// send the message after composing it with the provided data
err := sender.Send(msg, data)
if err != nil {
log.Println(err, msg.Errors())
}
return err
}
Installation
go get github.com/agext/email
License
Package email is released under the Apache 2.0 license. See the LICENSE file for details.
Documentation
¶
Overview ¶
Package email provides a fluid API for composing and sending email messages.
Any application needs one (and usually only one) Sender, representing an SMTP account connection information plus a sender Address.
A Message contains all the information required to create an email message. Usually, at least some parts of each message are templates to be filled with data from the rest of the application. Also, it is often convenient to define base messages on program initialization, and clone them for fine-tuning and send-out when needed.
Below is an overly-simplified example, to showcase the basic functionality. Note that by not defining From: and To: addresses for a message, they default to the sender address, which is convenient for system messaging.
package main
import (
"log"
"github.com/agext/email"
)
var (
host = "smtp.example.com"
user = "username"
pass = "password"
name = "Application mail"
addr = "app@example.com"
sender *email.Sender
contactFormMessage *email.Message
)
func main() {
var err error
// create a sender with a given configuration
sender, err = email.NewSender(host, user, pass, name, addr)
if err != nil {
log.Fatalln("invalid sender configuration: " + err.Error())
}
// create a message from scratch, to be used as a base for the actual messages
contactFormMessage = email.NewMessage(nil).
SubjectTemplate("Contact form message from {{.first}} {{.last}}").
TextTemplate(`
First Name: {{.first}}
Last Name: {{.last}}
Phone: {{.phone}}
Email: {{.email}}
`)
// ...
}
func sendContact(data map[string]interface{}) error {
// create a message from the base we created in main() - basically, clone all its data
msg := email.NewMessage(contactFormMessage)
// customize / adapt the message as needed...
// if the base messages are well thought out, the need should be minimal, if at all
// as an example, we could set the To: address based on the form data, to dispatch the messages
// to the person in the company who is most capable to handle it.
// send the message after composing it with the provided date
err := sender.Send(msg, data)
if err != nil {
log.Println(err, msg.Errors())
}
return err
}
Index ¶
- func Base64Encode(src []byte) []byte
- func QEncode(src []byte, offset int) (dst []byte, pos int)
- func QEncodeIfNeeded(src []byte, offset int) (dst []byte)
- func QuotedPrintableEncode(src []byte) []byte
- func SeemsValidAddr(addr string) bool
- func Send(msg *Message, data interface{}) error
- type Address
- type CTE
- type Message
- func (m *Message) Attach(file ...string) *Message
- func (m *Message) AttachFile(name, ctype, file string) *Message
- func (m *Message) AttachObject(name, ctype string, data []byte) *Message
- func (m *Message) Bcc(addr ...*Address) *Message
- func (m *Message) Cc(addr ...*Address) *Message
- func (m *Message) Compose(data interface{}) []byte
- func (m *Message) Domain(domain string) *Message
- func (m *Message) Errors() (errs []error)
- func (m *Message) From(addr *Address) *Message
- func (m *Message) FromAddr() string
- func (m *Message) HasErrors() bool
- func (m *Message) Html(html interface{}, related ...Related) *Message
- func (m *Message) HtmlTemplate(tpl string, related ...Related) *Message
- func (m *Message) Part(ctype string, cte CTE, bytes []byte, related ...Related) *Message
- func (m *Message) Prepare() *Message
- func (m *Message) PrepareFresh() *Message
- func (m *Message) RecipientAddrs() []string
- func (m *Message) ReplyTo(addr *Address) *Message
- func (m *Message) Sender(s *Sender) *Message
- func (m *Message) Subject(subject interface{}) *Message
- func (m *Message) SubjectTemplate(tpl string) *Message
- func (m *Message) Text(text interface{}) *Message
- func (m *Message) TextTemplate(tpl string) *Message
- func (m *Message) To(addr ...*Address) *Message
- type Related
- type Sender
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Base64Encode ¶
Base64Encode encodes the src data using the base64 content transfer encoding specified by RFC 2045. The result is the equivalent of base64-encoding src using StdEncoding from the standard package encoding/base64, then breaking it into lines of maximum 76 characters, separated by CRLF. Besides convenience, this function also has the advantage of combining the encoding and line-breaking steps into a single pass, with a single buffer allocation.
func QEncode ¶
QEncode encodes the src data using the q-encoding encoded-word syntax specified by RFC 2047. Since RFC 2047 requires that each line of a header that includes encoded-word text be no longer than 76, this function takes an offset argument for the length of the current header line already used up, e.g. by the header name, colon and space.
func QEncodeIfNeeded ¶
QEncodeIfNeeded q-encodes the src data only if it contains 'unsafe' characters.
func QuotedPrintableEncode ¶
QuotedPrintableEncode encodes the src data using the quoted-printable content transfer encoding specified by RFC 2045. Although RFC 2045 does not require that UTF multi-byte characters be kept on the same line of encoded text, this function does so.
func SeemsValidAddr ¶
SeemsValidAddr does a very loose check on addr, to weed out obviously invalid addresses. This function only checks that addr contains one and only one '@', followed by a domain name that has a TLD part.
Types ¶
type Address ¶
Address represents a human-friendly email address: a name plus the actual address.
func NewAddress ¶
NewAddress creates a new Address enforcing a very basic validity check - see `SeemsValidAddr`.
type Message ¶
Message represents all the information necessary for composing an email message with optional external data, and sending it via a Sender.
func NewMessage ¶
NewMessage creates a new Message, deep-copying from `msg`, if provided.
func QuickMessage ¶
QuickMessage creates a Message with the subject and the body provided. Alternative text and HTML body versions can be provided, in this order.
func (*Message) AttachFile ¶
AttachFile attaches a file specified by its filesystem path, setting its name and type to the provided values.
func (*Message) AttachObject ¶
AttachObject creates an attachment with the name, type and data provided.
func (*Message) Bcc ¶
Bcc sets the (optional) Bcc: email addresses. Last call overrides any previous calls, replacing rather than adding to the list.
func (*Message) Cc ¶
Cc sets the (optional) Cc: email addresses. Last call overrides any previous calls, replacing rather than adding to the list.
func (*Message) Compose ¶
Compose merges the `data` into the receiver's templates and creates the body of the SMTP message to be sent.
func (*Message) Domain ¶
Domain sets the domain portion of the generated message Id.
If not specified, the domain is extracted from the sender email address - which is the right choice for most applications.
func (*Message) Errors ¶
Errors returns the list of errors associated with the receiver, then resets the internal list.
func (*Message) Html ¶
Html sets the HTML version of the message body to the provided content. Optionally, related objects can be specified for inclusion.
func (*Message) HtmlTemplate ¶
HtmlTemplate sets the HTML version of the message body to the provided template. Optionally, related objects can be specified for inclusion.
func (*Message) Part ¶
Part adds an alternative part to the message. For a plain-text and/or an HTML body use the convenience methods: Text, TextTemplate, Html or HtmlTemplate.
func (*Message) Prepare ¶
Prepare reads all the files referenced by the message at attachments or related items.
If the message was already prepared and no new files have been added, it is no-op.
func (*Message) PrepareFresh ¶
PrepareFresh forces a new preparation of the message, even if there were no changes to the referred files since the previous one.
func (*Message) RecipientAddrs ¶
RecipientAddrs returns a list of email addresses with all the recipients for the message.
It includes addresses from the To, CC and BCC fields.
func (*Message) ReplyTo ¶
ReplyTo sets the (optional) Reply-To: email address. A `*Address` argument is expected for consistency, although only the email address part is used.
func (*Message) SubjectTemplate ¶
SubjectTemplate sets a template for the subject of the message.
func (*Message) Text ¶
Text sets the plain-text version of the message body to the provided content.
func (*Message) TextTemplate ¶
TextTemplate sets the plain-text version of the message body to the provided template.
type Related ¶
type Related struct {
// contains filtered or unexported fields
}
Related represents a multipart/related item.
func RelatedFile ¶
RelatedFile creates a Related structure from the provided file information.
func RelatedObject ¶
RelatedObject creates a Related structure from the provided data.
type Sender ¶
type Sender struct {
// contains filtered or unexported fields
}
Sender represents the SMTP credentials along with the (optional) Address of a sender.
func NewSender ¶
NewSender creates a new Sender from the provided information.
The `host` may include a port number, which defaults to 25. That is, "example.com" and "example.com:25" are equivalent. The `addr` parameters are optional and may be either an email address or a name followed by an email address.
func (*Sender) SetDefault ¶
SetDefault sets the receiver as the default sender.
Source Files