carrier

carrier

A simple module to send email via various services with a single message object.

Version: 0.1.0

Project Links: Docs - Issues - Mailing List - Contributing

Author: Peter Sanchez (https://petersanchez.com)

Dependencies

• Go 1.16+

Included Services

The following delivery services are currently supported:

• Console (prints to console by default)
• SMTP
• Amazon SES

Click each service above to see the docs

Example usage

With the exception of console, each service has it's own configuration object, called MailConfig. See each service docs for the config examples. In this example we will use the SMTP service.

import (
	...
	"petersanchez.com/carrier",
	"petersanchez.com/carrier/smtp",
	...
)

func email() {
	conf := &smtp.MailConfig{
		SMTPPort: 587,
		SMTPHost: "smtp.yourdomain.com",
		SMTPEncType: "starttls",
		SMTPAuth: "plain",
		SMTPUser: "user@yourdomain.com",
		SMTPPass: "supersecurepassword",
	}

	svc, err := smtp.NewSMTPService(conf)
	if err != nil {
		// handle errors (here and below)
	}

	msg := carrier.NewMessage()
	msg.SetFrom("me@mydomain.com").
		SetTo("recipient@theirdomain.com").
		SetCc("copy@somedomain.com")
	msg.SetSubject("Sending email from Go!")

	file, err := os.Open("funny.jpg")
	msg.AddAttachment("funny.jpg", file, "")
	file.Close()

	err = msg.SetBody("This is the text email body.")
	err = msg.SetBodyHTML("This is the HTML email body.")

	// Send email
	err = svc.Send(msg)
}

The Message object is based on the Header object from the fantastic go-message/mail module. The credit really goes to emersion who's code is doing the heavy lifting under the hood. See the header documentation for all the methods supported.

Why?

I couldn't find a module that let me swap out delivery services easily. I just wanted to have one default email message object that can be passed to whatever service interface and deliver it.

This is useful for development, staging, and production environments where often there are different scenarios to deliver/test email.

Status

Currently all the included service interfaces work as expected and are in use in production environments.

Contributing

We accept patches submitted via hg email which is the patchbomb extension included with Mercurial.

The mailing list where you submit your patches is ~petersanchez/public-inbox@lists.code.netlandish.com. You can also view the archives on the web here:

https://lists.code.netlandish.com/~petersanchez/public-inbox

To quickly setup your clone of carrier to submit to the mailing list just edit your .hg/hgrc file and add the following:

[email]
to = ~petersanchez/public-inbox@lists.code.netlandish.com

[patchbomb]
flagtemplate = {separate(' ', 'carrier', flags)}

[diff]
git = 1

We have more information on the topic here:

• Contributing
• Using email with Mercurial
• Mailing list etiquette

Copyright & Warranty

All documentation, libraries, and sample code are Copyright 2021 Peter Sanchez <pjs@petersanchez.com>. The library and sample code are made available to you under the terms of the BSD license which is contained in the included file, LICENSE.