email

package
v0.0.0-...-6fab949 Latest Latest
Warning

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

 Go to latest Published: Aug 8, 2023 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DeliveryEventTypeDelivered indicates that the message was successfully delivered.
	// This event is sent when the message is accepted by the recipient's mail server.
	DeliveryEventTypeDelivered = DeliveryEventType(driver.DeliveryEventTypeDelivered)
	// DeliveryEventTypeBounce indicates that the message was rejected by the recipient's mail server.
	// This event is sent when the recipient's mail server permanently rejects the message.
	DeliveryEventTypeBounce = DeliveryEventType(driver.DeliveryEventTypeBounce)
	// DeliveryEventTypeDelayed indicates that the message was delayed.
	DeliveryEventTypeDelayed = DeliveryEventType(driver.DeliveryEventTypeDelayed)
	// DeliveryEventTypeRenderingFailure indicates that the message could not be rendered.
	// This event is sent when the message could not be rendered.
	DeliveryEventTypeRenderingFailure = DeliveryEventType(driver.DeliveryEventTypeRenderingFailure)
	// DeliveryEventTypeSend indicates that the message was send to the email service and is waiting for delivery.
	DeliveryEventTypeSend = DeliveryEventType(driver.DeliveryEventTypeSend)
	// DeliveryEventTypeFromAddressFailure indicates that the message could not be sent because the From address was invalid.
	// This event is sent when the From address is invalid, missing or does not have the required permissions (i.e. unverified).
	DeliveryEventTypeFromAddressFailure = DeliveryEventType(driver.DeliveryEventTypeFromAddressFailure)
)
View Source 
const (
	// BounceTypeTransient represents the bounce type of transient nature.
	BounceTypeTransient = BounceType(driver.BounceTypeTransient)
	// BounceTypePermanent represents the bounce type of permanent nature.
	BounceTypePermanent = BounceType(driver.BounceTypePermanent)
)

Variables

View Source 
var NewDeliverySubscription = newDeliverySubscription

NewDeliverySubscription is intended for use by drivers only. Do not use in application code.

View Source 
var NewSender = newSender

NewSender is intended for use by drivers only. Do not use in application code.

View Source 
var NewTemplatedSender = newTemplatedSender

NewTemplatedSender is intended for use by drivers only. Do not use in application code.

Functions

func VerifyAddressFormat 

func VerifyAddressFormat(address string) error

func VerifyAddressListFormat 

func VerifyAddressListFormat(addressList string) error

VerifyAddressListFormat verifies that the given string is a valid list of RFC 5322 addresses.

Types

type Address 

type Address struct {
	// Name is an optional name of the address i.e. "John Doe".
	Name string
	// Address is the proper email address.
	Address string
}

Address represents a single mail address with an optional name. It is used to parse the input address. An address is in the form of '"John Doe" <john@doe.com>' is represented ass Address{Name: "John Doe", Address: "john@doe.com"}.

func ParseAddress 

func ParseAddress(address string) (Address, error)

ParseAddress parses the given string as an address.

func ParseAddressList 

func ParseAddressList(addressList string) ([]Address, error)

ParseAddressList parses the given string as a list of addresses.

func (Address) IsZero 

func (a Address) IsZero() bool

IsZero checks if the address has zero value.

func (Address) String 

func (a Address) String() string

type AddressParser 

type AddressParser struct {
	WordDecoder *mime.WordDecoder
}

An AddressParser is an RFC 5322 address parser.

func (AddressParser) Parse 

func (p AddressParser) Parse(address string) (Address, error)

Parse parses a single RFC 5322 address of the form "Gogh Fir <gf@example.com>" or "foo@example.com".

func (AddressParser) ParseList 

func (p AddressParser) ParseList(addressList string) ([]Address, error)

ParseList parses the given string as a list of addresses.

func (AddressParser) VerifyFormat 

func (p AddressParser) VerifyFormat(address string) error

VerifyFormat verifies that the given string is a valid RFC 5322 address.

func (AddressParser) VerifyListFormat 

func (p AddressParser) VerifyListFormat(addressList string) error

VerifyListFormat verifies that the given string is a valid list of RFC 5322 addresses.

type AddressValidator 

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

AddressValidator is an email address validator implementation.

type Attachment 

type Attachment struct {
	// AttachmentID is the identifier of the attachment.
	AttachmentID string
	// ContentID is the attachment content identifier.
	// This value is optional, in case it is not set, a <filename> will be used.
	ContentID string
	// Filename is the attachment filename.
	File AttachmentFile
	// Filename is the attachment filename.
	Filename string
	// ContentType is the attachment content type.
	ContentType string
	// Inline determines if the attachment should be displayed inline.
	Inline bool
}

Attachment is an interface used for email attachments.

type AttachmentFile 

