driver

Documentation

Index

• type Address
• type AddressValidationResult
• type AddressValidator
• type Attachment
  • func (a *Attachment) Close() error
  • func (a *Attachment) Read(p []byte) (n int, err error)
  • func (a *Attachment) WriteTo(w io.Writer) (n int64, err error)
• type AttachmentFile
• type BounceNotification
• type BounceRecord
• type BounceType
  • func (bt BounceType) String() string
• type BouncedRecipient
• type DeliveryEvent
• type DeliveryEventType
• type DeliverySubscription
• type Message
• type Sender
• type TemplatedMessage
• type TemplatedSender

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
	// IsFormatValid defines if the format of the address is valid.
	// This field is automatically set to true as a result of ParseAddress or ParseAddressList.
	IsFormatValid bool
}

Address represents an email address.

type AddressValidationResult

type AddressValidationResult struct {
}

type AddressValidator

type AddressValidator interface {
	// ValidateAddressBatch lets the provider validate the input addresses in a batch.
	ValidateAddressBatch(ctx context.Context, batch []*Address) ([]*AddressValidationResult, error)

	// Close closes the provider and releases all resources.
	// This could be a noop for some providers.
	// Once closed is called, there will be no method calls to the AddressValidator other than As, ErrorAs, and ErrorCode.
	Close() error

	// ErrorAs allows providers to expose provider-specific types for returned errors.
	ErrorAs(err error, i interface{}) bool

	// ErrorCode should return a code that describes the error, which was returned by
	ErrorCode(error) gcerrors.ErrorCode

	// As allows providers to expose provider-specific types.
	As(i interface{}) bool
}

AddressValidator is an interface that represents an implementation of the email address validator.

type Attachment

type Attachment struct {
	// 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.

func (*Attachment) Close

func (a *Attachment) Close() error

Close closes the attachment.

func (*Attachment) Read

func (a *Attachment) Read(p []byte) (n int, err error)

Read reads up to len(p) bytes into p.

func (*Attachment) WriteTo

func (a *Attachment) WriteTo(w io.Writer) (n int64, err error)

WriteTo writes the attachment to w.

type AttachmentFile

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

AttachmentFile is an interface used for email attachment files.

type BounceNotification

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

	// Details is the bounce details.
	Details string

	// Type is the bounce type.
	Type BounceType
}

BounceNotification is a bounce notification.

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.

const (

	// BounceTypeTransient indicates a transient bounce.
	BounceTypeTransient BounceType
	// BounceTypePermanent indicates a permanent bounce.
	BounceTypePermanent
)

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 DeliveryEvent

type DeliveryEvent struct {
	// Type describes 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 a delivery event.

type DeliveryEventType

type DeliveryEventType int

DeliveryEventType represents the type of a delivery event.

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 = 0
	// 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 = 1
	// DeliveryEventTypeDelayed indicates that the message was delayed.
	DeliveryEventTypeDelayed DeliveryEventType = 2
	// DeliveryEventTypeRenderingFailure indicates that the message could not be rendered.
	// This event is sent when the message could not be rendered.
	DeliveryEventTypeRenderingFailure DeliveryEventType = 3
	// DeliveryEventTypeSend indicates that the message was send to the email service and is waiting for delivery.
	DeliveryEventTypeSend DeliveryEventType = 4
	// 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 = 5
)

type DeliverySubscription

type DeliverySubscription interface {
	// ReceiveBounceBatch lets the provider receive a bounce event.
	// The method blocks until a bounce event is received or the context is canceled.
	ReceiveBatch(ctx context.Context, maxMessages int) ([]*DeliveryEvent, error)

	// As allows providers to expose provider-specific types.
	As(i interface{}) bool

	// ErrorAs allows providers to expose provider-specific types for returned errors.
	ErrorAs(err error, i interface{}) bool

	// ErrorCode should return a code that describes the error, which was returned by
	ErrorCode(error) codes.Code

	// IsRetryable should return true if the error is retryable.
	IsRetryable(err error) bool

	// Close closes the subscription.
	Close() error
}

DeliverySubscription represents a subscription to bounce events. It is used to receive bounce events.

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

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

	// ReplyTo is an email address that should be used to reply to the message.
	ReplyTo 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
}

Message is a message.

type Sender

type Sender interface {
	// SendBatch lets the provider send the input message in a batch.
	SendBatch(ctx context.Context, msg []*Message) error

	// ErrorAs allows providers to expose provider-specific types for returned errors.
	ErrorAs(err error, i interface{}) bool

	// ErrorCode should return a code that describes the error, which was returned by
	ErrorCode(error) codes.Code

	// As allows providers to expose provider-specific types.
	As(i interface{}) bool

	// Close closes the provider and releases all resources.
	// This could be a noop for some providers.
	// Once closed is called, there will be no method calls to the Sender other than As, ErrorAs, and ErrorCode.
	Close() error
}

Sender is an interface that represents a provider.

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 ID of the template.
	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(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
}

TemplatedMessage is a message used for email templates.

type TemplatedSender

type TemplatedSender interface {
	// SendTemplatedMessageBatch lets the provider send the input message in a batch.
	SendTemplatedMessageBatch(ctx context.Context, msg []*TemplatedMessage) error

	// ErrorAs allows providers to expose provider-specific types for returned errors.
	ErrorAs(err error, i any) bool

	// ErrorCode should return a code that describes the error, which was returned by
	ErrorCode(error) codes.Code

	// As allows providers to expose provider-specific types.
	As(i any) bool

	// Close closes the provider and releases all resources.
	// This could be a noop for some providers.
	// Once closed is called, there will be no method calls to the Sender other than As, ErrorAs, and ErrorCode.
	Close() error
}

TemplatedSender is an interface that represents a provider.