providers

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

Package providers defines the pluggable sending-provider contract. Every adapter lives in internal/providers/<name> and implements Provider plus any optional interfaces it supports; core code only talks to these interfaces (never imports an adapter) and finds adapters through the registry.

Every adapter must pass the shared contract-test suite in internal/providers/contracttest.

Index

Constants

View Source
const RuntimePrefix = "community:"

RuntimePrefix starts the registry key of every adapter installed while ReputeCast runs: community adapters are "community:<id>".

Variables

View Source
var ErrBadSignature = errors.New("webhook signature verification failed")

ErrBadSignature is returned by ParseWebhook for unverifiable payloads.

View Source
var ErrNotSupported = errors.New("not supported by this provider")

ErrNotSupported is returned by optional operations an account or plan can't do.

View Source
var ErrUnauthorized = errors.New("provider rejected the credentials")

ErrUnauthorized means the provider rejected the credentials (HTTP 401/403, SMTP 535). Health checks report it as "Down · auth failed" and ask for new credentials instead of retrying.

View Source
var ErrUnavailable = errors.New("provider unavailable")

ErrUnavailable means the provider can't be reached at all (outage).

Functions

func CommunityKey

func CommunityKey(name string) string

CommunityKey is the registry key of an installed community adapter that is known by its name (HTTP mappings): RuntimePrefix and the name in lowercase letters and digits joined by dashes, so it can appear in a webhook URL ("Example ESP" → "community:example-esp"). Remote adapters use their manifest id instead.

func ErrorIn

func ErrorIn(err error, l i18n.Lang) string

ErrorIn writes an error for a reader: err.Error(), with the message of a CallError the adapter worded itself in the reader's language.

func InstalledKey

func InstalledKey(kind, name string, manifest []byte) string

InstalledKey is the registry key of an installed community adapter, from its installed_adapters row: RuntimePrefix and the manifest's id for kind "remote", CommunityKey(name) for the other kinds. It is "" for a remote adapter whose manifest has no id; such an adapter is never registered.

func MessageIn

func MessageIn(err error, l i18n.Lang) string

MessageIn is the message of a failed call for a reader: a CallError's message (in the reader's language when the adapter kept its message), else err.Error().

func Register

func Register(d Descriptor)

Register adds an adapter to the catalog. Adapters call it from init.

func Registered

func Registered(adapter string) bool

Registered reports whether an adapter is in the registry (and therefore connectable from this build).

func RuntimeAdapters

func RuntimeAdapters() []string

RuntimeAdapters returns the keys of the runtime adapters, sorted.

func SetRuntime

func SetRuntime(owner any, ds []Descriptor) error

SetRuntime makes ds the runtime adapters registered by owner, replacing its previous set: community adapters come and go while ReputeCast runs, so they can't register from init. Keys must start with RuntimePrefix, so a runtime adapter can never take the place of a built-in one. owner must be comparable (a pointer).

func SignatureVerified

func SignatureVerified(ctx context.Context) bool

SignatureVerified reports whether ctx carries WithSignatureVerified.

func TextIn

func TextIn(english string, t i18n.Text, l i18n.Lang) string

TextIn returns a text in the reader's language: the message t when it exists, else english. English readers get english exactly as it was written, so API clients and agents read what they always did.

func WithSignatureVerified

func WithSignatureVerified(ctx context.Context) context.Context

WithSignatureVerified marks ctx for a payload whose signature was already verified at ingest, so ParseWebhook can skip verification (and time-window checks) when the normalization job parses it later.

Types

type AccessTemplate

type AccessTemplate struct {
	Format string // "cloudformation"
	// Body is the template itself, for download or review.
	Body string
	// LaunchURL opens the provider's console with the template ready to run.
	LaunchURL string
	// Policy is the least-privilege policy the template grants, for display.
	Policy string
	// Principal is the identity of this server that may assume the role,
	// when it could be detected ("" otherwise: the person fills it in).
	Principal string
	// RoleName is the role the stack creates; its ARN is the stack output.
	RoleName string
}

AccessTemplate grants ReputeCast access through the provider's own console, without long-lived keys (SES: a CloudFormation stack creating an IAM role ReputeCast assumes with an external id).

type AccessTemplateInput

type AccessTemplateInput struct {
	Region     string
	ExternalID string
	// TemplateURL is where the published template lives; the launch link
	// points the provider's console at it.
	TemplateURL string
}

AccessTemplateInput parameterizes an access template.

type AccessTemplater

