mail

package module
v0.2.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 7, 2022 License: MIT Imports: 26 Imported by: 237

README

go-mail - Simple and easy way to send mails in Go

GoDoc codecov Go Report Card Build Status Mentioned in Awesome Go REUSE status buy ma a coffee

The main idea of this library was to provide a simple interface to sending mails for my JS-Mailer project. It quickly evolved into a full-fledged mail library.

go-mail follows idiomatic Go style and best practice. It's only dependency is the Go Standard Library. It combines a lot of functionality from the standard library to give easy and convenient access to mail and SMTP related tasks.

Parts of this library (especially some parts of msgwriter.go) have been forked/ported from the go-mail/mail respectively go-gomail/gomail which both seems to not be maintained anymore.

Features

Some of the features of this library:

  • Only Standard Library dependant
  • Modern, idiomatic Go
  • Sane and secure defaults
  • Explicit SSL/TLS support
  • Implicit StartTLS support with different policies
  • Makes use of contexts for a better control flow and timeout/cancelation handling
  • SMTP Auth support (LOGIN, PLAIN, CRAM-MD)
  • RFC5322 compliant mail address validation
  • Support for common mail header field generation (Message-ID, Date, Bulk-Precedence, Priority, etc.)
  • Reusing the same SMTP connection to send multiple mails
  • Support for attachments and inline embeds (from file system, io.Reader or embed.FS)
  • Support for different encodings
  • Support sending mails via a local sendmail command
  • Message object satisfies io.WriteTo and io.Reader interfaces
  • Support for Go's html/template and text/template (as message body, alternative part or attachment/emebed)
  • Output to file support which allows storing mail messages as e. g. .eml files to disk to open them in a MUA

go-mail works like a programatic email client and provides lots of methods and functionalities you would consider standard in a MUA.

Examples

The package is shipped with GoDoc example code for difference scenarios. Check them out on its GoDoc page

For ease of use, here is a full usage example:

package main

import (
	"fmt"
	"github.com/wneessen/go-mail"
	"os"
)

func main() {
	// Create a new mail message
	m := mail.NewMsg()

	// To set address header fields like "From", "To", "Cc" or "Bcc" you have different methods
	// at your hands. Some perform input validation, some ignore invalid addresses. Some perform
	// the formating for you.
	// 
	if err := m.FromFormat("Toni Tester", "sender@example.com"); err != nil {
		fmt.Printf("failed to set FROM address: %s\n", err)
		os.Exit(1)
	}
	if err := m.To(`"Max Mastermind <rcpt@example.com>"`); err != nil {
		fmt.Printf("failed to set TO address: %s\n", err)
		os.Exit(1)
	}
	m.CcIgnoreInvalid("cc@example.com", "invalidaddress+example.com")

	// Set a subject line
	m.Subject("This is a great email")

	// And some other common headers...
	//
	// Sets a valid "Date" header field with the current time
	m.SetDate()
	//
	// Generates a valid and unique "Message-ID"
	m.SetMessageID()
	//
	// Sets the "Precedence"-Header to "bulk" to indicate a "bulk mail"
	m.SetBulk()
	//
	// Set a "high" importance to the mail (this sets several Header fields to 
	// satisfy the different common mail clients like Mail.app and Outlook)
	m.SetImportance(mail.ImportanceHigh)

	// Add your mail message to body
	m.SetBodyString(mail.TypeTextPlain, "This is a great message body text.")

	// Attach a file from your local FS
	// We override the attachment name using the WithFileName() Option
	m.AttachFile("/home/ttester/test.txt", mail.WithFileName("attachment.txt"))

	// Next let's create a Client
	// We have lots of With* options at our disposal to stear the Client. It will set sane
	// options by default, though
	//
	// Let's assume we need to perform SMTP AUTH with the sending server, though. Since we
	// use SMTP PLAIN AUTH, let's also make sure to enforce strong TLS
	host := "relay.example.com"
	c, err := mail.NewClient(host,
		mail.WithSMTPAuth(mail.SMTPAuthPlain), mail.WithUsername("ttester"),
		mail.WithPassword("V3rySecUr3!Pw."), mail.WithTLSPolicy(mail.TLSMandatory))
	if err != nil {
		fmt.Printf("failed to create new mail client: %s\n", err)
		os.Exit(1)
	}

	// Now that we have our client, we can connect to the server and send our mail message
	// via the convenient DialAndSend() method. You have the option to Dial() and Send()
	// seperately as well
	if err := c.DialAndSend(m); err != nil {
		fmt.Printf("failed to send mail: %s\n", err)
		os.Exit(1)
	}

	fmt.Println("Mail successfully sent.")
}

Contributors

Thanks to the following people for contributing to the go-mail codebase:

Documentation

Overview

Package mail provides a simple and easy way to send mails with Go

Index

Examples

Constants

View Source 
const (
	// DefaultPort is the default connection port cto the SMTP server
	DefaultPort = 25

	// DefaultTimeout is the default connection timeout
	DefaultTimeout = time.Second * 15

	// DefaultTLSPolicy is the default STARTTLS policy
	DefaultTLSPolicy = TLSMandatory

	// DefaultTLSMinVersion is the minimum TLS version required for the connection
	// Nowadays TLS1.2 should be the sane default
	DefaultTLSMinVersion = tls.VersionTLS12
)

Defaults

View Source 
const DoubleNewLine = "\r\n\r\n"

