raweml

package module
v1.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 7, 2022 License: MIT Imports: 18 Imported by: 0

README

RawEml

This package is for a granual control of emails that are sent with AWS SES.
It supports setting the email priority, conversation topic for grouping and any other email header tags.

Build Status Coverage Status Go Report Card Go Reference

Description

RawEml package allows you to specify any header attributes for an email sent with AWS SES

Supported email attributes:

  • priority
  • thread-topic (works for Outlook but not for Gmail)
  • any additional attributes via Headers field

NOTE: Attributes defined in Headers field have precedence over any other fields.
Example: If From header attribute is defined in the Headers field then the value in email.From will be ignored

Following fields can be used to build the email struct

  • From (multiple addresses)
  • Recipients
    • to (multiple addresses)
    • cc (multiple addresses)
    • bcc (multiple addresses)
  • Feedback (feedback address)
  • Subject
  • Text body
  • HTML body
  • CharSet
  • Attachment
  • Headers (email header attributes)
  • Priority [high, normal, low]
  • Topic
    • Thread-index [Date, GUID(topic), Child Block]
    • References topic
  • InReplyTo (Message-ID of the email to reply to in order for the email to be threaded. Gmail requires direct connection between emails to be threaded. Outlook is using Thread-Index and Thread-Topic instead)
  • AwsRegion (AWS SES region. Example us-east-1)

Download

go get github.com/boseca/raweml

Usage

To send the email call raweml.Send(email) method.

Examples

See the examples in the documentation.

Build

go build

Test

  • Run all tests
go test -v
  • Run single test
go test -v -run ^TestThread/Test_Parsing_Thread-Index$ github.com/boseca/raweml
  • Run examples

Make sure to change the sender email address to an AWS verified email address before running the examples

go test -v ./example
  • Lint
golint
  • Show code coverage
go test -coverprofile=c.out
sed -i "s/$(pwd|sed 's/\//\\\//g')/./g" c.out   # convert absolute path to relative path 
go tool cover -html=c.out -o=c.html             # optional
gcov2lcov -infile=c.out -outfile=c.lcov
genhtml -q --legend -o coverage_html --title='Raweml' c.lcov
x-www-browser file:///$(pwd)/coverage_html/index.html

Documentation

Overview

Package raweml allows you to send emails with Priority and Conversation Topic using the AWS SES raw email.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Send

func Send(email Email) error

Send sends the email using the AWS SES

Types

type Attachment

type Attachment struct {
	Name        string    // Name of the attachment
	Data        io.Reader // reader for the attachment. WARNING do not set this value to a nil *bytes.Buffer it will not be same as nil io.Reader and it will cause panic.
	FileName    string    // Name must be set to a valid fully qulified file name. If the FileName is set the Data reader will be ignored.
	ContentID   string    // Optional. Used for embedding images into the email (e.g. <img src="cid:{{ContentID}}">)
	ContentType string    // Optional. When blank falls back to 'application/octet-stream'.
}

Attachment represents an email attachment.

type ChildBlock

type ChildBlock struct {
	TimeFlag       bool
	TimeDifference int64 // Unix NanoSecond
	RandomNum      byte
	SequenceCount  byte
}

ChildBlock represents a sub thread of the email thread

  • TimeFlag: 1 bit 0 when TimeDiff < 0.02s && TimeDiff > 2 years; 1 when TimeDiff < 1s && TimeDiff > 56 years)
  • TimeDifference: time difference between the child block create time and the time in the header block expressed in FILETIME units if TimeFlag = 0 : discard high 15 bits and low 18 bits if TimeFlag = 1 : discard high 10 bits and low 32 bits
  • RandomNum: random number gernerated by calling GetTickCount()
  • SequenceCount: default set to 0 (Four bits containing a sequence count that is taken from part of the random number.)

func NewChildBlock

func NewChildBlock(deltaTimeUxNs int64) (r ChildBlock)

NewChildBlock creates a child header block

func ParseChildBlock

func ParseChildBlock(blockString string) (block ChildBlock, err error)

ParseChildBlock converts string to a ChildBlock struct

func (ChildBlock) Bytes

func (block ChildBlock) Bytes() []byte

Bytes returns bits representing the Child block : 40 bits: 1 flag, 31 time diff, 4 random, 4 seq

func (ChildBlock) String

func (block ChildBlock) String() string

String returns the base64 encoded string of the header child block

type Email

type Email struct {
	From        string
	Recipients  Recipients
	Feedback    string // feedback destination email address. If left blank "Return-path" or "From" address will be used instead.
	Subject     string // to change subject Charset use the MIME encoded-word syntax (e.g. "=?utf-8?B?5L2g5aW9?=") (ref: https://docs.aws.amazon.com/ses/latest/dg/send-email-raw.html)
	TextBody    string
	HTMLBody    string
	CharSet     string
	Attachments []Attachment // set it to `nil` if there are no attachments
	Headers     textproto.MIMEHeader
	Priority    EmailPriority
	Topic       string
	InReplyTo   string // Message-ID of the email to reply to in order for the email to be threaded. Gmail requires direct connection between emails to be threaded. Outlook is using Thread-Index and Thread-Topic instead
	AwsRegion   string // AWS Region of the SES service
}

Email is the structure containing all email details. To send the email just call the Send() method.

func (Email) Bytes

func (email Email) Bytes() ([]byte, error)

Bytes converts the email structure into email raw data bytes

func (Email) GetHeaders

func (email Email) GetHeaders() *textproto.MIMEHeader

