mbxs

Documentation

Overview

Package mbxs provides functions and types for working with IMAP mailboxes used by applications in this module.

Index

• Constants
• Variables
• func Connect(server string, port int, netType string, minTLSVer uint16, ...) (*client.Client, error)
• func ListMailboxes(c *client.Client, logger zerolog.Logger) ([]string, error)
• func Login(c *client.Client, username string, password string, logger zerolog.Logger) error
• func OAuth2ClientCredsAuth(ctx context.Context, imapClient *client.Client, mailbox string, ...) error
• func ValidateMailboxesList(c *client.Client, userMBXList []string, logger zerolog.Logger) ([]string, error)
• type Dialer
  • func (d *Dialer) Dial(network string, addr string) (net.Conn, error)
• type MailboxCheckResult
• type MailboxCheckResults
  • func CheckMail(c *client.Client, accountName string, validatedMBXList []string, ...) (MailboxCheckResults, error)
  • func (mcr MailboxCheckResults) GotMail() bool
  • func (mcr MailboxCheckResults) MessagesFoundSummary() string
  • func (mcr MailboxCheckResults) TotalMessagesFound() int
• type Message

Constants

const (

	// NetTypeTCPAuto indicates that either of IPv4 or IPv6 will be used to
	// establish a connection depending on the specified IP Address.
	NetTypeTCPAuto string = "tcp"

	// NetTypeTCP4 indicates an IPv4-only network.
	NetTypeTCP4 string = "tcp4"

	// NetTypeTCP6 indicates an IPv6-only network.
	NetTypeTCP6 string = "tcp6"
)

Known, named networks used for IMAP connections. These names match the network names used by the `net` standard library package.

const DefaultReplacementString string = textutils.EmojiScissors

DefaultReplacementString is used when replacing Unicode characters incompatible with a target character set. The common use case is substituting Unicode characters incompatible with the utf8mb3 character set.

const (

	// The LOGINDISABLED capability indicates that the LOGIN command is not
	// permitted. This is most often due to TLS not active for the current
	// connection.
	// https://datatracker.ietf.org/doc/html/rfc3501#section-6.1.1
	IMAPv4CapabilityLoginDisabled string = "LOGINDISABLED"
)

IMAP capabilities

const (

	// The LOGIN command identifies the client to the server and carries the
	// plaintext password authenticating this user.
	// https://datatracker.ietf.org/doc/html/rfc3501#section-6.2.3
	IMAPv4CommandLogin string = "LOGIN"
)

IMAP commands

Variables

var (
	// ErrRequiredAuthMechanismUnsupported indicates that a required
	// authentication mechanism is unsupported.
	ErrRequiredAuthMechanismUnsupported = errors.New("required auth mechanism unsupported")
)

Functions

func Connect

func Connect(server string, port int, netType string, minTLSVer uint16, logger zerolog.Logger) (*client.Client, error)

Connect opens a connection to the specified IMAP server using the specified network type, returns a client connection or an error if one occurs.

func ListMailboxes

func ListMailboxes(c *client.Client, logger zerolog.Logger) ([]string, error)

ListMailboxes lists mailboxes associated with the logged in user account (by way of an IMAP client connection).

func Login

func Login(c *client.Client, username string, password string, logger zerolog.Logger) error

Login uses the provided client connection and credentials to login to the IMAP server using plaintext authentication. Most servers will reject logins unless TLS is used.

func OAuth2ClientCredsAuth

func OAuth2ClientCredsAuth(
	ctx context.Context,
	imapClient *client.Client,
	mailbox string,
	clientID string,
	clientSecret string,
	scopes []string,
	tokenEndpointURL string,
	maxAttempts int,
	logger zerolog.Logger,
) error

OAuth2ClientCredsAuth uses the provided client connection and OAuth2 settings for Client Credentials flow authentication.

The XOAUTH2 authentication mechanism is used as described in https://developers.google.com/gmail/xoauth2_protocol and https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth#sasl-xoauth2

func ValidateMailboxesList

func ValidateMailboxesList(c *client.Client, userMBXList []string, logger zerolog.Logger) ([]string, error)

ValidateMailboxesList receives a list of requested mailboxes and returns a list of mailboxes from that list which have been confirmed to be present for the associated user account.

Types

type Dialer

type Dialer struct {
	// If specified, this value overrides the value supplied to
	// `go-imap/client.Dial*` functions and is used in its place to establish
	// a connection on the user-specified network type.
	NetworkTypeUserOverride string

	// Original value supplied to `go-imap/client.Dial*` functions. Unless
	// overridden by the user, this value is used to establish a connection on
	// the supplied network type.
	NetworkTypeOriginalValue string
}

Dialer is an implementation of the go-imap/client.Dialer interface. This implementation is used to override the default "auto" network type selection behavior applied by `Dial*` functions within the go-imap/client package.

func (*Dialer) Dial

func (d *Dialer) Dial(network string, addr string) (net.Conn, error)

Dial implements the go-imap/client.Dialer interface to override the default "auto" network type selection behavior applied by `Dial*` functions within the go-imap/client package.

type MailboxCheckResult

type MailboxCheckResult struct {
	MailboxName string
	ItemsFound  int
	Messages    []Message
}

MailboxCheckResult records mail items found for a specific mailbox.

type MailboxCheckResults

type MailboxCheckResults []MailboxCheckResult

MailboxCheckResults represents a collection of all results from mailbox checks.

func CheckMail

func CheckMail(c *client.Client, accountName string, validatedMBXList []string, logger zerolog.Logger) (MailboxCheckResults, error)

CheckMail generates a listing of emails within the provided (and validated) mailbox list for the associated account name.

func (MailboxCheckResults) GotMail

func (mcr MailboxCheckResults) GotMail() bool

GotMail returns true if mail was found in checked mailboxes or false if not.

func (MailboxCheckResults) MessagesFoundSummary

func (mcr MailboxCheckResults) MessagesFoundSummary() string

MessagesFoundSummary returns a one-line summary of the mail items found in checked mailboxes.

func (MailboxCheckResults) TotalMessagesFound

func (mcr MailboxCheckResults) TotalMessagesFound() int

TotalMessagesFound returns a count of all messages found across all checked mailboxes.

type Message

type Message struct {

	// MessageID is the unique ID for an email message found within a
	// specified mailbox.
	MessageID string

	// EnvelopeDate is the crafted date value for an email message found
	// within a specific mailbox. This is the date set by the mail transport
	// software that initially received the email message from the mail
	// client. While this can be incorrect or forged, it is generally more
	// reliable than the date email header value.
	EnvelopeDate time.Time

	// EnvelopeDateFormatted is a date/time value stored as a string for later
	// use with templates.
	EnvelopeDateFormatted string

	// OriginalSubject is the unmodified, original subject line of an email
	// message found within a specified mailbox.
	OriginalSubject string

	// ModifiedSubject is the subject line of the original email message that
	// has been modified to remove characters incompatible with the a target
	// character set (e.g., MySQL's utf8mb3).
	ModifiedSubject string
}

Message is a subset of attributes for an email message found within a specified mailbox.