DoubleNewLine represents a double new line that can be used by the msgWriter to indicate a new segement of the mail

View Source 
const MaxHeaderLength = 76

MaxHeaderLength defines the maximum line length for a mail header RFC 2047 suggests 76 characters

View Source 
const SendmailPath = "/usr/sbin/sendmail"

SendmailPath is the default system path to the sendmail binary

View Source 
const SingleNewLine = "\r\n"

SingleNewLine represents a new line that can be used by the msgWriter to issue a carriage return

View Source 
const VERSION = "0.2.4"

VERSION is used in the default user agent string

Variables

View Source 
var (
	// ErrPlainAuthNotSupported should be used if the target server does not support the "PLAIN" schema
	ErrPlainAuthNotSupported = errors.New("server does not support SMTP AUTH type: PLAIN")

	// ErrLoginAuthNotSupported should be used if the target server does not support the "LOGIN" schema
	ErrLoginAuthNotSupported = errors.New("server does not support SMTP AUTH type: LOGIN")

	// ErrCramMD5AuthNotSupported should be used if the target server does not support the "CRAM-MD5" schema
	ErrCramMD5AuthNotSupported = errors.New("server does not support SMTP AUTH type: CRAM-MD5")
)

SMTP Auth related static errors

View Source 
var (
	// ErrInvalidPort should be used if a port is specified that is not valid
	ErrInvalidPort = errors.New("invalid port number")

	// ErrInvalidTimeout should be used if a timeout is set that is zero or negative
	ErrInvalidTimeout = errors.New("timeout cannot be zero or negative")

	// ErrInvalidHELO should be used if an empty HELO sting is provided
	ErrInvalidHELO = errors.New("invalid HELO/EHLO value - must not be empty")

	// ErrInvalidTLSConfig should be used if an empty tls.Config is provided
	ErrInvalidTLSConfig = errors.New("invalid TLS config")

	// ErrNoHostname should be used if a Client has no hostname set
	ErrNoHostname = errors.New("hostname for client cannot be empty")

	// ErrDeadlineExtendFailed should be used if the extension of the connection deadline fails
	ErrDeadlineExtendFailed = errors.New("connection deadline extension failed")

	// ErrNoActiveConnection should be used when a method is used that requies a server connection
	// but is not yet connected
	ErrNoActiveConnection = errors.New("not connected to SMTP server")

	// ErrServerNoUnencoded should be used when 8BIT encoding is selected for a message, but
	// the server does not offer 8BITMIME mode
	ErrServerNoUnencoded = errors.New("message is 8bit unencoded, but server does not support 8BITMIME")
)
View Source 
var (
	// ErrNoFromAddress should be used when a FROM address is requrested but not set
	ErrNoFromAddress = errors.New("no FROM address set")

	// ErrNoRcptAddresses should be used when the list of RCPTs is empty
	ErrNoRcptAddresses = errors.New("no recipient addresses set")
)

Functions

This section is empty.

Types

type AddrHeader 

type AddrHeader string

AddrHeader represents a address related mail Header field name 

const (
	// HeaderBcc is the "Blind Carbon Copy" header field
	HeaderBcc AddrHeader = "Bcc"

	// HeaderCc is the "Carbon Copy" header field
	HeaderCc AddrHeader = "Cc"

	// HeaderEnvelopeFrom is the envelope FROM header field
	// It's not included in the mail body but only used by the Client for the envelope
	HeaderEnvelopeFrom AddrHeader = "EnvelopeFrom"

	// HeaderFrom is the "From" header field
	HeaderFrom AddrHeader = "From"

	// HeaderTo is the "Receipient" header field
	HeaderTo AddrHeader = "To"
)

List of common address header field names

func (AddrHeader) String added in v0.1.4 

func (a AddrHeader) String() string

String returns the address header string based on the given AddrHeader

type Charset 

type Charset string

Charset represents a character set for the encoding 