type AccessTemplater interface {
	AccessTemplate(ctx context.Context, in AccessTemplateInput) (AccessTemplate, error)
}

AccessTemplater is implemented by adapters whose access can be granted with a template in the provider's console.

type AccountIdentifier

type AccountIdentifier interface {
	AccountID(ctx context.Context) (string, error)
}

AccountIdentifier reports which provider account the credentials belong to (the AWS account id), so people can tell connections apart.

type Attachment

type Attachment struct {
	Filename    string
	ContentType string
	ContentID   string
	Content     []byte
}

Attachment is a file sent with a message (a PDF invoice). ContentID makes it an inline part that the HTML references as cid:<ContentID>.

type BounceMailboxTester

type BounceMailboxTester interface {
	TestBounceMailbox(ctx context.Context) (MailboxReport, error)
}

BounceMailboxTester is implemented by adapters that read bounces and complaints from a mailbox (SMTP). The test never marks or deletes mail.

type BroadcastStreamCreator

type BroadcastStreamCreator interface {
	CreateBroadcastStream(ctx context.Context, name string) (streamID string, err error)
}

BroadcastStreamCreator is implemented by providers whose terms allow bulk mail only on a dedicated stream (Postmark Broadcast message streams).

type BulkPolicy

type BulkPolicy string

BulkPolicy says whether a provider's terms allow bulk marketing mail.

const (
	BulkAllowed          BulkPolicy = "allowed"
	BulkBroadcastStreams BulkPolicy = "broadcast_streams_only" // e.g. Postmark: only on Broadcast message streams
	BulkForbidden        BulkPolicy = "forbidden"
	BulkYourPolicy       BulkPolicy = "your_policy" // self-hosted (Postal, SMTP)
)

Bulk policies shown as capability badges and checked by Send Readiness.

type CallError

type CallError struct {
	Op        string // provider operation: "SendEmail", "POST /email/batch", "GET /server"
	Status    int    // HTTP status or SMTP reply code; 0 for network errors
	Code      string // provider error code: "ServiceUnavailable", "ErrorCode 10"
	Message   string
	Temporary bool
	Throttled bool
	Auth      bool
	Cause     error
	// Text is the message Message comes from, when the adapter wrote the
	// sentence itself (a connection test's finding); a provider's own answer
	// has none.
	Text i18n.Text
}

CallError describes a failed API call for the event log and health ("503 ServiceUnavailable · SendEmail"). It unwraps to ErrUnavailable for outages and to ErrUnauthorized for rejected credentials.

func (*CallError) Error

func (e *CallError) Error() string

func (*CallError) Unwrap

func (e *CallError) Unwrap() []error

Unwrap lets errors.Is match ErrUnavailable / ErrUnauthorized and the cause.

type Capabilities

type Capabilities struct {
	Bulk            BulkPolicy `json:"bulk"`
	Webhooks        string     `json:"webhooks"`  // "SNS", "Registered", "Bounce mailbox", ""
	DomainAPI       string     `json:"domainApi"` // "full", "dkim_only", ""
	SuppressionSync bool       `json:"suppressionSync"`
	BatchSize       int        `json:"batchSize"` // messages per API call; 1 = no batching
	// DedicatedIPs is the dedicated-IP option as badges show it ("optional,
	// $24.95 per IP per month"); "" when the provider offers none.
	DedicatedIPs   string `json:"dedicatedIps"`
	Sandbox        string `json:"sandbox"` // "detection", "test token", "mode", ""
	QuotaDiscovery bool   `json:"quotaDiscovery"`
	// RateDiscovery is true when the API also reports the maximum send rate
	// (SES: "Quota & rate discovery"; Postmark only reports quota).
	RateDiscovery bool   `json:"rateDiscovery"`
	Pricing       string `json:"pricing"` // human summary: "$0.10 per 1,000"
	// RewritesLinks / AddsOpenPixel are true when provider-side tracking is
	// on by default and should be turned off to avoid double tracking.
	RewritesLinks bool `json:"rewritesLinks"`
	AddsOpenPixel bool `json:"addsOpenPixel"`
	// RemovesWebhook is true when the adapter removes the webhook it
	// registered once the provider is removed (WebhookUnregistrar).
	RemovesWebhook bool `json:"removesWebhook"`
	// PricingText and DedicatedIPsText are the messages Pricing and
	// DedicatedIPs come from (text.go). They are kept with the capability
	// snapshot of a connected provider, so it reads in each reader's
	// language later.
	PricingText      i18n.Text `json:"pricingText,omitzero"`
	DedicatedIPsText i18n.Text `json:"dedicatedIpsText,omitzero"`
}

