mailer

Documentation

Overview

Package mailer can be used to send mails through a mailer service.

Install it as a server module and then use Send(...) API.

Using "gae" backend requires running on GAE and having "app_engine_apis: true" in the module YAML. See https://cloud.google.com/appengine/docs/standard/go/services/access.

Index

• Variables
• func NewModule(opts *ModuleOptions) module.Module
• func NewModuleFromFlags() module.Module
• func Send(ctx context.Context, msg *Mail) error
• func Use(ctx context.Context, m Mailer) context.Context
• type Mail
• type Mailer
• type ModuleOptions
  • func (o *ModuleOptions) Register(f *flag.FlagSet)

Variables

var ModuleName = module.RegisterName("go.chromium.org/luci/server/mailer")

ModuleName can be used to refer to this module when declaring dependencies.

Functions

func NewModule

func NewModule(opts *ModuleOptions) module.Module

NewModule returns a server module that initializes the mailer in the context.

func NewModuleFromFlags

func NewModuleFromFlags() module.Module

NewModuleFromFlags is a variant of NewModule that initializes options through command line flags.

Calling this function registers flags in flag.CommandLine. They are usually parsed in server.Main(...).

func Send

func Send(ctx context.Context, msg *Mail) error

Send sends the given message through a mailer client in the context.

Panics if the context doesn't have a mailer. Transient errors are tagged with transient.Tag. All other errors are fatal and should not be retried.

func Use

func Use(ctx context.Context, m Mailer) context.Context

Use replaces the mailer in the context.

Useful in tests to mock the real mailer.

Types

type Mail

type Mail struct {
	// Sender is put into "From" email header field.
	//
	// If empty, some default value will be used. See ModuleOptions.
	Sender string

	// ReplyTo is put into "Reply-To" email header field.
	//
	// Optional.
	ReplyTo string

	// To is put into "To" email header field.
	To []string

	// Cc is put into "Cc" email header field.
	Cc []string

	// Bcc is put into "Bcc" email header field.
	Bcc []string

	// Subject is put into "Subject" email header field.
	Subject string

	// TextBody is a plaintext body of the email message.
	//
	// Can be used together with HTMLBody to send a multipart email.
	TextBody string

	// HTMLBody is an HTML body of the email message.
	//
	// Can be used together with TextBody to send a multipart email.
	HTMLBody string
}

Mail represents an email message.

Addresses may be of any form permitted by RFC 822. At least one of To, Cc, or Bcc must be non-empty. At least one of TextBody or HTMLBody must be non-empty.

type Mailer

type Mailer func(ctx context.Context, msg *Mail) error

Mailer lives in the context and knows how to send Messages.

Must tag transient errors with transient.Tag. All other errors are assumed to be fatal.

type ModuleOptions

type ModuleOptions struct {
	// MailerService defines what mailing backend to use.
	//
	// Supported values are:
	//   * "https://<host>"" to use a luci.mailer.v1.Mailer pRPC service.
	//   * "gae" to use GAE bundled Mail service (works only on GAE, see below).
	//
	// Also "http://<host>" can be used locally to connect to a local pRPC mailer
	// service without TLS. This is useful for local integration tests.
	//
	// Using "gae" backend requires running on GAE and having
	// "app_engine_apis: true" in the module YAML.
	// See https://cloud.google.com/appengine/docs/standard/go/services/access.
	//
	// On GAE defaults to "gae", elsewhere defaults to no backend at all which
	// results in emails being logged in local logs only and not actually sent
	// anywhere.
	MailerService string

	// DefaultSender is a value to use in "From" email header field by default.
	//
	// Used only if `Sender` field of Mail struct is not populated.
	//
	// On GAE defaults to "<appid> noreply@<appid>.appspotmail.com".
	//
	// When using a pRPC backend, defaults to an empty string, which indicates
	// that the pRPC backend should make the decision itself.
	DefaultSender string
}

ModuleOptions contain configuration of the mailer server module.

It will be used to initialize the mailer in the context.

func (*ModuleOptions) Register

func (o *ModuleOptions) Register(f *flag.FlagSet)

Register registers the command line flags.