const (
	// CharsetUTF7 represents the "UTF-7" charset
	CharsetUTF7 Charset = "UTF-7"

	// CharsetUTF8 represents the "UTF-8" charset
	CharsetUTF8 Charset = "UTF-8"

	// CharsetASCII represents the "US-ASCII" charset
	CharsetASCII Charset = "US-ASCII"

	// CharsetISO88591 represents the "ISO-8859-1" charset
	CharsetISO88591 Charset = "ISO-8859-1"

	// CharsetISO88592 represents the "ISO-8859-2" charset
	CharsetISO88592 Charset = "ISO-8859-2"

	// CharsetISO88593 represents the "ISO-8859-3" charset
	CharsetISO88593 Charset = "ISO-8859-3"

	// CharsetISO88594 represents the "ISO-8859-4" charset
	CharsetISO88594 Charset = "ISO-8859-4"

	// CharsetISO88595 represents the "ISO-8859-5" charset
	CharsetISO88595 Charset = "ISO-8859-5"

	// CharsetISO88596 represents the "ISO-8859-6" charset
	CharsetISO88596 Charset = "ISO-8859-6"

	// CharsetISO88597 represents the "ISO-8859-7" charset
	CharsetISO88597 Charset = "ISO-8859-7"

	// CharsetISO88599 represents the "ISO-8859-9" charset
	CharsetISO88599 Charset = "ISO-8859-9"

	// CharsetISO885913 represents the "ISO-8859-13" charset
	CharsetISO885913 Charset = "ISO-8859-13"

	// CharsetISO885914 represents the "ISO-8859-14" charset
	CharsetISO885914 Charset = "ISO-8859-14"

	// CharsetISO885915 represents the "ISO-8859-15" charset
	CharsetISO885915 Charset = "ISO-8859-15"

	// CharsetISO885916 represents the "ISO-8859-16" charset
	CharsetISO885916 Charset = "ISO-8859-16"

	// CharsetISO2022JP represents the "ISO-2022-JP" charset
	CharsetISO2022JP Charset = "ISO-2022-JP"

	// CharsetISO2022KR represents the "ISO-2022-KR" charset
	CharsetISO2022KR Charset = "ISO-2022-KR"

	// CharsetWindows1250 represents the "windows-1250" charset
	CharsetWindows1250 Charset = "windows-1250"

	// CharsetWindows1251 represents the "windows-1251" charset
	CharsetWindows1251 Charset = "windows-1251"

	// CharsetWindows1252 represents the "windows-1252" charset
	CharsetWindows1252 Charset = "windows-1252"

	// CharsetWindows1255 represents the "windows-1255" charset
	CharsetWindows1255 Charset = "windows-1255"

	// CharsetWindows1256 represents the "windows-1256" charset
	CharsetWindows1256 Charset = "windows-1256"

	// CharsetKOI8R represents the "KOI8-R" charset
	CharsetKOI8R Charset = "KOI8-R"

	// CharsetKOI8U represents the "KOI8-U" charset
	CharsetKOI8U Charset = "KOI8-U"

	// CharsetBig5 represents the "Big5" charset
	CharsetBig5 Charset = "Big5"

	// CharsetGB18030 represents the "GB18030" charset
	CharsetGB18030 Charset = "GB18030"

	// CharsetGB2312 represents the "GB2312" charset
	CharsetGB2312 Charset = "GB2312"

	// CharsetTIS620 represents the "TIS-620" charset
	CharsetTIS620 Charset = "TIS-620"

	// CharsetEUCKR represents the "EUC-KR" charset
	CharsetEUCKR Charset = "EUC-KR"

	// CharsetShiftJIS represents the "Shift_JIS" charset
	CharsetShiftJIS Charset = "Shift_JIS"

	// CharsetUnknown represents the "Unknown" charset
	CharsetUnknown Charset = "Unknown"

	// CharsetGBK represents the "GBK" charset
	CharsetGBK Charset = "GBK"
)

List of common charsets

func (Charset) String 

func (c Charset) String() string

String is a standard method to convert an Charset into a printable format

type Client 

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

Client is the SMTP client struct

func NewClient 

func NewClient(h string, o ...Option) (*Client, error)

NewClient returns a new Session client object

Example

Code example for the NewClient method 

package main

import (
	"github.com/wneessen/go-mail"
)

func main() {
	c, err := mail.NewClient("mail.example.com")
	if err != nil {
		panic(err)
	}
	_ = c
}

func (*Client) Close 

func (c *Client) Close() error

Close closes the Client connection

func (*Client) DialAndSend 

func (c *Client) DialAndSend(ml ...*Msg) error

DialAndSend establishes a connection to the SMTP server with a default context.Background and sends the mail

Example

Code example for the Client.DialAndSend method 

package main

import (
	"fmt"
	"github.com/wneessen/go-mail"
	"os"
)

func main() {
	from := "Toni Tester <toni@example.com>"
	to := "Alice <alice@example.com>"
	server := "mail.example.com"

	m := mail.NewMsg()
	if err := m.From(from); err != nil {
		fmt.Printf("failed to set FROM address: %s", err)
		os.Exit(1)
	}
	if err := m.To(to); err != nil {
		fmt.Printf("failed to set TO address: %s", err)
		os.Exit(1)
	}
	m.Subject("This is a great subject")

	c, err := mail.NewClient(server)
	if err != nil {
		fmt.Printf("failed to create mail client: %s", err)
		os.Exit(1)
	}
	if err := c.DialAndSend(m); err != nil {
		fmt.Printf("failed to send mail: %s", err)
		os.Exit(1)
	}
}

func (*Client) DialWithContext 

func (c *Client) DialWithContext(pc context.Context) error

DialWithContext establishes a connection cto the SMTP server with a given context.Context

func (*Client) Reset 

func (c *Client) Reset() error

Reset sends the RSET command to the SMTP client

func (*Client) Send 

func (c *Client) Send(ml ...*Msg) error

Send sends out the mail message

func (*Client) ServerAddr 

func (c *Client) ServerAddr() string

ServerAddr returns the currently set combination of hostname and port

func (*Client) SetPassword 

func (c *Client) SetPassword(p string)

SetPassword overrides the current password string with the given value

func (*Client) SetSMTPAuth 

func (c *Client) SetSMTPAuth(a SMTPAuthType)

SetSMTPAuth overrides the current SMTP AUTH type setting with the given value

func (*Client) SetSMTPAuthCustom 

func (c *Client) SetSMTPAuthCustom(sa smtp.Auth)

SetSMTPAuthCustom overrides the current SMTP AUTH setting with the given custom smtp.Auth

func (*Client) SetSSL added in v0.1.4 

func (c *Client) SetSSL(s bool)

SetSSL tells the Client wether to use SSL or not

func (*Client) SetTLSConfig 

