gmail

README

gmail

gmail is a wrapper Go library for working with the Google gmail API.

It is in active development and makes no guarantees about API stability. The long-term goal is to create a standard mail interface we can use across all email clients, like Gmail and Outlook.

Documentation

Index

• Constants
• func CloneMessage(src *Service, dst *Service, messageID string, dstLabelIds []string) (*gmail.Message, error)
• func ExecuteWithRetries[T any](f func() (T, error)) (T, error)
• func IsGoogleAPIError(err error) bool
• func IsMessageSent(m *gmail.Message) bool
• func IsNotFound(err error) bool
• func IsOAuth2Error(err error) bool
• func IsRateLimitError(err error) bool
• func MessageBody(m *gmail.Message) string
• func MessageHasLabel(m *gmail.Message, id string) bool
• func MessageHeader(m *gmail.Message, header string) string
• func MessageSender(m *gmail.Message) string
• func MessageSenderEmail(m *gmail.Message) string
• func MessageSubject(m *gmail.Message) string
• func SortMessagesByDate(messages []*gmail.Message)
• type ForwardMessage
  • func (m ForwardMessage) Create() *gmail.Message
  • func (m ForwardMessage) GetParentHeader(name string) string
  • func (m ForwardMessage) InReplyTo() string
  • func (m ForwardMessage) ParentBody() string
  • func (m ForwardMessage) Raw() string
  • func (m ForwardMessage) References() string
• type Service
  • func NewDefaultService(ctx context.Context, auth []byte) (*Service, error)
  • func NewService(ctx context.Context, creds []byte, auth []byte) (*Service, error)
  • func (s *Service) BlockMessage(id string, labels *srclabel.Labels) error
  • func (s *Service) CreateLabel(l *gmail.Label) (*gmail.Label, error)
  • func (s *Service) ForwardEmail(messageID, to string) (*gmail.Message, error)
  • func (s *Service) GetMessage(id string) (*gmail.Message, error)
  • func (s *Service) GetOrCreateLabel(l *gmail.Label) (*gmail.Label, error)
  • func (s *Service) GetOrCreateSRCLabels() (*srclabel.Labels, error)
  • func (s *Service) GetThread(id, format string) (*gmail.Thread, error)
  • func (s *Service) IsSenderAllowed(sender string) (bool, error)
  • func (s *Service) IsSenderBlocked(sender string) (bool, error)
  • func (s *Service) ListLabels() (*gmail.ListLabelsResponse, error)
  • func (s *Service) Profile() (*gmail.Profile, error)

Constants

const (
	// FwdMsgDelimiter is the delimiter used to separate the forwarded message from the original message.
	FwdMsgDelimiter = "---------- Forwarded message ---------"
)

Functions

func CloneMessage

func CloneMessage(src *Service, dst *Service, messageID string, dstLabelIds []string) (*gmail.Message, error)

CloneMessage is a convenience function to cloning a message from one inbox to another. On success, it will return the new destination message. Cloning differs from forwarding because it preserves the original message sender, recipient, and all other headers. TODO: Support recipient anonymization (i.e. randomize 'To' header, strings.Replace first and last name).

func ExecuteWithRetries

func ExecuteWithRetries[T any](f func() (T, error)) (T, error)

ExecuteWithRetries executes a function and automatically retries with an exponential back-off if the function rate turns a googleapi rate limit error (IsRateLimitError).

func IsGoogleAPIError

func IsGoogleAPIError(err error) bool

IsGoogleAPIError checks if the error is a googleapi.Error

func IsMessageSent

func IsMessageSent(m *gmail.Message) bool

IsMessageSent returns true if the message was sent by the current user

There are a number of ways to check if a message was sent by a user. This function checks if the message contains the system "SENT" label, which allows us to only fetch the minimal message information (no headers) from a thread.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound checks for a status not found (404) response from a Google API

func IsOAuth2Error

func IsOAuth2Error(err error) bool

IsOAuth2Error checks if the error is an oauth2.RetrieveError. This is useful for detecting expired or revoked access tokens.

func IsRateLimitError

func IsRateLimitError(err error) bool

IsRateLimitError checks for a status too many requests (429) response from a Google API

func MessageBody

func MessageBody(m *gmail.Message) string

MessageBody returns the body of the message as a string

It first checks for a text/plain body. If none is found, it checks for a text/html body.

func MessageHasLabel

func MessageHasLabel(m *gmail.Message, id string) bool

MessageHasLabel returns true if the message contains the given label id

func MessageHeader

func MessageHeader(m *gmail.Message, header string) string

MessageHeader returns the value of the header with the given name

func MessageSender

func MessageSender(m *gmail.Message) string

MessageSender returns the sender of the message The sender is the email address of the first "From" header

func MessageSenderEmail

func MessageSenderEmail(m *gmail.Message) string

MessageSenderEmail returns the email address of the sender It uses MessageSender to get the sender string, and then extracts the email address from it.

Example: "John Doe" <john.doe@example.com>" -> "john.doe@example.com"

