postal

Postal

Postal is a simple package which allows you to send email messages, either via an SMTP server or using MailGun's api. Postal implements a simple worker pool to make sending messages both easy and efficient. Postal uses standard Go templates (html/template).

Installation

Install it the usual way:

go get -u github.com/tsawler/postal

Usage

To create a worker pool to send email, first define a postal.Service object with settings appropriate for your environment. This is the postal.Service type:

// Service is the type used to create a MailDispatcher.
type Service struct {
    Method        int                           // How to send the message: postal.SMTP or postal.MailGun.
    ServerURL     string                        // The URL of the server mail is sent from.
    SMTPServer    string                        // The SMTP server.
    SMTPPort      int                           // The SMTP server's port.
    SMTPUser      string                        // The username for the SMTP server.
    SMTPPassword  string                        // The password for the SMTP server.
    ErrorChan     chan error // Optional channel for results (an error, or nil on success).
    MaxWorkers    int        // Maximum number of workers in the pool.
    MaxMessages   int        // How big the buffer should be for the JobQueue.
    Domain        string     // The domain used to send mail.
    APIKey        string     // The API key for mailgun.
    SendingFromEU bool       // If using mailgun and sending from EU, set to true.
    TemplateDir   string     // Where templates are stored.

    ConnectTimeout time.Duration // Bounds the SMTP connection. Zero means 10s.
    SendTimeout    time.Duration // Bounds transmission / the Mailgun call. Zero means 10s.
    ErrorChanGrace time.Duration // How long a worker waits on an unread ErrorChan. Zero means 5s.
}

Then, create a postal.MailDispatcher by calling postal.New with your postal.Service as the parameter:

dispatcher, _ := postal.New(myService)

Create a mail message by defining a postal.MailData object. This is the type for postal.MailData:

// MailData holds all information for a given message.
type MailData struct {
	ToName       string         // The name of the recipient.
	ToAddress    string         // The email address of the recipient.
	FromName     string         // The name of the sender.
	FromAddress  string         // The email address of the sender.
	ReplyTo      string         // The reply-to email address.
	AdditionalTo []string       // Additional TO recipients.
	Subject      string         // The subject of the email message.
	Content      template.HTML  // The content of the message, as HTML.
	ContentType  string         // Optional: "text/html" (default), "text/plain" (Content sent as-is, no template), "application/xml", etc.
	Template     string         // The template to use. If not specified, will use a simple default template.
	CC           []string       // A slice of CC recipient emails.
	BCC          []string       // A slice of BCC recipient emails.
	Attachments  []string       // A slice of attachments, which must exist on disk (i.e. []string{"./files/myfile.pdf"}).
	Data         map[string]any // Data which is to be passed to the Go template.
	InlineImages []string       // A slice of images to be inlined in the email. PNG is preferred.
	ServerURL    string         // The URL of the server (for backlinks in message).
}

Finally, send the message. There are two ways to do this.

SendAndWait (recommended) delivers one message and returns that message's result:

ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()

if err := dispatcher.SendAndWait(ctx, msg); err != nil {
    log.Println("could not send:", err)
}

Each call carries a private result channel, so concurrent callers never receive one another's results, and a caller whose context expires cannot strand the worker still delivering its message. Allow the context at least Service.MaxSendDuration() (ConnectTimeout + SendTimeout, 20s by default), or slow but successful sends are abandoned and misreported as failures.

Send is fire and forget. It returns as soon as the message is queued, and the result is delivered to Service.ErrorChan if one is configured:

dispatcher.Send(msg)

// Wait for a response.
err := <-dispatcher.ErrorChan

Because ErrorChan is shared by every in-flight message, a value read from it cannot be attributed to any particular Send. Use SendAndWait when the caller needs to know whether its message was delivered.

When you are finished with a dispatcher, call Close() to stop the worker pool and wait for in-flight deliveries to finish.

Concurrency and lifetime

• Multiple dispatchers may be created and used concurrently; each keeps its own configuration and template cache.
• SendAndWait is safe to call from any number of goroutines at once.
• A worker is never blocked indefinitely. If no one is reading ErrorChan, the result is dropped after ErrorChanGrace rather than parking the worker.
• Run and Close are both idempotent. A dispatcher cannot be restarted after Close.

An example of sending via SMTP:

package main

import (
	"fmt"
	"github.com/tsawler/postal"
)

func main() {
	// Define a postal.Service variable with values appropriate for your environment.
	service := postal.Service{
		Method:         postal.SMTP,       // Method to send. Options are postal.SMTP or postal.MailGun.
		ServerURL:     "http://localhost", // The URL of the server (for backlinks in mail).
		SMTPServer:    "localhost",        // The name of the SMTP server you are sending through.
		SMTPPort:      1025,               // The port the SMTP server listens on.
		SMTPUser:      "",                 // SMTP username.
		SMTPPassword:  "",                 // SMTP password.
		ErrorChan:     make(chan error),   // A channel to receive errors (or nil for success).
		MaxWorkers:    2,                  // Number of workers in our pool.
		MaxMessages:   10,                 // Buffer size for send channel.
		TemplateDir:   "./templates",      // The directory where mail templates live.
	}
	
	// Get a dispatcher by calling postal.New(service).
	dispatcher, _ := postal.New(service)

	// Run the worker pool.
	dispatcher.Run()

	// Create a mail message.
	msg := postal.MailData{
		ToName:      "Me",
		ToAddress:   "me@here.com",
		FromName:    "Jack",
		FromAddress: "jack@there.com",
		Subject:     "Test subject",
		Content:     "Hello, world!",
		CC:          []string{"you@here.com", "him@here.com"},
		//Template:    "my-template.gohtml", // You can specify your own template, or leave this out and use the default.
	}

	// Send the message by calling dispatcher.Send.
	fmt.Println("Sending mail")
	dispatcher.Send(msg)

	// Wait for something back from ErrorChan.
	fmt.Println("Waiting for response")
	err := <-dispatcher.ErrorChan
	fmt.Println("Error", err)
}

An example sending through MailGun's api:

package main

import (
	"fmt"
	"github.com/tsawler/postal"
)

func main() {
	
	// Define a postal.Service variable with values appropriate for your environment.
	service := postal.Service{
		Method:        postal.MailGun,     // Method to send. Options are postal.SMTP or postal.MailGun.
		ServerURL:    "http://localhost",  // The URL of your server, in case you want backlinks in your message.
		ErrorChan:     make(chan error),   // A channel to receive error messages (or nil for successful sends).
		MaxWorkers:    2,                  // The number of workers you want in the worker pool.
		MaxMessages:   10,                 // The size of the job queue (a buffered channel).
		SendingFromEU: false,              // Set to true if sending from European Union (mailgun only).
		TemplateDir:   "./templates",      // The directory where mail templates live.
		Domain:        "yourdomain.com",   // The domain you are sending from (mailgun only).
		APIKey:        "your-mailgun-api", // The mailgun api key (mailgun only).
	}
	
	// Call postal.New with your service to get a message dispatcher.
	dispatcher, _ := postal.New(service)

	// Run the worker pool associated with the dispatcher.
	dispatcher.Run()

	// Create a mail message, of postal.MailData type.
	msg := postal.MailData{
		ToName:        "Me",
		ToAddress:     "me@here.com",
		FromName:      "Jack",
		FromAddress:   "jack@there.com",
		Subject:       "Test subject",
		Content:       "Hello, world!",
		CC:            []string{"you@here.com", "him@here.com"},
	}

	// Send the message.
	fmt.Println("Sending mail")
	dispatcher.Send(msg)

	
	// Wait for a response.
	fmt.Println("Waiting for response")
	err := <-dispatcher.ErrorChan
	
	// If err is nil, then the message was sent.
	fmt.Println("Error", err)
}