Documentation
¶
Overview ¶
Package sending runs campaign sends: it builds the recipient list, applies suppressions, routes each recipient to a sending provider, throttles per provider and per mailbox provider, sends in batches through River jobs, updates live counters and pauses automatically when thresholds trip.
Index ¶
- Constants
- Variables
- func CanaryFrom(ctx context.Context, campaignID uuid.UUID) string
- func Retryable(err error) bool
- func Tx(ctx context.Context, pool *pgxpool.Pool, fn func(pgx.Tx) error) error
- func WithCanary(ctx context.Context, campaignID uuid.UUID, choice string) context.Context
- func WithRecheck(ctx context.Context, campaignID uuid.UUID, rc Recheck) context.Context
- type CanaryIP
- type CanaryPlan
- type CanaryPlanner
- type Engagement
- type Explained
- type NotReadyError
- type Outages
- type Readiness
- type ReadyAlways
- type Recheck
- type Recorder
- type Segments
- type ShareMover
- type Starter
- type Unavailable
Constants ¶
const ( CanaryAuto = "auto" CanaryOn = "on" CanaryOff = "off" )
The canary choices of a send (C1, GS-10): the sending engine decides (auto: a new sending domain or IP, contacts never mailed from the domain, an audience over 2× usual), or the person asked for one (on) or against one (off) on Review & send.
Variables ¶
var ErrNotReady = errors.New("send readiness is blocked")
ErrNotReady is returned when Send Readiness blocks the send at start.
ErrUnavailable is returned by Unavailable, before the sending domain is wired.
Functions ¶
func CanaryFrom ¶
CanaryFrom returns the canary choice WithCanary attached ("" for none).
func Tx ¶
Tx runs fn in a transaction and retries it when Postgres aborts it for a deadlock or a serialization failure. Concurrent batches update the same counter rows and can lock them in different orders; an aborted attempt commits nothing, so retrying is safe. fn must not keep state between attempts.
func WithCanary ¶
WithCanary hands Start the canary choice Review & send made for the campaign: auto (Traffic rules decide), on or off (review GS-10, C1).
Types ¶
type CanaryPlan ¶
type CanaryPlan struct {
Auto bool
Reasons []string
Size int64
Seeds int
Domain string
NeverMailed int64
Usual int64
Audience int64
// NewIPs are the routes' dedicated sending IPs that never sent for the
// workspace (the new_ip reason).
NewIPs []CanaryIP
}
CanaryPlan is what the sending engine would do about a canary for a campaign (C1: engine.CanaryPlanFor): whether it starts with one on its own, why (new_domain, never_mailed, over_usual) with the numbers behind the reasons, how many recipients the canary holds and how many seed mailboxes go with it.
type CanaryPlanner ¶
type CanaryPlanner interface {
CanaryPlanFor(ctx context.Context, campaignID uuid.UUID) (CanaryPlan, error)
}
CanaryPlanner tells Review & send the canary plan of a campaign.
type Engagement ¶
type Engagement struct {
MessageID uuid.UUID
Click bool
Link int
UserAgent string
IP string
Method string
At time.Time
}
Engagement is one open-pixel fetch or link click, as the tracking endpoints (and the demo transport) report it. Link is the click's link position; UserAgent, IP and Method decide human or machine.
type Explained ¶
Explained is an error that says why in a reader's language too, as the engine's state errors do ("Weekly Digest #142 is already sending").
type NotReadyError ¶
NotReadyError is ErrNotReady with what blocked the send.
func (*NotReadyError) Error ¶
func (e *NotReadyError) Error() string
func (*NotReadyError) Is ¶
func (e *NotReadyError) Is(target error) bool
Is makes errors.Is(err, ErrNotReady) hold.
type Outages ¶
type Outages interface {
// or "auth".
HoldShares(ctx context.Context, providerID uuid.UUID, reason string) error
}
Outages is the sending engine's side of a provider outage that the provider health job found (review GS-3): every running send's share on that provider goes through the engine's outage path, the same as an outage the send loop finds itself: held with its analysis and ways to continue (retry with a probe, move to a vetted provider, cancel the share), or moved when the Broadcast failover policy allows it. The engine implements it; the health job type-asserts its Starter.
type Readiness ¶
Readiness reruns Send Readiness when a send starts (the send-time recheck, add-on §3.8) and supplies its per-mailbox-provider throttles. The engine falls back to ReadyAlways when none is wired.
type ReadyAlways ¶
type ReadyAlways struct{}
ReadyAlways never blocks and keeps the default throttles.
type Recheck ¶
type Recheck struct {
// Verdict is "ready", "warnings" or "blocked".
Verdict string
// Blocking lists the titles of the checks that block.
Blocking []string
// Throttles are messages per second per mailbox provider ("outlook": 5);
// nil keeps the engine's defaults.
Throttles map[string]float64
// Audience is the final recipient count the recheck counted, and RunID
// its Send Readiness run; a hold records both.
Audience int64
RunID string
}
Recheck is the result of the send-time recheck.
type Recorder ¶
type Recorder interface {
RecordEngagement(ctx context.Context, evs []Engagement) error
}
Recorder records opens and clicks (the tracking domain implements it).
type Segments ¶
type Segments interface {
ContactIDs(ctx context.Context, workspaceID, segmentID uuid.UUID) ([]uuid.UUID, error)
}
Segments resolves saved segments to contact ids (the audience domain).
type ShareMover ¶
type ShareMover interface {
}
ShareMover moves what is left of a held share to another provider, vetted as every move is, keeping A/B and canary holdouts held (review GS-5). The engine implements it; the providers screen's decision on a held share goes through it.
type Starter ¶
type Starter interface {
Start(ctx context.Context, campaignID uuid.UUID, startedBy uuid.UUID) error
Pause(ctx context.Context, campaignID uuid.UUID, by uuid.UUID, reason string) error
Resume(ctx context.Context, campaignID uuid.UUID, by uuid.UUID) error
Cancel(ctx context.Context, campaignID uuid.UUID, by uuid.UUID) error
}
Starter starts or schedules a campaign send. The review & send screen calls it after confirmation (and after approval, when required).
type Unavailable ¶
type Unavailable struct{}
Unavailable is the Starter used until the sending domain replaces it.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package engine is ReputeCast's sending engine (spec 5.3, 7.6): it builds a campaign's recipient list, routes, renders and hands every message to its sending provider within rate limits and throttles, watches bounce, complaint and outage signals and pauses what they concern, sends automation emails, and serves the live monitor's snapshot and stream.
|
Package engine is ReputeCast's sending engine (spec 5.3, 7.6): it builds a campaign's recipient list, routes, renders and hands every message to its sending provider within rate limits and throttles, watches bounce, complaint and outage signals and pauses what they concern, sends automation emails, and serves the live monitor's snapshot and stream. |
|
Package rules holds a workspace's traffic rules (Sending providers › Traffic rules, review 2026-10 M34): the canary defaults (GS-10), the complaint watch after a send (GS-6), the thresholds by bounce type (GS-11) and the mailbox provider response rules (GS-12).
|
Package rules holds a workspace's traffic rules (Sending providers › Traffic rules, review 2026-10 M34): the canary defaults (GS-10), the complaint watch after a send (GS-6), the thresholds by bounce type (GS-11) and the mailbox provider response rules (GS-12). |
|
Package sendtest drives campaign sends end to end in tests: the real API's data, the sending engine on a virtual clock and the demo transport whose delivery and engagement events go through the same normalization as provider webhooks.
|
Package sendtest drives campaign sends end to end in tests: the real API's data, the sending engine on a virtual clock and the demo transport whose delivery and engagement events go through the same normalization as provider webhooks. |