GetHeaders returns a pointer to the email.Headers field

func (Email) GetSendRawEmailInput

func (email Email) GetSendRawEmailInput() (*ses.SendRawEmailInput, error)

GetSendRawEmailInput converts the email to *ses.SendRawEmailInput structure required by ses.SendRawEmail() method

func (Email) GetSource

func (email Email) GetSource() *string

GetSource returns the From email address

func (Email) Send

func (email Email) Send() (*ses.SendRawEmailOutput, error)

Send sends the email

func (Email) SendWithSession

func (email Email) SendWithSession(svc *ses.SES, input *ses.SendRawEmailInput) (result *ses.SendRawEmailOutput, err error)

SendWithSession sends the email using provided svc session

func (*Email) SetHeader

func (email *Email) SetHeader(key, value string)

SetHeader sets the header entries associated with key to the single element value. It replaces any existing values associated with key.

type EmailPriority

type EmailPriority string

EmailPriority defines the type of priorty for the email

const (
	PriorityHigh   EmailPriority = "High"
	PriorityNormal EmailPriority = "Normal"
	PriorityLow    EmailPriority = "Low"
)

Email Priority Types

func (EmailPriority) String

func (priority EmailPriority) String() string

String converts email priority to string

func (EmailPriority) ToNumber

func (priority EmailPriority) ToNumber() string

ToNumber converts email priority to a string number

type Filetime

type Filetime struct {
	// --------------------------
	// 	Generic file time stamp :
	// --------------------------
	// 	31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 	15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
	//  |<------ year ------>|<- month ->|<---- day --->|	|<--- hour --->|<---- minute --->|<- second/2 ->|
	//
	//    Offset   Length   Contents
	// 	   0       7 bits   year     years since 1980
	// 	   7       4 bits   month    [1..12]
	//    11       5 bits   day      [1..31]
	//    16       5 bits   hour     [0..23]
	//    21       6 bits   minite   [0..59]
	//    27       5 bits   second/2 [0..29]
	// --------------------------
	// ref: https://golang.org/src/syscall/types_windows.go
	LowDateTime  uint32
	HighDateTime uint32
}

Filetime represents the date and time for a file. It is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC) This is different from Unix time which is the number of nanoseconds elapsed since January 1, 1970, 00:00:00 (UTC)

func UnixNanoToFiletime

func UnixNanoToFiletime(nsec int64) (ft Filetime)

UnixNanoToFiletime converts nano seconds to Filetime

func (*Filetime) UnixNanoseconds

func (ft *Filetime) UnixNanoseconds() int64

UnixNanoseconds returns Filetime in nanoseconds since Epoch (00:00:00 UTC, January 1, 1970).

type Recipients

type Recipients struct {
	BccAddresses []*string `type:"list"`
	CcAddresses  []*string `type:"list"`
	ToAddresses  []*string `type:"list"`
	// contains filtered or unexported fields
}

Recipients contains list of To, Cc, Bcc recipients

func NewRecipients

func NewRecipients(to string, cc string, bcc string) (r Recipients)

NewRecipients converts comma separated list of to, cc and bcc into Recipients structure

func (Recipients) All

func (r Recipients) All() []*string

All returns all recipients as an array of string pointers

func (Recipients) Bcc

func (r Recipients) Bcc() string

Bcc returns a string of comma separated Bcc recipients

func (Recipients) Cc

func (r Recipients) Cc() string

Cc returns a string of comma separated Cc recipients

func (Recipients) IsEmpty

func (r Recipients) IsEmpty() bool

IsEmpty returns true if there are no recipients in any of To, Cc or Bcc

func (Recipients) String

func (r Recipients) String() string

String converts Recipients structure to a string with comma separated recipients

func (Recipients) To

func (r Recipients) To() string

To returns a string of comma separated To recipients

type Thread

type Thread struct {
	DateUnixNano int64 // Thread Date in Unix Nanoseconds

	ChildBlocks []ChildBlock // Sub-Thread
	// contains filtered or unexported fields
}

Thread represents an email thread (conversation group)

func NewEmailThreadFromParams

func NewEmailThreadFromParams(dateUnixNanoSec int64, guid uuid.UUID, topic string, childBlocks []ChildBlock) (r Thread)

NewEmailThreadFromParams creates a new Thread struct from arguments

func NewThread

func NewThread(topic string) Thread

NewThread creates a new Thread struct based on the provided `topic` argument

func ParseEmailThread

func ParseEmailThread(idx string, topic string) (r Thread, err error)

ParseEmailThread creates thread based on the idx and topic

func (*Thread) AddChildBlock

func (thread *Thread) AddChildBlock()

AddChildBlock ads a child block to the emails thread

func (Thread) Bytes

func (thread Thread) Bytes() (r []byte)

Bytes returns thread bytes data encoded in Base64

func (Thread) GUIDBytes

func (thread Thread) GUIDBytes() []byte

GUIDBytes returns bytes of the thread GUID

func (Thread) GetGUID

func (thread Thread) GetGUID() uuid.UUID

GetGUID returns thread GUID

func (Thread) GetTopic

func (thread Thread) GetTopic() string

GetTopic returns thread topic

func (Thread) Index

func (thread Thread) Index() string

Index is an alias for String() function that returns the thread as Base64 encoded string

func (*Thread) Reference

func (thread *Thread) Reference() string

Reference returns a hashed version of the Thread GUID that is created based on nameSpaceAppID and Topic

func (Thread) String

func (thread Thread) String() string

String returns thread data as Base64 encoded string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL