email

README

A package for sending emails via AWS SES

Introduction

• Send emails via AWS SES
• Fetch attachments locally, from an S3 Bucket or via HTTP
• Supports both text/plain and text/html emails

Example

package main

import (
	"context"

	email "github.com/gofor-little/aws-email"
)

func main() {
	// Initialize the email package.
	if err := email.Initialize("AWS_PROFILE", "AWS_REGION"); err != nil {
		panic(err)
	}

	// Build the email data.
	data := email.Data{
		To:          []string{"joe@example.com"},
		From:        "john@example.com",
		Subject:     "Example Email",
		Body:        "Example Body",
		ContentType: email.ContentTypeTextPlain,
		Attachments: []email.Attachment{
			{
				Path: "/home/ubuntu/app/logo.png",
				Type: email.AttachmentTypeLocal,
			},
			{
				Path: "bucket-name/images/logo.png",
				Type: email.AttachmentTypeS3,
			},
			{
				Path: "https://example.com/logo.png",
				Type: email.AttachmentTypeHTTP,
			},
		},
	}

	// Send the email.
	if _, err := email.Send(context.Background(), data); err != nil {
		panic(err)
	}
}

Testing

Ensure the following environment variables are set, usually with a .env file.

• AWS_PROFILE (an AWS CLI profile name)
• AWS_REGION (a valid AWS region)
• TEST_EMAIL_FROM (a valid email address verified in SES)
• TEST_EMAIL_RECIPIENTS (a comma separated list of valid email addresses)

Documentation

Index

• Variables
• func Initialize(ctx context.Context, profile string, region string) error
• func Send(ctx context.Context, data Data) (string, error)
• type Attachment
  • func (a *Attachment) Load(ctx context.Context) ([]byte, error)
• type AttachmentType
• type ContentType
• type Data

Variables

var (
	// SESClient is used to send emails via SES.
	SESClient *ses.Client
	// S3Client is used to fetch attachments from S3.
	S3Client *s3.Client
	// HTTPClient is used to fetch attachments from the web.
	HTTPClient httpClient
)

Functions

func Initialize

func Initialize(ctx context.Context, profile string, region string) error

Initialize will initialize the email package. Both the profile and region parameters are optional if authentication can be achieved via another method. For example, environment variables or IAM roles.

func Send

func Send(ctx context.Context, data Data) (string, error)

Send loads the attachments, builds the email and sends it.

Types

type Attachment

type Attachment struct {
	Path string         `json:"path"`
	Type AttachmentType `json:"type"`
}

Attachment stores a path and type which are used to load it locally.

func (*Attachment) Load

func (a *Attachment) Load(ctx context.Context) ([]byte, error)

Load loads an Attachment's data and returns it as a byte slice.

type AttachmentType

type AttachmentType string

AttachmentType is a string type alias for the different supported attachment types.

const (
	// AttachmentTypeLocal is used for local attachments. As this is
	// deployed as a Lambda function it's primary use is testing.
	AttachmentTypeLocal AttachmentType = "local"
	// AttachmentTypeS3 is used for attachments stored in S3.
	AttachmentTypeS3 AttachmentType = "s3"
	// AttachmentTypeHTTP is used for attachments publicly accessible via HTTP.
	AttachmentTypeHTTP AttachmentType = "http"
)

type ContentType

type ContentType string

ContentType is a string type alias for the different supported content types.

const (
	// ContentTypeTextPlain is used for text/plain emails.
	ContentTypeTextPlain ContentType = "text/plain"
	// ContentTypeTextHTML is used for text/html emails.
	ContentTypeTextHTML ContentType = "text/html"
)

type Data

type Data struct {
	To          []string     `json:"to"`
	CC          *[]string    `json:"cc"`
	BCC         *[]string    `json:"bcc"`
	ReplyTo     *[]string    `json:"replyTo"`
	From        string       `json:"from"`
	Subject     string       `json:"subject"`
	Body        string       `json:"body"`
	ContentType ContentType  `json:"contentType"`
	Attachments []Attachment `json:"attachments"`
}

Data is the data required to build and send an email.