func (c *Client) SetTLSConfig(co *tls.Config) error

SetTLSConfig overrides the current *tls.Config with the given *tls.Config value

func (*Client) SetTLSPolicy 

func (c *Client) SetTLSPolicy(p TLSPolicy)

SetTLSPolicy overrides the current TLSPolicy with the given TLSPolicy value

Example

Code example for the Client.SetTLSPolicy method 

package main

import (
	"fmt"
	"github.com/wneessen/go-mail"
)

func main() {
	c, err := mail.NewClient("mail.example.com")
	if err != nil {
		panic(err)
	}
	c.SetTLSPolicy(mail.TLSMandatory)
	fmt.Println(c.TLSPolicy())
}

Output:
TLSMandatory

func (*Client) SetUsername 

func (c *Client) SetUsername(u string)

SetUsername overrides the current username string with the given value

func (*Client) TLSPolicy 

func (c *Client) TLSPolicy() string

TLSPolicy returns the currently set TLSPolicy as string

type ContentType 

type ContentType string

ContentType represents a content type for the Msg 

const (
	TypeTextPlain      ContentType = "text/plain"
	TypeTextHTML       ContentType = "text/html"
	TypeAppOctetStream ContentType = "application/octet-stream"
)

List of common content types

type Encoding 

type Encoding string

Encoding represents a MIME encoding scheme like quoted-printable or Base64. 

const (
	// EncodingB64 represents the Base64 encoding as specified in RFC 2045.
	EncodingB64 Encoding = "base64"

	// EncodingQP represents the "quoted-printable" encoding as specified in RFC 2045.
	EncodingQP Encoding = "quoted-printable"

	// NoEncoding avoids any character encoding (except of the mail headers)
	NoEncoding Encoding = "8bit"
)

List of supported encodings

func (Encoding) String 

func (e Encoding) String() string

String is a standard method to convert an Encoding into a printable format

type File added in v0.1.1 

type File struct {
	Name   string
	Header textproto.MIMEHeader
	Writer func(w io.Writer) (int64, error)
}

File is an attachment or embedded file of the Msg

type FileOption added in v0.1.1 

type FileOption func(*File)

FileOption returns a function that can be used for grouping File options

func WithFileName added in v0.1.1 

func WithFileName(n string) FileOption

WithFileName sets the filename of the File 

type Header string

Header represents a generic mail header field name 

const (
	// HeaderContentDisposition is the "Content-Disposition" header
	HeaderContentDisposition Header = "Content-Disposition"

	// HeaderContentID is the "Content-ID" header
	HeaderContentID Header = "Content-ID"

	// HeaderContentLang is the "Content-Language" header
	HeaderContentLang Header = "Content-Language"

	// HeaderContentLocation is the "Content-Location" header (RFC 2110)
	HeaderContentLocation Header = "Content-Location"

	// HeaderContentTransferEnc is the "Content-Transfer-Encoding" header
	HeaderContentTransferEnc Header = "Content-Transfer-Encoding"

	// HeaderContentType is the "Content-Type" header
	HeaderContentType Header = "Content-Type"

	// HeaderDate represents the "Date" field
	// See: https://www.rfc-editor.org/rfc/rfc822#section-5.1
	HeaderDate Header = "Date"

	// HeaderImportance represents the "Importance" field
	HeaderImportance Header = "Importance"

	// HeaderInReplyTo represents the "In-Reply-To" field
	HeaderInReplyTo Header = "In-Reply-To"

	// HeaderListUnsubscribe is the "List-Unsubscribe" header field
	HeaderListUnsubscribe Header = "List-Unsubscribe"

	// HeaderListUnsubscribePost is the "List-Unsubscribe-Post" header field
	HeaderListUnsubscribePost Header = "List-Unsubscribe-Post"

	// HeaderMessageID represents the "Message-ID" field for message identification
	// See: https://www.rfc-editor.org/rfc/rfc1036#section-2.1.5
	HeaderMessageID Header = "Message-ID"

	// HeaderMIMEVersion represents the "MIME-Version" field as per RFC 2045
	// See: https://datatracker.ietf.org/doc/html/rfc2045#section-4
	HeaderMIMEVersion Header = "MIME-Version"

	// HeaderOrganization is the "Organization" header field
	HeaderOrganization Header = "Organization"

	// HeaderPrecedence is the "Precedence" header field
	HeaderPrecedence Header = "Precedence"

	// HeaderPriority represents the "Priority" field
	HeaderPriority Header = "Priority"

	// HeaderReplyTo is the "Reply-To" header field
	HeaderReplyTo Header = "Reply-To"

	// HeaderSubject is the "Subject" header field
	HeaderSubject Header = "Subject"

	// HeaderUserAgent is the "User-Agent" header field
	HeaderUserAgent Header = "User-Agent"

	// HeaderXMailer is the "X-Mailer" header field
	HeaderXMailer Header = "X-Mailer"

	// HeaderXMSMailPriority is the "X-MSMail-Priority" header field
	HeaderXMSMailPriority Header = "X-MSMail-Priority"

	// HeaderXPriority is the "X-Priority" header field
	HeaderXPriority Header = "X-Priority"
)

List of common generic header field names

func (Header) String added in v0.1.4 

func (h Header) String() string

String returns the header string based on the given Header

type Importance 

type Importance int

Importance represents a Importance/Priority value string 

