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
- Variables
- func CleanIPs(ips []string) (clean, bad []string)
- func CommunityKey(name string) string
- func ErrorIn(err error, l i18n.Lang) string
- func IdempotencyWindow(p Provider) time.Duration
- func InstalledKey(kind, name string, manifest []byte) string
- func MessageIn(err error, l i18n.Lang) string
- func ParseIP(s string) (netip.Addr, bool)
- func Register(d Descriptor)
- func Registered(adapter string) bool
- func RuntimeAdapters() []string
- func SetRuntime(owner any, ds []Descriptor) error
- func SignatureVerified(ctx context.Context) bool
- func TextIn(english string, t i18n.Text, l i18n.Lang) string
- func WithSignatureVerified(ctx context.Context) context.Context
- type AccessTemplate
- type AccessTemplateInput
- type AccessTemplater
- type AccountIdentifier
- type Attachment
- type BounceMailboxTester
- type BroadcastStreamCreator
- type BulkPolicy
- type CallError
- type Capabilities
- type Config
- type ConnectionReport
- type ConnectionTester
- type DNSRecord
- type DeclaredText
- type Descriptor
- type DomainManager
- type Event
- type EventBackfiller
- type EventChecker
- type EventQueue
- type EventType
- type ExtrasSender
- type Field
- type IPReporter
- type IdempotentSender
- type MailboxReport
- type Message
- type MessageExtras
- type ProductionAccessRequest
- type ProductionAccessRequester
- type Provider
- type ProvisionInput
- type ProvisionResult
- type ProvisionStep
- type Provisioner
- type QueuedEvent
- type Quota
- type QuotaReporter
- type RegionScanner
- type RegionStatus
- type Reputation
- type ReputationReporter
- type SendError
- type SendResult
- type SendingIPs
- type ServiceStatus
- type StatusPage
- type StatusReporter
- type Stream
- type Suppression
- type SuppressionReasonAdder
- type SuppressionRemover
- type SuppressionScope
- type SuppressionScoper
- type SuppressionSyncer
- type Terms
- type Tracking
- type TrackingManager
- type Verifier
- type WebhookHandshaker
- type WebhookInspector
- type WebhookRegistrar
- type WebhookSecrets
- type WebhookStatus
- type WebhookTester
- type WebhookUnregistrar
- type WebhookVerifier
Constants ¶
const ( OneClickReplaced = "replaced" OneClickUnsigned = "unsigned" )
How a provider carries the one-click unsubscribe headers (Capabilities.OneClick).
const ( SuppressionScopeAccount = "account" // the provider account's own list SuppressionScopeTenant = "tenant" // an Amazon SES tenant's own list (one per workspace) SuppressionScopeStream = "stream" // per message stream (Postmark) SuppressionScopeDomain = "domain" // per sending domain (Mailgun) )
Suppression list scopes: where a provider's list lives.
const EventsQueue = "queue"
EventsQueue is ProvisionInput.Events for events that come through a queue ReputeCast polls.
const MaxSendingIPs = 64
MaxSendingIPs is how many sending IPs a person can list by hand for one provider.
const RuntimePrefix = "community:"
RuntimePrefix starts the registry key of every adapter installed while ReputeCast runs: community adapters are "community:<id>".
Variables ¶
var ErrBadSignature = errors.New("webhook signature verification failed")
ErrBadSignature is returned by ParseWebhook for unverifiable payloads.
var ErrNotSupported = errors.New("not supported by this provider")
ErrNotSupported is returned by optional operations an account or plan can't do.
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.
ErrUnavailable means the provider can't be reached at all (outage).
Functions ¶
func CleanIPs ¶
CleanIPs returns the addresses among ips written the canonical way, in address order (IPv4 first) and each once, as providers.ips keeps them, and the entries that aren't addresses, as given.
func CommunityKey ¶
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 ¶
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 IdempotencyWindow ¶
IdempotencyWindow is p's idempotency window, 0 when p doesn't dedupe.
func InstalledKey ¶
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 ¶
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 ParseIP ¶
ParseIP reads one sending IP: an IPv4 or IPv6 address, without a zone or a prefix length. An IPv4-mapped IPv6 address reads as the IPv4 address.
func Register ¶
func Register(d Descriptor)
Register adds an adapter to the catalog. Adapters call it from init.
func Registered ¶
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 ¶
SignatureVerified reports whether ctx carries WithSignatureVerified.
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 ¶
AccountIdentifier reports which provider account the credentials belong to (the AWS account id), so people can tell connections apart.
type Attachment ¶
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.
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"`
// OneClick is how the provider carries the List-Unsubscribe and
// List-Unsubscribe-Post headers ReputeCast adds: "" as given, signed
// with the domain's DKIM key; OneClickReplaced when it sets its own;
// OneClickUnsigned when its DKIM signature doesn't cover them, so
// Gmail and Yahoo may not offer one-click unsubscribe.
OneClick string `json:"oneClick,omitempty"`
// EventQueue names the queue the adapter can take its events from
// instead of webhooks ("SQS", review PR-4); empty for none.
EventQueue string `json:"eventQueue,omitempty"`
// Tenants is true when each workspace sends as its own tenant at the
// provider, with its own suppression list and reputation (SES, PR-11).
Tenants bool `json:"tenants,omitempty"`
// 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"`
// InfersDelivery: the provider reports no deliveries (plain SMTP), so
// a message counts as delivered once the server accepts it ("delivered
// (inferred)"); bounces and complaints still arrive as reports.
InfersDelivery bool `json:"infersDelivery,omitempty"`
// ReportsIPs is true when the adapter lists the account's dedicated
// sending IPs (IPReporter): ReputeCast keeps them up to date. Without
// it, people set a provider's IPs by hand.
ReportsIPs bool `json:"reportsIps,omitempty"`
}
Capabilities are the badges shown on each provider (spec 5.2).
func (Capabilities) In ¶
func (c Capabilities) In(l i18n.Lang) Capabilities
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 (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
// IP is the address that opened or clicked, when the provider reports
// it (its tracking classifies privacy proxies and scanners by network).
IP 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 EventChecker ¶
type EventChecker interface {
EventCheckAddress() string
// EventCheckFrom picks an address the provider may send the check from:
// one of candidates (the workspace's senders) whose address or domain
// it has verified, else any address of an identity it has verified; ""
// while none is (the check then waits for domain verification).
EventCheckFrom(ctx context.Context, candidates []string) (string, error)
}
EventChecker is implemented by adapters with an address that always accepts mail and makes the provider report a delivery (SES's mailbox simulator): the setup sends there and waits for that event before it calls events verified (PR-3).
type EventQueue ¶
type EventQueue interface {
// QueueEnabled reports whether this connection gets its events that way.
QueueEnabled() bool
// ReceiveEvents returns up to max queued events, waiting up to wait for
// the first one (a long poll).
ReceiveEvents(ctx context.Context, max int, wait time.Duration) ([]QueuedEvent, error)
// AckEvents removes stored events from the queue.
AckEvents(ctx context.Context, handles []string) error
}
EventQueue is implemented by adapters whose events can come through a queue ReputeCast polls instead of webhooks (SES through SQS, PR-4): nothing has to reach ReputeCast from the internet.
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.
type IPReporter ¶
type IPReporter interface {
SendingIPs(ctx context.Context) (SendingIPs, error)
}
IPReporter is implemented by adapters whose API lists the dedicated IPs an account sends from (Capabilities.ReportsIPs says so in the catalog). ReputeCast asks when a provider is connected, when its connection step is repeated and every day, and keeps providers.ip_mode and ips from the answer: the canary's new-IP trigger, Send Readiness's IP blocklist rows, Deliverability and warm-up read them.
A provider that can't be asked (an outage, refused credentials, a key without the scope) is an error, never an empty list: ReputeCast keeps what it knew. Adapters whose API can't list an account's IPs don't implement it, and people set those IPs by hand on Sending providers.
type IdempotentSender ¶
type IdempotentSender interface {
// IdempotencyWindow is how long the provider keeps a key: a message sent
// again within it is never delivered twice.
IdempotencyWindow() time.Duration
}
IdempotentSender is implemented by adapters whose provider recognizes a message it already took when the same message is sent again: each call carries an idempotency key derived from the ReputeCast message id alone (never from a batch), and the provider keeps the keys for a while.
The sending engine relies on it after a send whose answer was lost (the worker stopped in the middle of the call, the result couldn't be recorded): within the window it sends such a message again, one per call, and the provider drops the copy if it took the first one. Without it, or after the window, the message is "in doubt" and a person decides, because sending it again could deliver it twice (review GS-1).
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
// Events is how events come back: "" or "webhook" (the provider calls
// WebhookURL) or "queue" (a queue ReputeCast polls, PR-4).
Events string
// Tenant names the workspace's own tenant at the provider when it has
// them (SES tenants, PR-11); empty for none.
Tenant 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
// Note qualifies what was done, under it ("This workspace's own
// suppression list…"); NoteText is its message.
Note string
NoteText i18n.Text
}
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 QueuedEvent ¶
type QueuedEvent struct {
Body []byte
ContentType string
// Handle acknowledges the event once it is stored.
Handle string
}
QueuedEvent is one event pulled from an event queue, in the format the adapter's ParseWebhook reads.
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 ¶
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.
type SendResult ¶
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 SendingIPs ¶
type SendingIPs struct {
// Dedicated is true when the account sends from IPs of its own, leased
// or dedicated to it, and false on the provider's shared pool, whose IPs
// it doesn't list: they change from message to message and are kept
// warm by every customer's mail.
Dedicated bool
// IPs are the dedicated IPs as the provider lists them; none on a
// shared pool.
IPs []string
}
SendingIPs is what a provider's API says about the IPs an account's mail leaves from.
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 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 SuppressionReasonAdder ¶
type SuppressionReasonAdder interface {
AddSuppressionsWithReason(ctx context.Context, list []Suppression) error
}
SuppressionReasonAdder is implemented by providers whose suppression list keeps a reason (Amazon SES: BOUNCE or COMPLAINT): the sync uses it instead of AddSuppressions so a complaint is pushed as a complaint.
type SuppressionRemover ¶
type SuppressionRemover interface {
RemoveSuppressions(ctx context.Context, emails []string) error
}
SuppressionRemover is implemented by providers whose suppression list API can take an address off: the sync removes there what left the shared list.
type SuppressionScope ¶
type SuppressionScope struct {
Scope string
// Writable is false for a list shared with mail ReputeCast doesn't send
// (an Amazon SES account-level list without a tenant): the sync only
// reads it, so other apps on that account are never affected.
Writable bool
}
SuppressionScope says where a provider's suppression list lives and whether ReputeCast may write to it.
type SuppressionScoper ¶
type SuppressionScoper interface {
SuppressionScope() SuppressionScope
}
SuppressionScoper is implemented by providers whose list scope depends on the connection; others are a writable account-level list.
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. ReputeCast pushes only hard bounces and complaints that apply to all mail (never unsubscribes: those stop marketing, not a password reset).
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.
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 ¶
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 ¶
WebhookTester asks the provider to send a test event to its webhook.
type WebhookUnregistrar ¶
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.
Source Files
¶
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, ParseWebhook (signature verification and normalization) against recorded payloads, and, for an adapter that reports them, the account's sending IPs.
|
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, ParseWebhook (signature verification and normalization) against recorded payloads, and, for an adapter that reports them, the account's sending IPs. |
|
Package eventqueue polls the event queues of connections whose events come through a queue ReputeCast reads instead of a webhook (review PR-4: SES → SNS → an SQS queue).
|
Package eventqueue polls the event queues of connections whose events come through a queue ReputeCast reads instead of a webhook (review PR-4: SES → SNS → an SQS queue). |
|
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, where its sending IPs come from) 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, where its sending IPs come from) 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. |