type AttachmentFile interface {
	io.Reader
	ContentType() string
	ModTime() time.Time
	Size() int64
	Close() error
}

AttachmentFile is an interface used for email attachment files. This value might be taken from *os.File, *blob.Reader, etc.

type BounceRecord 

type BounceRecord struct {
	// Recipients is a list of the bounced recipients.
	Recipients []BouncedRecipient
	// BounceType is the type of the bounce.
	BounceType BounceType
	// Timestamp is the time when the bounce occurred.
	Timestamp time.Time
}

BounceRecord represents a bounce record.

type BounceType 

type BounceType int

BounceType determines the type of the message bounce. It is used to determine whether the bounce is permanent or transient.

func (BounceType) String 

func (bt BounceType) String() string

String returns the string representation of the bounce type.

type BouncedRecipient 

type BouncedRecipient struct {
	// Email is the email address of the recipient.
	Email string
	// Status is the status of the bounce.
	Status string
	// DiagnosticCode is the diagnostic code of the bounce.
	DiagnosticCode string
}

BouncedRecipient represents a bounced recipient.

type ComposeMsgFn 

type ComposeMsgFn interface {
	// contains filtered or unexported methods
}

ComposeMsgFn is a message composer function.

func Attach 

func Attach(att AttachmentFile, filename string) ComposeMsgFn

Attach creates an attachment.

func AttachFile 

func AttachFile(path string) ComposeMsgFn

func Attachments 

func Attachments(attachments ...*Attachment) ComposeMsgFn

Attachments sets the email attachments.

func Bcc 

func Bcc(bcc ...string) ComposeMsgFn

Bcc sets the blind carbon copy email recipients.

func Cc 

func Cc(cc ...string) ComposeMsgFn

Cc sets the carbon copy email recipients.

func Date 

func Date(date time.Time) ComposeMsgFn

Date sets the email header Date.

func EmbedAttachment 

func EmbedAttachment(att AttachmentFile, filename string) ComposeMsgFn

EmbedAttachment creates an attachment that should be displayed inline.

func From 

func From(from string) ComposeMsgFn

From sets the email sender.

func HTMLBody 

func HTMLBody(content string) ComposeMsgFn

HTMLBody sets the HTML content of an email message.

func MessageID 

func MessageID(id string) ComposeMsgFn

MessageID sets the loggable ID of the message.

func ReplyTo 

func ReplyTo(replyTo string) ComposeMsgFn

ReplyTo sets the email reply to addresses.

func Subject 

func Subject(subject string) ComposeMsgFn

Subject sets the email subject.

func TextBody 

func TextBody(content string) ComposeMsgFn

TextBody sets the text content of an email message.

func To 

func To(to ...string) ComposeMsgFn

To sets the email recipients.

type ComposeTemplatedMsgFn 

type ComposeTemplatedMsgFn interface {
	// contains filtered or unexported methods
}

ComposeTemplatedMsgFn is a function that composes a message from the given template.

func Template 

func Template(name, version string, data map[string]any) ComposeTemplatedMsgFn

Template composes a TemplatedMessage with given template name, version and data.

func TemplateData 

func TemplateData(data map[string]any) ComposeTemplatedMsgFn

TemplateData sets the template data.

func TemplateName 

func TemplateName(name string) ComposeTemplatedMsgFn

TemplateName sets the template name.

func TemplateVersion 

func TemplateVersion(version string) ComposeTemplatedMsgFn

TemplateVersion sets the template version.

type DeliveryEvent 

type DeliveryEvent struct {
	// Type represents the type of the event.
	Type DeliveryEventType

	// Bounce contains the bounce information.
	// This field is only set if Type is DeliveryEventTypeBounce or DeliveryEventTypeTransientBounce.
	Bounce BounceRecord

	// Timestamp is the time when the event occurred.
	Timestamp time.Time

	// MessageID is the ID of the message associated with the event.
	MessageID string
}

DeliveryEvent represents an email delivery event.

type DeliveryEventType 

type DeliveryEventType int

DeliveryEventType represents the type of an email delivery event.

func (DeliveryEventType) String 

func (d DeliveryEventType) String() string

type DeliverySubscription 

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

DeliverySubscription represents a subscription to bounce events.

func (*DeliverySubscription) As 

func (s *DeliverySubscription) As(i interface{}) bool

As converts i to driver-specific types. See https://gocloud.dev/concepts/as/ for background information, the "As" examples in this package for examples, and the driver package documentation for the specific types supported for that driver.

func (*DeliverySubscription) ErrorAs 

func (s *DeliverySubscription) ErrorAs(err error, i interface{}) bool

ErrorAs converts err to driver-specific types. ErrorAs panics if i is nil or not a pointer. ErrorAs returns false if err == nil. See Topic.As for more details.

func (*DeliverySubscription) Receive 