Capabilities are the badges shown on each provider (spec 5.2).

func (Capabilities) In

In returns the capabilities with Pricing and DedicatedIPs in the reader's language. Use it for display only: the English values are data too.

func (Capabilities) WithMessages

func (c Capabilities) WithMessages(cat *i18n.Catalog) Capabilities

WithMessages fills Pricing and DedicatedIPs from the adapter's catalog (keys pricing and dedicatedIps), as Descriptor.WithMessages does.

type Config

type Config struct {
	ProviderID  uuid.UUID
	WorkspaceID uuid.UUID
	Settings    json.RawMessage // providers.config column
	Credentials json.RawMessage // decrypted credentials_enc
	// WebhookSecret signs or authenticates incoming webhooks where the
	// provider supports a shared secret.
	WebhookSecret string
	HTTPClient    *http.Client
	// Dialer opens raw connections (SMTP, IMAP, POP3) through the same
	// address guard as HTTPClient; nil dials directly.
	Dialer *net.Dialer
}

Config is the non-secret connection settings and the decrypted credentials of one connected provider.

type ConnectionReport

type ConnectionReport struct {
	// Summary is one line for a status badge: "STARTTLS, TLS 1.3 · AUTH PLAIN accepted".
	Summary string
	// Transcript is the protocol exchange without secrets, one entry per
	// line: "220 smtp.mta.acme.io ESMTP Postal", "EHLO reputecast.acme.io"…
	Transcript []string
	// Auth is the login method the server accepted ("plain", "login"), so
	// sends can use it rather than discover it again; empty without login.
	Auth string
	// SummaryText is the message Summary comes from.
	SummaryText i18n.Text
}

ConnectionReport is the detailed result of a connection test.

type ConnectionTester

type ConnectionTester interface {
	TestConnection(ctx context.Context) (ConnectionReport, error)
}

ConnectionTester is implemented by adapters that can describe a connection test in detail (SMTP: greeting, extensions, TLS version, authentication).

type DNSRecord

type DNSRecord struct {
	Purpose string `json:"purpose"` // dkim, spf, return_path, dmarc, verification
	Type    string `json:"type"`    // CNAME, TXT, MX
	Name    string `json:"name"`
	Value   string `json:"value"`
	// Status is filled by DNS checks: pending, verified, wrong_value, missing.
	Status string `json:"status,omitempty"`
}

DNSRecord is one record a provider requires for a sending domain.

type DeclaredText

type DeclaredText struct {
	// What names it by its well-known key ("field.api_key.label").
	What    string
	English string
	Text    i18n.Text
}

DeclaredText is one text of a descriptor (Texts).

type Descriptor

type Descriptor struct {
	Adapter      string       `json:"adapter"`
	Name         string       `json:"name"`
	Kind         string       `json:"kind"` // api, smtp, self_hosted, community
	Capabilities Capabilities `json:"capabilities"`
	Version      string       `json:"version"`
	Maintainer   string       `json:"maintainer"`
	// Fields lists what the connection step asks for.
	Fields []Field `json:"fields"`
	// Terms summarizes what the provider's terms allow, per account variant
	// (Postmark: Transactional and Broadcast streams). Shown on the routing
	// screen and used by Send Readiness.
	Terms []Terms `json:"terms,omitempty"`
	// Events, DomainSetup and SuppressionMode describe the adapter on the
	// Adapters tab ("SNS webhooks", "API", "Two-way").
	Events          string `json:"events,omitempty"`
	DomainSetup     string `json:"domainSetup,omitempty"`
	SuppressionMode string `json:"suppressionMode,omitempty"`
	// EventsText, DomainSetupText and SuppressionModeText are the messages
	// the three words come from (text.go).
	EventsText          i18n.Text `json:"-"`
	DomainSetupText     i18n.Text `json:"-"`
	SuppressionModeText i18n.Text `json:"-"`
	// Messages is the adapter's own catalog, which its texts come from
	// (WithMessages). Built-in adapters have one; community adapters write
	// English only.
	Messages *i18n.Catalog `json:"-"`
	New      func(Config) (Provider, error)
}

Descriptor describes an adapter in the catalog (setup wizard, Adapters tab).

func Catalog

func Catalog() []Descriptor

Catalog returns every registered adapter.

func Lookup

func Lookup(adapter string) (Descriptor, bool)

Lookup returns a registered adapter.

func (Descriptor) In

func (d Descriptor) In(l i18n.Lang) Descriptor