func MessageSubject

func MessageSubject(m *gmail.Message) string

MessageSubject returns the subject of the message

func SortMessagesByDate

func SortMessagesByDate(messages []*gmail.Message)

SortMessagesByDate sorts messages by date received by gmail (ascending) The messages are sorted in place.

Types

type ForwardMessage

type ForwardMessage struct {
	Sender string
	To     string
	Parent *gmail.Message
}

ForwardMessage represents a message to be forwarded.

func (ForwardMessage) Create

func (m ForwardMessage) Create() *gmail.Message

Create a send-able gmail message from a forwarded message

func (ForwardMessage) GetParentHeader

func (m ForwardMessage) GetParentHeader(name string) string

GetParentHeader returns the value of the header with the given name from the parent message. It ignores casing when looking at headers.

func (ForwardMessage) InReplyTo

func (m ForwardMessage) InReplyTo() string

InReplyTo returns the contents of the "In-Reply-To:" field of the message to which this one is a reply (the "parent message"). It follows the spec described in https://tools.ietf.org/html/rfc2822#section-3.6.4

The "In-Reply-To:" field will contain the contents of the "Message-ID:" field of the message to which this one is a reply (the "parent message"). If there is more than one parent message, then the "In-Reply-To:" field will contain the contents of all of the parents' "Message-ID:" fields. If there is no "Message-ID:" field in any of the parent messages, then the new message will have no "In-Reply-To:" field.

func (ForwardMessage) ParentBody

func (m ForwardMessage) ParentBody() string

ParentBody returns the body of the parent message. Note: We always convert to text/plain. It's simpler to do deal with and is sufficient for our purposes.

func (ForwardMessage) Raw

func (m ForwardMessage) Raw() string

Raw returns the raw RFC-822 compliant forwarded message.

func (ForwardMessage) References

func (m ForwardMessage) References() string

References returns the contents of the "References:" field of the message to which this one is a reply (the "parent message"). It follows the spec described in https://tools.ietf.org/html/rfc2822#section-3.6.4

The "References:" field will contain the contents of the parent's "References:" field (if any) followed by the contents of the parent's "Message-ID:" field (if any). If the parent message does not contain a "References:" field but does have an "In-Reply-To:" field containing a single message identifier, then the "References:" field will contain the contents of the parent's "In-Reply-To:" field followed by the contents of the parent's "Message-ID:" field (if any). If the parent has none of the "References:", "In-Reply-To:", or "Message-ID:" fields, then the new message will have no "References:" field.

type Service

type Service struct {
	*gmail.Service
	UserID string
	// contains filtered or unexported fields
}

Service is a wrapper around the gmail service that adds some convenience methods.

func NewDefaultService

func NewDefaultService(ctx context.Context, auth []byte) (*Service, error)

func NewService

func NewService(ctx context.Context, creds []byte, auth []byte) (*Service, error)

func (*Service) BlockMessage

func (s *Service) BlockMessage(id string, labels *srclabel.Labels) error

BlockMessage blocks a message by moving moving out of the users inbox and into the block graveyard

func (*Service) CreateLabel

func (s *Service) CreateLabel(l *gmail.Label) (*gmail.Label, error)

func (*Service) ForwardEmail

func (s *Service) ForwardEmail(messageID, to string) (*gmail.Message, error)

ForwardEmail is a good enough implementation of forwarding an email in the same format as the gmail client. It is good enough because it doesn't naively handle HTML mime-type content or when there are multiple parent messages. This is sufficient for our purposes.

func (*Service) GetMessage

func (s *Service) GetMessage(id string) (*gmail.Message, error)

GetMessage() fetches a message by ID It is a convenience method that wraps the gmail API call. It opens opportunities for caching and rate-limiting handling

func (*Service) GetOrCreateLabel

func (s *Service) GetOrCreateLabel(l *gmail.Label) (*gmail.Label, error)

func (*Service) GetOrCreateSRCLabels

func (s *Service) GetOrCreateSRCLabels() (*srclabel.Labels, error)

GetOrCreateSRCLabels fetches or creates all of the labels managed by SRC Label IDs are unique to each gmail account, so we need to list all labels and match based off names.

func (*Service) GetThread

func (s *Service) GetThread(id, format string) (*gmail.Thread, error)

GetThread() fetches a thread by ID with messages in the given format See https://developers.google.com/gmail/api/reference/rest/v1/users.threads/get#Format for format values

It is a convenience method that wraps the gmail API call It opens opportunities for caching and rate-limiting handling

func (*Service) IsSenderAllowed

func (s *Service) IsSenderAllowed(sender string) (bool, error)

IsSenderAllowed checks if message is on the user's allow list

func (*Service) IsSenderBlocked

func (s *Service) IsSenderBlocked(sender string) (bool, error)

IsSenderBlocked checks if message is on the user's block list

func (*Service) ListLabels

func (s *Service) ListLabels() (*gmail.ListLabelsResponse, error)

func (*Service) Profile

func (s *Service) Profile() (*gmail.Profile, error)