const (
	ImportanceLow Importance = iota
	ImportanceNormal
	ImportanceHigh
	ImportanceNonUrgent
	ImportanceUrgent
)

List of Importance values

func (Importance) NumString 

func (i Importance) NumString() string

NumString returns the importance number string based on the Importance

func (Importance) String 

func (i Importance) String() string

String returns the importance string based on the Importance

func (Importance) XPrioString 

func (i Importance) XPrioString() string

XPrioString returns the X-Priority number string based on the Importance

type MIMEType 

type MIMEType string

MIMEType represents the MIME type for the mail 

const (
	MIMEAlternative MIMEType = "alternative"
	MIMEMixed       MIMEType = "mixed"
	MIMERelated     MIMEType = "related"
)

List of MIMETypes

type MIMEVersion 

type MIMEVersion string

MIMEVersion represents the MIME version for the mail 

const (
	//Mime10 is the MIME Version 1.0
	Mime10 MIMEVersion = "1.0"
)

List of MIME versions

type Msg 

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

Msg is the mail message struct

func NewMsg 

func NewMsg(o ...MsgOption) *Msg

NewMsg returns a new Msg pointer

Example

Code example for the NewMsg method 

package main

import (
	"fmt"
	"github.com/wneessen/go-mail"
)

func main() {
	m := mail.NewMsg(mail.WithEncoding(mail.EncodingQP), mail.WithCharset(mail.CharsetASCII))
	fmt.Printf("%s // %s\n", m.Encoding(), m.Charset())
}

Output:
quoted-printable // US-ASCII

func (*Msg) AddAlternativeHTMLTemplate added in v0.2.2 

func (m *Msg) AddAlternativeHTMLTemplate(t *ht.Template, d interface{}, o ...PartOption) error

AddAlternativeHTMLTemplate sets the alternative body of the message to a html/template.Template output The content type will be set to text/html automatically

func (*Msg) AddAlternativeString 

func (m *Msg) AddAlternativeString(ct ContentType, b string, o ...PartOption)

AddAlternativeString sets the alternative body of the message.

func (*Msg) AddAlternativeTextTemplate added in v0.2.2 

func (m *Msg) AddAlternativeTextTemplate(t *tt.Template, d interface{}, o ...PartOption) error

AddAlternativeTextTemplate sets the alternative body of the message to a text/template.Template output The content type will be set to text/plain automatically

func (*Msg) AddAlternativeWriter 

func (m *Msg) AddAlternativeWriter(ct ContentType, w func(io.Writer) (int64, error), o ...PartOption)

AddAlternativeWriter sets the body of the message.

func (*Msg) AddBcc 

func (m *Msg) AddBcc(t string) error

AddBcc adds an additional address to the Bcc address header field

func (*Msg) AddBccFormat 

func (m *Msg) AddBccFormat(n, a string) error

AddBccFormat takes a name and address, formats them RFC5322 compliant and stores them as as additional Bcc address header field

func (*Msg) AddCc 

func (m *Msg) AddCc(t string) error

AddCc adds an additional address to the Cc address header field

func (*Msg) AddCcFormat 

func (m *Msg) AddCcFormat(n, a string) error

AddCcFormat takes a name and address, formats them RFC5322 compliant and stores them as as additional Cc address header field

func (*Msg) AddTo 

func (m *Msg) AddTo(t string) error

AddTo adds an additional address to the To address header field

func (*Msg) AddToFormat 

func (m *Msg) AddToFormat(n, a string) error

AddToFormat takes a name and address, formats them RFC5322 compliant and stores them as as additional To address header field

func (*Msg) AttachFile added in v0.1.1 

func (m *Msg) AttachFile(n string, o ...FileOption)

AttachFile adds an attachment File to the Msg

func (*Msg) AttachFromEmbedFS added in v0.2.5 

func (m *Msg) AttachFromEmbedFS(n string, f *embed.FS, o ...FileOption) error

AttachFromEmbedFS adds an attachment File from an embed.FS to the Msg

func (*Msg) AttachHTMLTemplate added in v0.2.2 

func (m *Msg) AttachHTMLTemplate(n string, t *ht.Template, d interface{}, o ...FileOption) error

AttachHTMLTemplate adds the output of a html/template.Template pointer as File attachment to the Msg

func (*Msg) AttachReader added in v0.1.1 

func (m *Msg) AttachReader(n string, r io.Reader, o ...FileOption)

AttachReader adds an attachment File via io.Reader to the Msg

func (*Msg) AttachTextTemplate added in v0.2.2 

func (m *Msg) AttachTextTemplate(n string, t *tt.Template, d interface{}, o ...FileOption) error

AttachTextTemplate adds the output of a text/template.Template pointer as File attachment to the Msg

func (*Msg) Bcc 

func (m *Msg) Bcc(b ...string) error

Bcc takes and validates a given mail address list sets the Bcc: addresses of the Msg

func (*Msg) BccIgnoreInvalid 

func (m *Msg) BccIgnoreInvalid(b ...string)

BccIgnoreInvalid takes and validates a given mail address list sets the Bcc: addresses of the Msg Any provided address that is not RFC5322 compliant, will be ignored

func (*Msg) Cc 

func (m *Msg) Cc(c ...string) error

Cc takes and validates a given mail address list sets the Cc: addresses of the Msg

func (*Msg) CcIgnoreInvalid 

func (m *Msg) CcIgnoreInvalid(c ...string)

CcIgnoreInvalid takes and validates a given mail address list sets the Cc: addresses of the Msg Any provided address that is not RFC5322 compliant, will be ignored

func (*Msg) Charset 

func (m *Msg) Charset() string

Charset returns the currently set charset of the Msg

func (*Msg) EmbedFile added in v0.1.1 

func (m *Msg) EmbedFile(n string, o ...FileOption)

EmbedFile adds an embedded File to the Msg

func (*Msg) EmbedFromEmbedFS added in v0.2.5 

func (m *Msg) EmbedFromEmbedFS(n string, f *embed.FS, o ...FileOption) error

EmbedFromEmbedFS adds an embedded File from an embed.FS to the Msg

func (*Msg) EmbedHTMLTemplate added in v0.2.2 

func (m *Msg) EmbedHTMLTemplate(n string, t *ht.Template, d interface{}, o ...FileOption) error

EmbedHTMLTemplate adds the output of a html/template.Template pointer as embedded File to the Msg

func (*Msg) EmbedReader added in v0.1.1 

func (m *Msg) EmbedReader(n string, r io.Reader, o ...FileOption)

EmbedReader adds an embedded File from an io.Reader to the Msg

func (*Msg) EmbedTextTemplate added in v0.2.2 

func (m *Msg) EmbedTextTemplate(n string, t *tt.Template, d interface{}, o ...FileOption) error

EmbedTextTemplate adds the output of a text/template.Template pointer as embedded File to the Msg

func (*Msg) Encoding 

func (m *Msg) Encoding() string

Encoding returns the currently set encoding of the Msg

func (*Msg) EnvelopeFrom added in v0.2.4 

func (m *Msg) EnvelopeFrom(f string) error

EnvelopeFrom takes and validates a given mail address and sets it as envelope "FROM" addrHeader of the Msg

func (*Msg) EnvelopeFromFormat added in v0.2.4 

func (m *Msg) EnvelopeFromFormat(n, a string) error

EnvelopeFromFormat takes a name and address, formats them RFC5322 compliant and stores them as the envelope FROM address header field

func (*Msg) From 

func (m *Msg) From(f string) error

From takes and validates a given mail address and sets it as "From" genHeader of the Msg

func (*Msg) FromFormat 

func (m *Msg) FromFormat(n, a string) error

FromFormat takes a name and address, formats them RFC5322 compliant and stores them as the From address header field

func (*Msg) GetRecipients 

func (m *Msg) GetRecipients() ([]string, error)

GetRecipients returns a list of the currently set TO/CC/BCC addresses.

func (*Msg) GetSender 

func (m *Msg) GetSender(ff bool) (string, error)

GetSender returns the currently set envelope FROM address. If no envelope FROM is set it will use the first mail body FROM address. If ff is true, it will return the full address string including the address name, if set

func (*Msg) Read added in v0.2.1 

func (m *Msg) Read(p []byte) (int, error)

Read outputs the length of p into p to satisfy the io.Reader interface

func (*Msg) ReplyTo 

func (m *Msg) ReplyTo(r string) error

ReplyTo takes and validates a given mail address and sets it as "Reply-To" addrHeader of the Msg

func (*Msg) ReplyToFormat 

func (m *Msg) ReplyToFormat(n, a string) error

ReplyToFormat takes a name and address, formats them RFC5322 compliant and stores them as the Reply-To header field

func (*Msg) Reset added in v0.1.2 

func (m *Msg) Reset()

Reset resets all headers, body parts and attachments/embeds of the Msg It leaves already set encodings, charsets, boundaries, etc. as is

func (*Msg) SetAddrHeader 

func (m *Msg) SetAddrHeader(h AddrHeader, v ...string) error

SetAddrHeader sets an address related header field of the Msg

func (*Msg) SetAddrHeaderIgnoreInvalid 

func (m *Msg) SetAddrHeaderIgnoreInvalid(h AddrHeader, v ...string)

SetAddrHeaderIgnoreInvalid sets an address related header field of the Msg and ignores invalid address in the validation process

func (*Msg) SetBodyHTMLTemplate added in v0.2.2 

func (m *Msg) SetBodyHTMLTemplate(t *ht.Template, d interface{}, o ...PartOption) error

SetBodyHTMLTemplate sets the body of the message from a given html/template.Template pointer The content type will be set to text/html automatically

func (*Msg) SetBodyString 

func (m *Msg) SetBodyString(ct ContentType, b string, o ...PartOption)

SetBodyString sets the body of the message.

Example (DifferentTypes)

This code example shows how to use Msg.SetBodyString to set a string as message body with different content types 

package main

import (
	"github.com/wneessen/go-mail"
)

func main() {
	m := mail.NewMsg()
	m.SetBodyString(mail.TypeTextPlain, "This is a mail body that with content type: text/plain")
	m.SetBodyString(mail.TypeTextHTML, "<p>This is a mail body that with content type: text/html</p>")
}
Example (WithPartOption)

This code example shows how to use Msg.SetBodyString to set a string as message body a PartOption to override the default encoding 

package main

import (
	"github.com/wneessen/go-mail"
)

func main() {
	m := mail.NewMsg(mail.WithEncoding(mail.EncodingB64))
	m.SetBodyString(mail.TypeTextPlain, "This is a mail body that with content type: text/plain",
		mail.WithPartEncoding(mail.EncodingQP))
}

func (*Msg) SetBodyTextTemplate added in v0.2.2 

func (m *Msg) SetBodyTextTemplate(t *tt.Template, d interface{}, o ...PartOption) error

SetBodyTextTemplate sets the body of the message from a given text/template.Template pointer The content type will be set to text/plain automatically

Example

This code example shows how to use a text/template as message Body. Msg.SetBodyHTMLTemplate works anolog to this just with html/template instead 

package main

import (
	"github.com/wneessen/go-mail"
	"text/template"
)

func main() {
	type MyStruct struct {
		Placeholder string
	}
	data := MyStruct{Placeholder: "Teststring"}
	tpl, err := template.New("test").Parse("This is a {{.Placeholder}}")
	if err != nil {
		panic(err)
	}

	m := mail.NewMsg()
	if err := m.SetBodyTextTemplate(tpl, data); err != nil {
		panic(err)
	}
}

func (*Msg) SetBodyWriter 

func (m *Msg) SetBodyWriter(ct ContentType, w func(io.Writer) (int64, error), o ...PartOption)

SetBodyWriter sets the body of the message.

func (*Msg) SetBoundary 

func (m *Msg) SetBoundary(b string)

SetBoundary sets the boundary of the Msg

func (*Msg) SetBulk 

func (m *Msg) SetBulk()

SetBulk sets the "Precedence: bulk" genHeader which is recommended for automated mails like OOO replies See: https://www.rfc-editor.org/rfc/rfc2076#section-3.9

func (*Msg) SetCharset 

func (m *Msg) SetCharset(c Charset)

SetCharset sets the encoding charset of the Msg

func (*Msg) SetDate 

func (m *Msg) SetDate()

SetDate sets the Date genHeader field to the current time in a valid format

func (*Msg) SetDateWithValue added in v0.1.2 

func (m *Msg) SetDateWithValue(t time.Time)

SetDateWithValue sets the Date genHeader field to the provided time in a valid format

func (*Msg) SetEncoding 

func (m *Msg) SetEncoding(e Encoding)

SetEncoding sets the encoding of the Msg

func (*Msg) SetHeader 

func (m *Msg) SetHeader(h Header, v ...string)

SetHeader sets a generic header field of the Msg

func (*Msg) SetImportance 

func (m *Msg) SetImportance(i Importance)

SetImportance sets the Msg Importance/Priority header to given Importance

func (*Msg) SetMIMEVersion 

func (m *Msg) SetMIMEVersion(mv MIMEVersion)

SetMIMEVersion sets the MIME version of the Msg

func (*Msg) SetMessageID 

func (m *Msg) SetMessageID()

SetMessageID generates a random message id for the mail

func (*Msg) SetMessageIDWithValue 

func (m *Msg) SetMessageIDWithValue(v string)

SetMessageIDWithValue sets the message id for the mail

func (*Msg) SetOrganization added in v0.1.3 

func (m *Msg) SetOrganization(o string)

SetOrganization sets the provided string as Organization header for the Msg

func (*Msg) SetUserAgent added in v0.1.3 

func (m *Msg) SetUserAgent(a string)

SetUserAgent sets the User-Agent/X-Mailer header for the Msg

func (*Msg) Subject 

func (m *Msg) Subject(s string)

Subject sets the "Subject" header field of the Msg

func (*Msg) To 

func (m *Msg) To(t ...string) error

To takes and validates a given mail address list sets the To: addresses of the Msg

func (*Msg) ToIgnoreInvalid 

func (m *Msg) ToIgnoreInvalid(t ...string)

ToIgnoreInvalid takes and validates a given mail address list sets the To: addresses of the Msg Any provided address that is not RFC5322 compliant, will be ignored

func (*Msg) Write 

func (m *Msg) Write(w io.Writer) (int64, error)

Write is an alias method to WriteTo due to compatibility reasons

func (*Msg) WriteTo added in v0.1.9 

func (m *Msg) WriteTo(w io.Writer) (int64, error)

WriteTo writes the formated Msg into a give io.Writer and satisfies the io.WriteTo interface

func (*Msg) WriteToFile added in v0.2.3 

func (m *Msg) WriteToFile(n string) error

WriteToFile stores the Msg as file on disk. It will try to create the given filename Already existing files will be overwritten

func (*Msg) WriteToSendmail added in v0.1.2 

func (m *Msg) WriteToSendmail() error

WriteToSendmail returns WriteToSendmailWithCommand with a default sendmail path

Example

This code example shows how to utilize the Msg.WriteToSendmail method to send generated mails using a local sendmail installation 

package main

import (
	"github.com/wneessen/go-mail"
)

func main() {
	m := mail.NewMsg()
	m.SetBodyString(mail.TypeTextPlain, "This is the mail body string")
	if err := m.FromFormat("Toni Tester", "toni.tester@example.com"); err != nil {
		panic(err)
	}
	if err := m.To("gandalf.tester@example.com"); err != nil {
		panic(err)
	}
	if err := m.WriteToSendmail(); err != nil {
		panic(err)
	}
}

func (*Msg) WriteToSendmailWithCommand added in v0.1.5 

func (m *Msg) WriteToSendmailWithCommand(sp string) error

WriteToSendmailWithCommand returns WriteToSendmailWithContext with a default timeout of 5 seconds and a given sendmail path

func (*Msg) WriteToSendmailWithContext added in v0.1.2 