In returns a copy of the descriptor with every text people read in the reader's language. Use it for display only: code that decides something from a descriptor's words (SuppressionMode "Pull only") reads the registry's English one.

func (Descriptor) Texts

func (d Descriptor) Texts() []DeclaredText

Texts lists every text people read in a descriptor with its message, for checks (the contract suite): what the text is, its English and its Text.

func (Descriptor) WithMessages

func (d Descriptor) WithMessages(c *i18n.Catalog) Descriptor

WithMessages names the adapter's catalog and fills the descriptor's texts (and its Capabilities' Pricing and DedicatedIPs) from the catalog's well-known keys. Adapters call it from their Descriptor function.

type DomainManager

type DomainManager interface {
	AddDomain(ctx context.Context, domain string) ([]DNSRecord, error)
	DomainStatus(ctx context.Context, domain string) ([]DNSRecord, error)
}

DomainManager is implemented by providers that set up domains over their API.

type Event

type Event struct {
	Type              EventType
	ProviderMessageID string
	MessageID         *uuid.UUID // when the provider echoes our tag/header
	Recipient         string
	OccurredAt        time.Time
	OriginalType      string // "Bounce/Permanent/General", "HardBounce"
	OriginalCode      string // "550 5.1.1"
	Diagnostic        string
	// BounceClass is the shared taxonomy: mailbox_unknown, mailbox_full,
	// domain_invalid, policy_block, spam_block, reputation, temporary, other.
	BounceClass string
	URL         string // clicks
	UserAgent   string
	Raw         json.RawMessage
}

Event is a provider event mapped to ReputeCast's model.

type EventBackfiller

type EventBackfiller interface {
	Backfill(ctx context.Context, providerMessageIDs []string) ([]Event, error)
}

EventBackfiller fetches the current delivery status of messages from the provider's API, for when webhooks went silent.

type EventType

type EventType string

EventType is a normalized delivery or engagement event.

const (
	EventDelivered   EventType = "delivered"
	EventDeferred    EventType = "deferred"
	EventHardBounce  EventType = "hard_bounce"
	EventSoftBounce  EventType = "soft_bounce"
	EventComplaint   EventType = "complaint"
	EventRejected    EventType = "rejected"
	EventOpen        EventType = "open"
	EventClick       EventType = "click"
	EventUnsubscribe EventType = "unsubscribe"
)

Normalized events; the provider's original type and code are kept.

type ExtrasSender

type ExtrasSender interface {
	SendWithExtras(ctx context.Context, msgs []Message, extras []MessageExtras) ([]SendResult, error)
}

ExtrasSender is implemented by adapters that can send copies and attachments (an optional interface: core code type-asserts before using it, and a message with extras only goes to a provider that has it). extras[i] belongs to msgs[i].

type Field

type Field struct {
	Key      string   `json:"key"`
	Label    string   `json:"label"`
	Secret   bool     `json:"secret"`
	Required bool     `json:"required"`
	Options  []string `json:"options,omitempty"`
	Help     string   `json:"help,omitempty"`
	// LabelText and HelpText are the messages Label and Help come from.
	LabelText i18n.Text `json:"-"`
	HelpText  i18n.Text `json:"-"`
}

Field is one input of a provider's connection form.

func (Field) In

func (f Field) In(l i18n.Lang) Field

In returns the field with its label and hint in the reader's language.

type MailboxReport

type MailboxReport struct {
	Protocol string // IMAP, POP3
	Folder   string
	// Messages waiting to be processed, and how many of them look like
	// bounce (DSN) or complaint (ARF) reports.
	Messages int
	Reports  int
}

MailboxReport describes the bounce mailbox an adapter reads.

type Message

type Message struct {
	ID      uuid.UUID // ReputeCast message id; also used in Message-ID and tracking
	Stream  Stream
	From    mail.Address
	ReplyTo *mail.Address
	To      mail.Address
	Subject string
	HTML    string
	Text    string
	// Headers include List-Unsubscribe, List-Unsubscribe-Post (RFC 8058),
	// Feedback-ID and X-ReputeCast-Message.
	Headers map[string]string
	// Tags are passed through where the provider supports them (SES tags,
	// Postmark metadata) and come back on events.
	Tags map[string]string
}

Message is one email to one recipient, already rendered and personalized.

type MessageExtras

type MessageExtras struct {
	Cc          []mail.Address
	Bcc         []mail.Address
	Attachments []Attachment
}

MessageExtras is what a transactional message can carry beyond the base Message: copies and attachments.

func (MessageExtras) Empty

func (e MessageExtras) Empty() bool

Empty reports whether the extras add nothing.

type ProductionAccessRequest

type ProductionAccessRequest struct {
	Region      string
	WebsiteURL  string
	MailType    string // "marketing" or "transactional"
	UseCase     string
	Language    string // "en" or "ja"
	DailyVolume int64
	// ContactEmails receive the provider's answer.
	ContactEmails []string
}

ProductionAccessRequest asks a provider to take a region out of its sandbox (SES PutAccountDetails).

type ProductionAccessRequester

type ProductionAccessRequester interface {
	RequestProductionAccess(ctx context.Context, r ProductionAccessRequest) error
}

ProductionAccessRequester is implemented by adapters with a sandbox that a request can lift.

type Provider

type Provider interface {
	// Adapter is the registry key ("ses", "postmark", "smtp"…).
	Adapter() string
	Capabilities() Capabilities
	// Send delivers a batch (at most Capabilities().BatchSize messages).
	// It returns one result per message; an error means the whole call
	// failed (wrap ErrUnavailable for outages).
	Send(ctx context.Context, msgs []Message) ([]SendResult, error)
	// ParseWebhook verifies the request's signature and maps its payload to
	// events. It must not do network I/O except what verification requires
	// (for example fetching the SNS signing certificate, cached).
	ParseWebhook(ctx context.Context, r *http.Request, body []byte) ([]Event, error)
}

Provider is the contract every adapter implements.

type ProvisionInput

type ProvisionInput struct {
	// WebhookURL is where the provider posts events.
	WebhookURL string
	// Suffix, when set, is appended to the names of created resources
	// because another connection of this instance already uses the plain
	// names in the same account and region.
	Suffix string
}

ProvisionInput is what provisioning needs from ReputeCast.

type ProvisionResult

type ProvisionResult struct {
	// Done describes what exists now ("Created SNS topic `reputecast-events`
	// and subscribed `https://…`").
	Done string
	// DoneText is the message Done comes from.
	DoneText i18n.Text
	// Settings are merged into the provider's settings (topic ARNs,
	// configuration sets per stream).
	Settings map[string]any
	// Pending is true when the step waits for something outside ReputeCast
	// (the SNS subscription handshake); call Provision again a bit later.
	Pending bool
}

ProvisionResult is the outcome of one step.

type ProvisionStep

type ProvisionStep struct {
	Key string
	// Label says what the step will do ("Create configuration set `rc-system`").
	Label string
	// LabelText is the message Label comes from.
	LabelText i18n.Text
}

ProvisionStep is one provider-side resource the connect flow creates.

type Provisioner

type Provisioner interface {
	ProvisionSteps(ctx context.Context, in ProvisionInput) []ProvisionStep
	Provision(ctx context.Context, step string, in ProvisionInput) (ProvisionResult, error)
}

Provisioner creates the provider-side resources ReputeCast needs, one retryable step at a time (SES: SNS topic and subscription, a configuration set per stream).

type Quota

type Quota struct {
	Kind    string // rolling_24h, monthly_plan, warmup_daily
	Max     int64  // 0 = unknown/unlimited
	Used    int64
	MaxRate float64 // per second, 0 = unknown
	Sandbox bool
	Account string // human status: "Production · no enforcement"
	// AccountText is the message Account comes from (text.go).
	AccountText i18n.Text
	// VDM is true when Amazon SES's Virtual Deliverability Manager is on for
	// the account; other providers leave it false.
	VDM bool
}

Quota is a provider's sending allowance.

type QuotaReporter

type QuotaReporter interface {
	Quota(ctx context.Context) (Quota, error)
}

QuotaReporter is implemented by providers that expose quota and rate.

type RegionScanner

type RegionScanner interface {
	ScanRegions(ctx context.Context) ([]RegionStatus, error)
}

RegionScanner is implemented by adapters whose account standing differs per region (SES), so the region step can show where production access already exists.

type RegionStatus

type RegionStatus struct {
	Region string // "us-east-1"
	Name   string // "N. Virginia"
	// Production is false while the region is in the provider's sandbox.
	Production bool
	Max24h     int64
	MaxRate    float64
	// Err is set when the region couldn't be read (not enabled, no access).
	Err string
}

RegionStatus is the account's standing in one region.

type Reputation

type Reputation struct {
	// Bounce and Complaint are percentages (0.2 means 0.2%).
	Bounce    float64
	Complaint float64
	// Window describes the period measured ("7 d").
	Window string
}

Reputation is the bounce and complaint rate a provider measures for the account itself: what its own review and suspension thresholds apply to.

type ReputationReporter

type ReputationReporter interface {
	Reputation(ctx context.Context) (Reputation, error)
}

ReputationReporter is implemented by adapters whose API reports the account's own bounce and complaint rates (Postmark outbound stats). Without it, ReputeCast counts the rates from the events it received.

type SendError

type SendError struct {
	// Temporary errors (throttling, 5xx, timeouts) are retried; permanent
	// ones (invalid recipient, suppressed at provider) are not.
	Temporary bool
	Throttled bool
	Code      string // provider's code, kept for the event log
	Message   string
}

SendError explains a refused message.

func (*SendError) Error

func (e *SendError) Error() string

type SendResult

type SendResult struct {
	MessageID         uuid.UUID
	ProviderMessageID string
	Err               *SendError
}

SendResult is the outcome for one message of a batch.

func SendWithExtras

func SendWithExtras(ctx context.Context, p Provider, msgs []Message, extras []MessageExtras) ([]SendResult, error)

SendWithExtras sends msgs through p, with their extras when p supports them. It refuses (per message, permanently) a message with extras that p can't carry, rather than dropping its attachments.

type ServiceStatus

type ServiceStatus struct {
	Incident bool
	Summary  string
	URL      string
	Updated  time.Time
	// SummaryText is the message Summary comes from.
	SummaryText i18n.Text
}

ServiceStatus is what a provider's public status page reports.

type StatusPage

type StatusPage interface {
	StatusPageURL() (label, url string)
}

StatusPage is the public status page of a provider, shown as a button during outages ("AWS status").

type StatusReporter

type StatusReporter interface {
	ServiceStatus(ctx context.Context) (ServiceStatus, error)
}

StatusReporter reads the provider's public status page during an outage.

type Stream

type Stream string

Stream is the kind of mail.

const (
	StreamBroadcast  Stream = "broadcast"
	StreamAutomation Stream = "automation"
	StreamSystem     Stream = "system"
)

Streams.

type Suppression

type Suppression struct {
	Email     string
	Reason    string // hard_bounce, complaint, unsubscribe, manual
	Code      string
	CreatedAt time.Time
}

Suppression is one address suppressed at a provider.

type SuppressionSyncer

type SuppressionSyncer interface {
	ListSuppressions(ctx context.Context, since time.Time) ([]Suppression, error)
	AddSuppressions(ctx context.Context, emails []string) error
}

SuppressionSyncer is implemented by providers with a suppression list API.

type Terms

type Terms struct {
	// Variant names the account kind ("Transactional stream"); empty for the
	// provider as a whole.
	Variant string     `json:"variant,omitempty"`
	Bulk    BulkPolicy `json:"bulk"`
	Note    string     `json:"note"`
	Streams []Stream   `json:"streams"`
	// VariantText and NoteText are the messages Variant and Note come from.
	VariantText i18n.Text `json:"-"`
	NoteText    i18n.Text `json:"-"`
}

Terms is what one variant of a provider account may be used for.

func (Terms) In

func (t Terms) In(l i18n.Lang) Terms

In returns the terms with their variant and note in the reader's language.

type Tracking

type Tracking struct {
	OpenPixel   bool
	LinkRewrite bool
	// Detail explains the setting in the provider's words ("Server setting
	// TrackOpens is on, and TrackLinks is HtmlAndText").
	Detail string
	// Scope names where it applies ("Configuration set rc-broadcasts",
	// "Transactional stream").
	Scope string
	// DetailText and ScopeText are the messages Detail and Scope come from.
	DetailText i18n.Text
	ScopeText  i18n.Text
}

Tracking is the provider-side open and click tracking configuration.

type TrackingManager

type TrackingManager interface {
	Tracking(ctx context.Context) (Tracking, error)
	DisableTracking(ctx context.Context) error
}

TrackingManager reads and turns off provider-side tracking, so opens and clicks are not counted twice and links are not rewritten twice.

type Verifier

type Verifier interface {
	// Verify checks the credentials and returns account details for the UI.
	Verify(ctx context.Context) (Quota, error)
}

Verifier is implemented by adapters that can check credentials at connect time.

type WebhookHandshaker

type WebhookHandshaker interface {
	Handshake(ctx context.Context, r *http.Request, body []byte) (handled bool, response []byte, err error)
}

WebhookHandshaker completes subscription handshakes that are not events, such as an SNS SubscriptionConfirmation. handled is true when the request was a handshake; response, when set, is written back with 200.

type WebhookInspector

type WebhookInspector interface {
	InspectWebhook(ctx context.Context, url string) (WebhookStatus, error)
}

WebhookInspector reports whether the provider has a webhook pointing at url.

type WebhookRegistrar

type WebhookRegistrar interface {
	RegisterWebhook(ctx context.Context, url string) error
}

WebhookRegistrar is implemented by providers whose webhooks ReputeCast registers automatically.

type WebhookSecrets

type WebhookSecrets interface {
	WebhookSecretHeaders() []string
}

WebhookSecrets names the request headers that carry a shared webhook secret in plain text, beyond Authorization (which is never stored). The ingest endpoint leaves them out of the stored raw event; normalization runs on verified events and never needs them.

type WebhookStatus

type WebhookStatus struct {
	Registered bool
	ID         string
	URL        string
	// Queued and Sent come from the provider's own webhook delivery log when
	// its API exposes one; -1 when unknown.
	Queued int64
	Sent   int64
}

WebhookStatus is the provider-side view of the webhook pointing at us.

type WebhookTester

type WebhookTester interface {
	SendTestEvent(ctx context.Context, url string) error
}

WebhookTester asks the provider to send a test event to its webhook.

type WebhookUnregistrar

type WebhookUnregistrar interface {
	UnregisterWebhook(ctx context.Context, url string) error
}

WebhookUnregistrar removes the webhook RegisterWebhook added, when the provider is removed. A webhook that isn't there is not an error.

type WebhookVerifier

type WebhookVerifier interface {
	VerifyWebhook(ctx context.Context, r *http.Request, body []byte) error
}

WebhookVerifier checks a webhook request's signature without parsing it, so the ingest endpoint can answer immediately and leave normalization to a background job. Adapters without it are verified through ParseWebhook.

Directories

Path Synopsis
Package apiclient is the small JSON-over-HTTP client the API adapters (Postmark, Postal…) share: timeouts, a response size limit, and mapping of HTTP failures to providers.CallError so health checks and the sending pipeline can tell an outage from throttling from rejected credentials.
Package apiclient is the small JSON-over-HTTP client the API adapters (Postmark, Postal…) share: timeouts, a response size limit, and mapping of HTTP failures to providers.CallError so health checks and the sending pipeline can tell an outage from throttling from rejected credentials.
Package azureacs is the Azure Communication Services Email adapter, on the data-plane REST API without the Azure SDK.
Package azureacs is the Azure Communication Services Email adapter, on the data-plane REST API without the Azure SDK.
Package bounce maps SMTP replies and enhanced status codes (RFC 3463) to ReputeCast's shared bounce taxonomy, so every adapter classifies the same diagnostic the same way: mailbox_unknown, mailbox_full, domain_invalid, policy_block, spam_block, reputation, temporary, other.
Package bounce maps SMTP replies and enhanced status codes (RFC 3463) to ReputeCast's shared bounce taxonomy, so every adapter classifies the same diagnostic the same way: mailbox_unknown, mailbox_full, domain_invalid, policy_block, spam_block, reputation, temporary, other.
Package brevo is the Brevo (formerly Sendinblue) adapter, through the transactional email API v3.
Package brevo is the Brevo (formerly Sendinblue) adapter, through the transactional email API v3.
Package contracttest is the shared test suite every sending-provider adapter must pass (TECH_STACK note 10): registration and capabilities, the texts people read about the adapter (in every app language), Send (success, permanent rejection, outage, rejected credentials) against a fake of the provider's API, and ParseWebhook (signature verification and normalization) against recorded payloads.
Package contracttest is the shared test suite every sending-provider adapter must pass (TECH_STACK note 10): registration and capabilities, the texts people read about the adapter (in every app language), Send (success, permanent rejection, outage, rejected credentials) against a fake of the provider's API, and ParseWebhook (signature verification and normalization) against recorded payloads.
Package flex holds setting types that accept what a connection form may store.
Package flex holds setting types that accept what a connection form may store.
Package httpgeneric is the generic HTTP adapter (spec 5.2).
Package httpgeneric is the generic HTTP adapter (spec 5.2).
Package mailgun is the Mailgun adapter (US and EU regions).
Package mailgun is the Mailgun adapter (US and EU regions).
Package mailjet is the Mailjet adapter (Send API v3.1).
Package mailjet is the Mailjet adapter (Send API v3.1).
Package manage is the sending-providers domain: the provider list with health, quota, cost and capabilities (spec 7.3), the health job (outages, rejected credentials, webhooks silent, recovery, failover per stream), provider actions (re-check, credentials, settings, tracking, webhooks, backfill, held broadcasts) and the Adapters tab.
Package manage is the sending-providers domain: the provider list with health, quota, cost and capabilities (spec 7.3), the health job (outages, rejected credentials, webhooks silent, recovery, failover per stream), provider actions (re-check, credentials, settings, tracking, webhooks, backfill, held broadcasts) and the Adapters tab.
Package mimemsg renders a providers.Message as an RFC 5322 message with wneessen/go-mail, so the adapters that send raw MIME (Amazon SES, Postal, SMTP) produce byte-for-byte the same structure: multipart/alternative (text, then HTML), a Message-ID derived from the ReputeCast message id, and every header the sending pipeline set (List-Unsubscribe, Feedback-ID…).
Package mimemsg renders a providers.Message as an RFC 5322 message with wneessen/go-mail, so the adapters that send raw MIME (Amazon SES, Postal, SMTP) produce byte-for-byte the same structure: multipart/alternative (text, then HTML), a Message-ID derived from the ReputeCast message id, and every header the sending pipeline set (List-Unsubscribe, Feedback-ID…).
Package postal is the adapter for a self-hosted Postal server (postalserver.io).
Package postal is the adapter for a self-hosted Postal server (postalserver.io).
Package postmark is the Postmark adapter.
Package postmark is the Postmark adapter.
Package remote runs community adapters: sending adapters that live in their own process and speak the adapter protocol (docs/adapters.md, "Community adapters"), signed JSON over HTTP(S).
Package remote runs community adapters: sending adapters that live in their own process and speak the adapter protocol (docs/adapters.md, "Community adapters"), signed JSON over HTTP(S).
remotetest
Package remotetest is a fake community adapter process for tests: a small reference implementation of the adapter side of the protocol (docs/adapters.md) in Go.
Package remotetest is a fake community adapter process for tests: a small reference implementation of the adapter side of the protocol (docs/adapters.md) in Go.
Package resend is the Resend adapter (resend.com).
Package resend is the Resend adapter (resend.com).
Package sendgrid is the Twilio SendGrid adapter (v3 API).
Package sendgrid is the Twilio SendGrid adapter (v3 API).
Package ses is the Amazon SES adapter (SES API v2 through aws-sdk-go-v2), with events delivered through SNS.
Package ses is the Amazon SES adapter (SES API v2 through aws-sdk-go-v2), with events delivered through SNS.
Package simulator is the demo transport: a sending provider that touches no network.
Package simulator is the demo transport: a sending provider that touches no network.
Package smtp is the generic SMTP adapter (wneessen/go-mail).
Package smtp is the generic SMTP adapter (wneessen/go-mail).
bouncebox
Package bouncebox reads the bounce mailbox of an SMTP provider over IMAP (github.com/emersion/go-imap/v2, isolated here because it is still in beta) or POP3 (a small client in this package).
Package bouncebox reads the bounce mailbox of an SMTP provider over IMAP (github.com/emersion/go-imap/v2, isolated here because it is still in beta) or POP3 (a small client in this package).
dsn
Package dsn parses bounce and complaint reports that arrive by email: delivery status notifications (RFC 3464, multipart/report; report-type=delivery-status) and abuse reports (ARF, RFC 5965, report-type=feedback-report).
Package dsn parses bounce and complaint reports that arrive by email: delivery status notifications (RFC 3464, multipart/report; report-type=delivery-status) and abuse reports (ARF, RFC 5965, report-type=feedback-report).
Package sparkpost is the SparkPost adapter (US and EU).
Package sparkpost is the SparkPost adapter (US and EU).
Package state describes what ReputeCast stores about a connected provider in the providers table's JSON columns (capability snapshot, health, pricing, limits, provider-side tracking) and the display helpers every screen shares (short names, chart colours).
Package state describes what ReputeCast stores about a connected provider in the providers table's JSON columns (capability snapshot, health, pricing, limits, provider-side tracking) and the display helpers every screen shares (short names, chart colours).
Package webhookauth holds the webhook authentication schemes several sending providers share, so each adapter verifies them the same way: Standard Webhooks (the Svix scheme Resend uses), HMAC signatures over the body, and shared secrets sent as basic auth or in a header.
Package webhookauth holds the webhook authentication schemes several sending providers share, so each adapter verifies them the same way: Standard Webhooks (the Svix scheme Resend uses), HMAC signatures over the body, and shared secrets sent as basic auth or in a header.

Jump to

Keyboard shortcuts

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