carrier

README

carrier

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

Version: 0.2.2

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/x/carrier",
	"petersanchez.com/x/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.

Documentation

Overview

Package carrier implements sending email via various services with a single message object.

This package will panic if you pass in email addresses that are invalid. Please be sure to validate your input before passing it in.

Example

package main

import (
	"log"
	"os"

	"petersanchez.com/x/carrier"
)

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

	// You should handle errors properly in all instances below
	file, err := os.Open("funny.jpg")
	if err != nil {
		log.Fatal(err)
	}
	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)
	log.Println("Successfully sent email.")
}

Index

• func SendMail(to string, from string, subject string, text string, html string, svc Service) error
• type ConsoleService
  • func NewConsoleService() *ConsoleService
  • func (c *ConsoleService) Send(msg *Message) error
• type Message
  • func NewMessage() *Message
  • func (m *Message) AddAttachment(filename string, data io.Reader, ctype string) error
  • func (m *Message) AddPGPKeys(keys *PGPKeys) error
  • func (m *Message) Buffer() *bytes.Buffer
  • func (m *Message) Bytes() []byte
  • func (m *Message) Close()
  • func (m *Message) GetAllRcpts() []string
  • func (m *Message) SendMail(svc Service) error
  • func (m *Message) SetBcc(address string) *Message
  • func (m *Message) SetBccCSV(address string) *Message
  • func (m *Message) SetBccList(addresses []string) *Message
  • func (m *Message) SetBody(body string) error
  • func (m *Message) SetBodyHTML(body string) error
  • func (m *Message) SetCc(address string) *Message
  • func (m *Message) SetCcCSV(address string) *Message
  • func (m *Message) SetCcList(addresses []string) *Message
  • func (m *Message) SetFrom(address string) *Message
  • func (m *Message) SetHTML(msg io.Reader) error
  • func (m *Message) SetText(msg io.Reader) error
  • func (m *Message) SetTo(address string) *Message
  • func (m *Message) SetToCSV(address string) *Message
  • func (m *Message) SetToList(addresses []string) *Message
  • func (m *Message) String() string
• type OutboxService
  • func NewOutboxService() *OutboxService
  • func (c *OutboxService) Send(msg *Message) error
• type PGPKeys
  • func NewPGPKeys(skey, rkey io.Reader) (*PGPKeys, error)
• type Service

Examples

• Package
• PGPKeys

Functions

func SendMail

func SendMail(to string, from string, subject string,
	text string, html string, svc Service) error

SendMail is a quick helper to send out an email using a given service

Types

type ConsoleService

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

ConsoleService is a simple email service to print email to the set writer

func NewConsoleService

func NewConsoleService() *ConsoleService

NewConsoleService returns an smtp service instance

func (*ConsoleService) Send

func (c *ConsoleService) Send(msg *Message) error

Send match email Service interface signature

type Message

type Message struct {
	mail.Header
	// contains filtered or unexported fields
}

Message object which holds the entire email message. Each service will take a *Message object and use it to parse out the required data to send the email.

func NewMessage

func NewMessage() *Message

NewMessage returns a new *Message object

func (*Message) AddAttachment

func (m *Message) AddAttachment(filename string, data io.Reader, ctype string) error

AddAttachment Adds an attachment to the message. If ctype is blank the func will try to guess the content-type

func (*Message) AddPGPKeys

func (m *Message) AddPGPKeys(keys *PGPKeys) error

AddPGPKeys sets the PGP keys for this message. If you plan to sign or encrypt the final email than this MUST be called before writing any message body. An error is raised if you try to assign keys after the body has been opened.

func (*Message) Buffer

func (m *Message) Buffer() *bytes.Buffer

Buffer Returns the raw email buffer

func (*Message) Bytes

func (m *Message) Bytes() []byte

Bytes Returns full email as bytes

func (*Message) Close

func (m *Message) Close()

Close Closes the mail.Writer

func (*Message) GetAllRcpts

func (m *Message) GetAllRcpts() []string

GetAllRcpts Returns all email recipients

func (*Message) SendMail

func (m *Message) SendMail(svc Service) error

SendMail Sends the message as an email via the given service.

func (*Message) SetBcc

func (m *Message) SetBcc(address string) *Message

SetBcc Set the Bcc: header

func (*Message) SetBccCSV

func (m *Message) SetBccCSV(address string) *Message

SetBccCSV Set Bcc: header. See SetToCSV comment

func (*Message) SetBccList

func (m *Message) SetBccList(addresses []string) *Message

SetBccList Set the Bcc: header to multiple addresses

func (*Message) SetBody

func (m *Message) SetBody(body string) error

SetBody Set the text/plain part of the email

func (*Message) SetBodyHTML

func (m *Message) SetBodyHTML(body string) error

SetBodyHTML Set the text/html part of the email

func (*Message) SetCc

func (m *Message) SetCc(address string) *Message

SetCc Set the Cc: header

func (*Message) SetCcCSV

func (m *Message) SetCcCSV(address string) *Message

SetCcCSV Set Cc: header. See SetToCSV comment.

func (*Message) SetCcList

func (m *Message) SetCcList(addresses []string) *Message

SetCcList Set the Cc: address header to multiple addresses

func (*Message) SetFrom

func (m *Message) SetFrom(address string) *Message

SetFrom Set the From: header

func (*Message) SetHTML

func (m *Message) SetHTML(msg io.Reader) error

SetHTML Set the text/html part of the email, via io.Reader instance

func (*Message) SetText

func (m *Message) SetText(msg io.Reader) error

SetText Set the text/plain part of the email, via io.Reader instance

func (*Message) SetTo

func (m *Message) SetTo(address string) *Message

SetTo Set the To: header

func (*Message) SetToCSV

func (m *Message) SetToCSV(address string) *Message

SetToCSV Set the To: header from a comma separated list of emails. Ie, user1@foobar.com, user2@foobar.com, etc.

func (*Message) SetToList

func (m *Message) SetToList(addresses []string) *Message

SetToList Set the To: header to multiple addresses

func (*Message) String

func (m *Message) String() string

String Returns full email as string

type OutboxService

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

OutboxService is a simple email service to store messages in a slice for use in tests, etc.

func NewOutboxService

func NewOutboxService() *OutboxService

NewOutboxService returns an smtp service instance

func (*OutboxService) Send

func (c *OutboxService) Send(msg *Message) error

Send match email Service interface signature

type PGPKeys

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

PGPKeys holds signer and recipient PGP keys

Example

package main

import (
	"log"
	"os"

	"petersanchez.com/x/carrier"
)

func main() {

	// You should handle errors properly in all instances below
	privkey, err := os.Open("privkey.asc")
	if err != nil {
		panic(err)
	}
	defer privkey.Close()

	// public key is optional. If present, the email will encrypted
	// for the recipient using the public key
	pubkey, err := os.Open("pubkey.asc")
	defer pubkey.Close()

	// Give pubkey if you want the email encrypted. If just providing
	// the private key, the email will be signed with the given key.
	keys, err := carrier.NewPGPKeys(privkey, nil)

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

	// You MUST assign keys before setting the body.
	err = msg.AddPGPKeys(keys)

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

	// Send email
	err = svc.Send(msg)
	log.Println("Successfully sent email.")
}

func NewPGPKeys

func NewPGPKeys(skey, rkey io.Reader) (*PGPKeys, error)

NewPGPKeys returns a PGPKey instance. If rkey is empty then the final email this PGPKeys instance is used for will only be signed.

type Service

type Service interface {
	Send(msg *Message) error
}

Service interface