func (m *Msg) WriteToSendmailWithContext(ctx context.Context, sp string, a ...string) error

WriteToSendmailWithContext opens an pipe to the local sendmail binary and tries to send the mail though that. It takes a context.Context, the path to the sendmail binary and additional arguments for the sendmail binary as parameters

Example

This code example shows how to send generated mails using a custom context and sendmail-compatbile command using the Msg.WriteToSendmailWithContext method 

package main

import (
	"context"
	"github.com/wneessen/go-mail"
	"time"
)

func main() {
	sendmailPath := "/opt/sendmail/sbin/sendmail"
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*5)
	defer cancel()

	m := mail.NewMsg()
	m.SetBodyString(mail.TypeTextPlain, "This is the mail body string")
	if err := m.FromFormat("Toni Tester", "toni.tester@example.com"); err != nil {
		panic(err)
	}
	if err := m.To("gandalf.tester@example.com"); err != nil {
		panic(err)
	}
	if err := m.WriteToSendmailWithContext(ctx, sendmailPath); err != nil {
		panic(err)
	}
}

func (*Msg) WriteToTempFile added in v0.2.3 

func (m *Msg) WriteToTempFile() (string, error)

WriteToTempFile will create a temporary file and output the Msg to this file The method will return the filename of the temporary file

type MsgOption 

type MsgOption func(*Msg)

MsgOption returns a function that can be used for grouping Msg options

func WithBoundary added in v0.1.4 

func WithBoundary(b string) MsgOption

WithBoundary overrides the default MIME boundary

func WithCharset 

func WithCharset(c Charset) MsgOption

WithCharset overrides the default message charset

func WithEncoding 

func WithEncoding(e Encoding) MsgOption

WithEncoding overrides the default message encoding

func WithMIMEVersion 

func WithMIMEVersion(mv MIMEVersion) MsgOption

WithMIMEVersion overrides the default MIME version

type Option 

type Option func(*Client) error

Option returns a function that can be used for grouping Client options

func WithHELO 

func WithHELO(h string) Option

WithHELO tells the client to use the provided string as HELO/EHLO greeting host

func WithPassword 

func WithPassword(p string) Option

WithPassword tells the client to use the provided string as password/secret for authentication

func WithPort 

func WithPort(p int) Option

WithPort overrides the default connection port

func WithSMTPAuth 

func WithSMTPAuth(t SMTPAuthType) Option

WithSMTPAuth tells the client to use the provided SMTPAuthType for authentication

func WithSMTPAuthCustom 

func WithSMTPAuthCustom(a smtp.Auth) Option

WithSMTPAuthCustom tells the client to use the provided smtp.Auth for SMTP authentication

func WithSSL 

func WithSSL() Option

WithSSL tells the client to use a SSL/TLS connection

func WithTLSConfig 

func WithTLSConfig(co *tls.Config) Option

WithTLSConfig tells the client to use the provided *tls.Config

func WithTLSPolicy 

func WithTLSPolicy(p TLSPolicy) Option

WithTLSPolicy tells the client to use the provided TLSPolicy

func WithTimeout 

func WithTimeout(t time.Duration) Option

WithTimeout overrides the default connection timeout

func WithUsername 

func WithUsername(u string) Option

WithUsername tells the client to use the provided string as username for authentication

type Part 

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

Part is a part of the Msg

func (*Part) SetEncoding 

func (p *Part) SetEncoding(e Encoding)

SetEncoding creates a new mime.WordEncoder based on the encoding setting of the message

type PartOption 

type PartOption func(*Part)

PartOption returns a function that can be used for grouping Part options

func WithPartEncoding 

func WithPartEncoding(e Encoding) PartOption

WithPartEncoding overrides the default Part encoding

type SMTPAuthType 

type SMTPAuthType string

SMTPAuthType represents a string to any SMTP AUTH type 

const (
	// SMTPAuthLogin is the "LOGIN" SASL authentication mechanism
	SMTPAuthLogin SMTPAuthType = "LOGIN"

	// SMTPAuthPlain is the "PLAIN" authentication mechanism as described in RFC 4616
	SMTPAuthPlain SMTPAuthType = "PLAIN"

	// SMTPAuthCramMD5 is the "CRAM-MD5" SASL authentication mechanism as described in RFC 4954
	SMTPAuthCramMD5 SMTPAuthType = "CRAM-MD5"
)

Supported SMTP AUTH types

type TLSPolicy 

type TLSPolicy int

TLSPolicy type describes a int alias for the different TLS policies we allow 

const (
	// TLSMandatory requires that the connection cto the server is
	// encrypting using STARTTLS. If the server does not support STARTTLS
	// the connection will be terminated with an error
	TLSMandatory TLSPolicy = iota

	// TLSOpportunistic tries cto establish an encrypted connection via the
	// STARTTLS protocol. If the server does not support this, it will fall
	// back cto non-encrypted plaintext transmission
	TLSOpportunistic

	// NoTLS forces the transaction cto be not encrypted
	NoTLS
)

func (TLSPolicy) String 

func (p TLSPolicy) String() string

String is a standard method to convert a TLSPolicy into a printable format

Source Files

View all Source files

Directories

Path Synopsis
Package auth implements the LOGIN and MD5-DIGEST smtp authentication mechanisms
 Package auth implements the LOGIN and MD5-DIGEST smtp authentication mechanisms

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.