func (s *DeliverySubscription) Receive(ctx context.Context) (*DeliveryEvent, error)

Receive receives and returns the next message from the subscription's queue, blocking and polling if none are available. It can be called concurrently from multiple goroutines.

Receive retries retryable errors from the underlying driver forever. Therefore, if Receive returns an error, either: 1. It is a non-retryable error from the underlying driver, either from 

an attempt to fetch more messages or from an attempt to ack messages.
Operator intervention may be required (e.g., invalid resource, quota
error, etc.). Receive will return the same error from then on, so the
application should log the error and either recreate the Subscription,
or exit.

2. The provided ctx is Done. Error() on the returned error will include both 

the ctx error and the underlying driver error, and ErrorAs on it
can access the underlying driver error type if needed. Receive may
be called again with a fresh ctx.

Callers can distinguish between the two by checking if the ctx they passed is Done, or via xerrors.Is(err, context.DeadlineExceeded or context.Canceled) on the returned error.

func (*DeliverySubscription) Shutdown 

func (s *DeliverySubscription) Shutdown(ctx context.Context) (err error)

Shutdown flushes pending ack sends and disconnects the Subscription.

type Message 

type Message struct {

	// MessageID is the loggable ID of the message.
	MessageID string

	// From is the email sender.
	From string

	// To is a list of the email recipients.
	To []string

	// Cc is a list of the carbon copy email recipients.
	Cc []string

	// Bcc is a list of the blind carbon copy email recipients.
	Bcc []string

	// HtmlBody is the html body of an email message.
	HtmlBody string

	// TextBody is the text body of an email message.
	TextBody string

	// Subject is the email subject.
	Subject string

	// Attachments is a list of the email attachments.
	Attachments []*Attachment

	// ReplyTo is an email address that should be used to reply to the message.
	ReplyTo string

	// Date is a date when the email was sent.
	Date time.Time

	// BeforeSend is a callback used when sending a message. It will always be
	// set to nil for received messages.
	//
	// The callback will be called exactly once, before the message is sent.
	//
	// asFunc converts its argument to driver-specific types.
	// See https://gocloud.dev/concepts/as/ for background information.
	BeforeSend func(asFunc func(interface{}) bool) error

	// AfterSend is a callback used when sending a message. It will always be
	// set to nil for received messages.
	//
	// The callback will be called at most once, after the message is sent.
	// If Send returns an error, AfterSend will not be called.
	//
	// asFunc converts its argument to driver-specific types.
	// See https://gocloud.dev/concepts/as/ for background information.
	AfterSend func(asFunc func(interface{}) bool) error
	// contains filtered or unexported fields
}

Message is a message from the emails package.

func ComposeMessage 

func ComposeMessage(composers ...ComposeMsgFn) (*Message, error)

ComposeMessage composes a message.

type Sender 

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

Sender represents an implementation of the email message s.

func OpenSender 

func OpenSender(ctx context.Context, urlstr string) (*Sender, error)

OpenSender opens the Sender identified by the URL given. See the SenderURLOpener documentation for more details.

func (*Sender) As 

func (p *Sender) As(i any) bool

As converts i to driver-specific types.

func (*Sender) ErrorAs 

func (p *Sender) ErrorAs(err error, i any) bool

ErrorAs converts err to driver-specific types. It panics if i is nil or not a pointer. It returns false if err == nil.

func (*Sender) Send 

func (p *Sender) Send(ctx context.Context, m *Message) error

Send uses the mailing provider to send the input message.

func (*Sender) Shutdown 

func (p *Sender) Shutdown(ctx context.Context) (err error)

Shutdown flushes pending messages and disconnects the Sender. It only returns after all pending messages have been sent.

type SenderURLOpener 

type SenderURLOpener interface {
	OpenSenderURL(ctx context.Context, u *url.URL) (*Sender, error)
}

SenderURLOpener represents types that can open Sender based on a URL.

type TemplatedMessage 

type TemplatedMessage struct {
	// MessageID is the loggable ID of the message.
	MessageID string

	// From is the email sender.
	From string

	// To is a list of the email recipients.
	To []string

	// Cc is a list of the carbon copy email recipients.
	Cc []string

	// Bcc is a list of the blind carbon copy email recipients.
	Bcc []string

	// HtmlBody is the html body of an email message.
	HtmlBody string

	// TextBody is the text body of an email message.
	TextBody string

	// Subject is the email subject.
	Subject string

	// Attachments is a list of the email attachments.
	Attachments []*Attachment

	// Date the email date header.
	Date time.Time

	// ReplyTo is an email address that should be used to reply to the message.
	ReplyTo string

	// TemplateName is the unique template name.
	TemplateName string

	// TemplateData is a map of the substitution data for the template.
	TemplateData map[string]any

	// TemplateVersion is the version of the template to be used.
	TemplateVersion string

	// BeforeSend is a callback used when sending a message. It will always be
	// set to nil for received messages.
	//
	// The callback will be called exactly once, before the message is sent.
	//
	// asFunc converts its argument to driver-specific types.
	// See https://gocloud.dev/concepts/as/ for background information.
	BeforeSend func(asFunc func(any) bool) error

	// AfterSend is a callback used when sending a message. It will always be
	// set to nil for received messages.
	//
	// The callback will be called at most once, after the message is sent.
	// If Send returns an error, AfterSend will not be called.
	//
	// asFunc converts its argument to driver-specific types.
	// See https://gocloud.dev/concepts/as/ for background information.
	AfterSend func(asFunc func(any) bool) error
}

