email

Documentation

Overview

Package email provides an interface to send messages over email.

Example

package main

import (
	"go.thethings.network/lorawan-stack/v3/pkg/email"
	"go.thethings.network/lorawan-stack/v3/pkg/fetch"
)

var fetcher fetch.Interface

// globalData would be global data that may be used in every email.
type globalData struct {
	Network struct {
		Name              string
		IdentityServerURL string
		ConsoleURL        string
	}
	User struct {
		ID    string
		Name  string
		Email string
	}
}

func (g globalData) Recipient() (name, address string) {
	return g.User.Name, g.User.Email
}

// welcomeEmail is the data specifically for the welcome email.
type welcomeEmail struct {
	globalData
	ActivationToken string
}

// TemplateName returns the name of the template that the registry should search for.
func (welcome welcomeEmail) TemplateName() string { return "welcome" }

const welcomeSubject = `Welcome to {{.Network.Name}}`

const welcomeHTML = `<div style="styles to hide the pre-header-text">Welcome to {{.Network.Name}}, {{.User.Name}}!</div>
{{ template "header.html" . }}
<h1>Welcome to {{.Network.Name}}, {{.User.Name}}!</h1><br>
Please activate your account by visiting <a href="{{.Network.IdentityServerURL}}/activate/{{.ActivationToken}}">this link</a>.
{{ template "footer.html" . }}`

const welcomeText = `{{ template "header.txt" . }}

Welcome to {{.Network.Name}}, {{.User.Name}}!

Please activate your account by visiting {{.Network.IdentityServerURL}}/activate/{{.ActivationToken}}.

{{ template "footer.txt" . }}`

func (welcome welcomeEmail) DefaultTemplates() (subject, html, text string) {
	return welcomeSubject, welcomeHTML, welcomeText
}

func main() {
	// The email sender can be Sendgrid, SMTP, ...
	var sender email.Sender

	// This can fetch templates from the filesystem, github, S3, ...
	registry, err := email.NewTemplateRegistry(fetcher)
	if err != nil {
		return // error setting up the template registry
	}

	data := welcomeEmail{}
	data.User.Name = "John Doe"
	data.User.Email = "john.doe@example.com"
	data.Network.Name = "The Things Network"
	data.Network.IdentityServerURL = "https://id.thethings.network"

	// The first time you render an email, the template will also be compiled.
	// Any later changes to the template will not be picked up.
	// The compiled template will render into an email that is ready to be sent.
	message, err := registry.Render(data)
	if err != nil {
		return // error rendering the message
	}

	err = sender.Send(message)
	if err != nil {
		return // error sending the message
	}

	// done!
}

Index

• type Config
• type Message
• type MessageData
• type MessageTemplate
  • func (m MessageTemplate) Execute(data interface{}) (*Message, error)
• type Sender
• type TemplateRegistry
  • func NewTemplateRegistry(fetcher fetch.Interface, includes ...string) (*TemplateRegistry, error)
  • func (r *TemplateRegistry) Render(data MessageData) (*Message, error)

Examples

• Package

Types

type Config

type Config struct {
	SenderName    string `name:"sender-name" description:"The name of the sender"`
	SenderAddress string `name:"sender-address" description:"The address of the sender"`
	Provider      string `name:"provider" description:"Email provider to use"`
	Network       struct {
		Name              string `name:"name" description:"The name of the network"`
		IdentityServerURL string `name:"identity-server-url" description:"The URL of the Identity Server"`
		ConsoleURL        string `name:"console-url" description:"The URL of the Console"`
	} `name:"network" description:"The network of the sender"`
}

Config for sending emails

type Message

type Message struct {
	TemplateName string

	RecipientName    string
	RecipientAddress string

	Subject  string
	HTMLBody string
	TextBody string
}

Message for sending over email.

type MessageData

type MessageData interface {
	TemplateName() string
	Recipient() (name, address string)
	DefaultTemplates() (subject, html, text string)
}

MessageData interface contains everything we need to create an email.Message. The DefaultTemplates should be able to execute using the MessageData itself.

type MessageTemplate

type MessageTemplate struct {
	Name            string
	SubjectTemplate *template.Template
	HTMLTemplate    *template.Template
	TextTemplate    *template.Template
}

MessageTemplate is the template for an email message.

func (MessageTemplate) Execute

func (m MessageTemplate) Execute(data interface{}) (*Message, error)

Execute the message template, rendering it into a Message.

type Sender

type Sender interface {
	Send(message *Message) error
}

Sender is the interface for sending messages over email.

type TemplateRegistry

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

TemplateRegistry contains multiple email templates, identified by name.

func NewTemplateRegistry

func NewTemplateRegistry(fetcher fetch.Interface, includes ...string) (*TemplateRegistry, error)

NewTemplateRegistry returns a new template registry that uses the given fetcher.

func (*TemplateRegistry) Render

func (r *TemplateRegistry) Render(data MessageData) (*Message, error)

Render message template data into a message.