README
¶
Wail
Overview
Wail is a simple package to send emails. It supports:
- SSL/TLS encryption
- Base64 and quoted printable encoding
- Authentication on server
- Plain text and HTML messages
- Attachments
Installation
To install the package run the following command:
go get -u github.com/rub1q/wail
Usage
Step #1. Creating a SMTP config
First things first you need to define a SMTP config. For example as follows:
cfg := &wail.SmtpConfig{
Server: wail.ServerConfig{
Host: "smtp.example.com",
Port: 465,
NeedAuth: true,
ConnectTimeout: 10 * time.Second,
EncryptType: wail.EncryptSSL,
},
Sender: wail.SenderConfig{
Name: "Alex",
Login: os.Getenv("SENDER_LOGIN"),
Password: os.Getenv("SENDER_PWD"),
},
TlsConfig: &tls.Config{
InsecureSkipVerify: true,
},
}
A few words about config
By default is using EncryptType = EncryptSSL. If the SMTP server supports a STARTTLS extension you can change the EncryptType value to EncryptTLS
The sender's Name is using to show it above your emails. If you do not need an authentication set the NeedAuth to false. Hence, the sender's Login and Password could be omitted
TlsConfig is using to specify additional setting for establishing encrypted connection with the SMTP server
Note: leave the default
TlsConfigvalue if you do not know how to use it
Step #2. Creating a client and establishing a connection
After the config is done you need to create a new client. Call NewClient() and pass it your config:
c := wail.NewClient(cfg)
Then call Dial() to establish a connection with the server. Dial() could return an error if something go wrong
err := c.Dial()
if err != nil {
log.Fatal(err.Error())
}
defer c.Close()
Step #3. Creating an email
The next step is creating an email object. Call the NewMail() method to do it
mailCfg := &wail.MailConfig{
Charset: wail.UTF8,
Encoding: wail.Base64,
}
mail := wail.NewMail(mailCfg)
NewMail() is accepting MailConfig structure as a parameter. You can pass nil if you want to use a default config values
Call SetSubject() to set the email subject:
mail.SetSubject("Test subject")
Then specify all recipients by using To(), CopyTo() and BlindCopyTo() methods. For example:
err = mail.To("example1@example.com", "example2@example.com")
if err != nil {
log.Fatal(err.Error())
}
err = mail.CopyTo("example3@example.com")
if err != nil {
log.Fatal(err.Error())
}
All three methods could return an error
Step #4. Creating a message
At the momemt Wail supports 4 message Content-Types:
text/plaintext/htmlmultipart/mixedmultipart/alternative
For each Content-Type methods and structures are provided
Assume you want to send a text\plain message. Call the NewTextMessage() method:
mt := wail.NewTextMessage()
And then provide a text you want to send:
mt.Set(wail.TextPlain, []byte("Hello, World"))
Set() accepts TextPlain or TextHtml as the first parameter. Use the last one if you need to send a HTML message
Step #5. Sending the email
After you have created the message call SetMessage() and pass it your message object.
mail.SetMessage(&mt)
Finally, call Send() with an email object argument to send an email:
err = c.Send(mail)
if err != nil {
log.Fatal(err.Error())
}
License
Documentation
¶
Index ¶
- Constants
- func LoginAuth(username, password string) smtp.Auth
- func XoAuth2Auth(username string, token oauth2.TokenSource) smtp.Auth
- type Attachment
- type Mail
- type MailConfig
- type Message
- type MultipartAltMessage
- type MultipartMixedMessage
- type SenderConfig
- type ServerConfig
- type SmtpClient
- type SmtpConfig
- type TextMessage
Constants ¶
const ( // EncryptSSL is a default encryption type. Use this // type if you want to encrypt your connection but // you don't need to call STARTTLS command. // // This encryption type may be used if you establishing // a connection on port 465 EncryptSSL encryption = iota // EncryptTLS encryption type is used if you want to // encrypt connection by calling STARTTLS command. // // This encryption type may be used if you establishing // a connection on port 587 or 25 (the last one is not // recommended to use) EncryptTLS // No encryption EncryptNone )
const ( QuotedPrintable encoding = "quoted-printable" Base64 encoding = "base64" )
const ( UTF8 charset = "UTF-8" ISO_8859_1 charset = "ISO-8859-1" US_ASCII charset = "US-ASCII" )
const ( TextPlain contentType = iota TextHtml )
Variables ¶
This section is empty.
Functions ¶
func XoAuth2Auth ¶
func XoAuth2Auth(username string, token oauth2.TokenSource) smtp.Auth
Types ¶
type Attachment ¶
type Attachment struct {
// contains filtered or unexported fields
}
func (*Attachment) GetContent ¶
func (a *Attachment) GetContent(mb *mimeBuilder) string
func (*Attachment) GetContentType ¶
func (a *Attachment) GetContentType() contentType
func (*Attachment) ReadFromFile ¶
func (a *Attachment) ReadFromFile(filePath string) error
ReadFromFile reads the content of a file that is stored in filePath
func (*Attachment) SetAsBinary ¶
func (a *Attachment) SetAsBinary(name string, content []byte)
SetAsBinary sets names and file content in cases when you can't read it from file (e.g. a file content stores in DB)
type Mail ¶
type Mail struct {
// contains filtered or unexported fields
}
func NewMail ¶
func NewMail(cfg *MailConfig) *Mail
func (*Mail) BlindCopyTo ¶
BlindCopyTo sets email addresses to which an email blind copy will be sent
func (*Mail) SetSubject ¶
SetSubject sets an email subject. Subject could be empty
type MailConfig ¶
type MailConfig struct {
Charset charset
Encoding encoding
}
var DefaultMailConfig MailConfig = MailConfig{ Charset: UTF8, Encoding: Base64, }
type Message ¶
type Message interface {
// GetContent returns formatted message body text
GetContent(mb *mimeBuilder) string
// GetContentType returns a content type of the message
// that is used for assembling a result message
GetContentType() contentType
}
type MultipartAltMessage ¶
type MultipartAltMessage struct {
// contains filtered or unexported fields
}
func NewMultipartAltMessage ¶
func NewMultipartAltMessage() MultipartAltMessage
func (*MultipartAltMessage) GetContent ¶
func (m *MultipartAltMessage) GetContent(mb *mimeBuilder) string
func (*MultipartAltMessage) GetContentType ¶
func (m *MultipartAltMessage) GetContentType() contentType
func (*MultipartAltMessage) SetHtmlText ¶
func (m *MultipartAltMessage) SetHtmlText(text []byte, order int)
SetHtmlText sets an html part of the message with specified order (priority)
Note: Anti-spam software penalizing messages with very different text in a multipart/alternative message
func (*MultipartAltMessage) SetPlainText ¶
func (m *MultipartAltMessage) SetPlainText(text []byte, order int)
SetPlainText sets a plain part of the message with specified order (priority)
Note: Anti-spam software penalizing messages with very different text in a multipart/alternative message
type MultipartMixedMessage ¶
type MultipartMixedMessage struct {
// contains filtered or unexported fields
}
func NewMultipartMixedMessage ¶
func NewMultipartMixedMessage() MultipartMixedMessage
NewMultipartMixedMessage creates a new multipart/mixed message object
func (*MultipartMixedMessage) AddAttachment ¶
func (m *MultipartMixedMessage) AddAttachment(attach Attachment)
AddAttachment adds an attachment to the message
func (*MultipartMixedMessage) GetContent ¶
func (m *MultipartMixedMessage) GetContent(mb *mimeBuilder) string
func (*MultipartMixedMessage) GetContentType ¶
func (m *MultipartMixedMessage) GetContentType() contentType
func (*MultipartMixedMessage) SetText ¶
func (m *MultipartMixedMessage) SetText(ctype contentType, text []byte)
SetText sets a text content type (plain or html) and message text
type SenderConfig ¶
type SenderConfig struct {
// Name specified in this field will be displayed above emails
Name string
// Login is the email address from which an emails will be sent.
// It is also will be used for authentication on server (if required)
Login string
// Password from your email account. It is used for authentication on server
Password string
}
SenderConfig contains information about the sender
type ServerConfig ¶
type ServerConfig struct {
// Host represents the SMTP server address
Host string
// Port represents the SMTP server port
Port uint16
ConnectTimeout time.Duration
// NeedAuth is used to indicate that the server
// demands an authentication before sending emails
NeedAuth bool
// EncryptType is an encryption type (SSL, TLS or none)
EncryptType encryption
// contains filtered or unexported fields
}
ServerConfig contains information about the SMTP server
type SmtpClient ¶
type SmtpClient struct {
// contains filtered or unexported fields
}
SmtpClient represents a client that negotiate with the server
func (*SmtpClient) Close ¶
func (s *SmtpClient) Close() error
Close closes a connection with the server by sending the QUIT command
func (*SmtpClient) Dial ¶
func (s *SmtpClient) Dial() error
Dial establishes a connection with the server using parameters from SMTP config. If an error occurs during a connection Dial will return it
func (*SmtpClient) Send ¶
func (s *SmtpClient) Send(m *Mail) error
Send assembles the message and sends it to the server
type SmtpConfig ¶
type SmtpConfig struct {
// Server represents the server configuration
Server ServerConfig
// Sender represents the sender configuration
Sender SenderConfig
// TlsConfig is the TLS configuration used for TLS or SSL connections.
//
// Note: leave the default value if you don't know how to use it
TlsConfig *tls.Config
}
SmtpConfig contains information required for establishing connection and generating message
type TextMessage ¶
type TextMessage struct {
// contains filtered or unexported fields
}
func NewTextMessage ¶
func NewTextMessage() TextMessage
NewTextMessage creates a new text message object
func (*TextMessage) GetContent ¶
func (t *TextMessage) GetContent(mb *mimeBuilder) string
func (*TextMessage) GetContentType ¶
func (t *TextMessage) GetContentType() contentType
func (*TextMessage) Set ¶
func (t *TextMessage) Set(ctype contentType, text []byte)
Set sets a text content type (plain or html) and message text
Source Files
Directories