TemplatedMessage is a message used for email templates.

func ComposeTemplatedMessage 

func ComposeTemplatedMessage(composers ...ComposeTemplatedMsgFn) (*TemplatedMessage, error)

ComposeTemplatedMessage composes a message from the given template.

type TemplatedSender 

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

TemplatedSender represents an implementation of the email template message sender.

func OpenTemplatedSender 

func OpenTemplatedSender(ctx context.Context, urlstr string) (*TemplatedSender, error)

OpenTemplatedSender opens the TemplatedSender identified by the URL given. See the TemplatedSenderURLOpener documentation for more details.

func (*TemplatedSender) As 

func (p *TemplatedSender) As(i any) bool

As converts i to driver-specific types.

func (*TemplatedSender) ErrorAs 

func (p *TemplatedSender) ErrorAs(err error, i any) bool

ErrorAs converts err to driver-specific types. It panics if i is nil or not a pointer. It returns false if err == nil.

func (*TemplatedSender) Send 

func (p *TemplatedSender) Send(ctx context.Context, m *TemplatedMessage) error

Send uses the mailing provider to send the input message.

func (*TemplatedSender) Shutdown 

func (p *TemplatedSender) Shutdown(ctx context.Context) (err error)

Shutdown flushes pending messages and disconnects the TemplatedSender. It only returns after all pending messages have been sent.

type TemplatedSenderURLOpener 

type TemplatedSenderURLOpener interface {
	OpenTemplatedSenderURL(ctx context.Context, u *url.URL) (*TemplatedSender, error)
}

TemplatedSenderURLOpener represents types that can open TemplatedSender based on a URL.

type URLMux 

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

URLMux is URL opener multiplexer. It matches the scheme of the URLs against a set of registered schemes and calls the opener that matches the URL's scheme. See https://gocloud.dev/concepts/urls/ for more information.

func DefaultURLMux 

func DefaultURLMux() *URLMux

DefaultURLMux returns the URLMux used by OpenSender.

Driver packages can use this to register their SenderURLOpener on the mux.

func (*URLMux) OpenSender 

func (mux *URLMux) OpenSender(ctx context.Context, urlstr string) (*Sender, error)

OpenSender calls OpenSenderURL with the URL parsed from urlstr. OpenSender is safe to call from multiple goroutines.

func (*URLMux) OpenTemplatedSender 

func (mux *URLMux) OpenTemplatedSender(ctx context.Context, urlstr string) (*TemplatedSender, error)

OpenTemplatedSender calls OpenTemplateSenderURL with the URL parsed from urlstr. OpenTemplatedSender is safe to call from multiple goroutines.

func (*URLMux) RegisterSender 

func (mux *URLMux) RegisterSender(scheme string, opener SenderURLOpener)

RegisterSender registers the opener with the given scheme. If an opener already exists for the scheme, RegisterSender panics.

func (*URLMux) RegisterTemplatedSender 

func (mux *URLMux) RegisterTemplatedSender(scheme string, opener TemplatedSenderURLOpener)

RegisterTemplatedSender registers the opener with the given scheme. If an opener already exists for the scheme, RegisterTemplatedSender panics.

func (*URLMux) SenderSchemes 

func (mux *URLMux) SenderSchemes() []string

SenderSchemes returns a sorted slice of the registered Sender schemes.

func (*URLMux) TemplatedSenderSchemes 

func (mux *URLMux) TemplatedSenderSchemes() []string

TemplatedSenderSchemes returns a sorted slice of the registered TemplatedSender schemes.

func (*URLMux) ValidSenderScheme 

func (mux *URLMux) ValidSenderScheme(scheme string) bool

ValidSenderScheme returns true iff scheme has been registered for MailProviders.

func (*URLMux) ValidTemplatedSenderScheme 

func (mux *URLMux) ValidTemplatedSenderScheme(scheme string) bool

ValidTemplatedSenderScheme returns true iff scheme has been registered for MailProviders.

Source Files

View all Source files

Directories

Path Synopsis
Package batcher supports batching of items.
 Package batcher supports batching of items.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.