sparkpost

package
v1.2.0 Latest Latest
Warning

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

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

Documentation

Overview

Package sparkpost is the SparkPost adapter (US and EU). SparkPost is now part of Bird, which steers new projects to Bird Email, a different API; this adapter connects existing SparkPost accounts, whose API is still operated and documented (checked 2026-10-13, https://bird.com/products/email/sparkpost).

Each message is its own transmission with an Idempotency-Key made from its ReputeCast id, which SparkPost keeps for 24 hours: a retry after a timeout or a 504 within that time never sends twice (idempotency.go).

Terms (checked 2026-10-13): SparkPost accounts are under Bird's terms since 22 December 2024 (https://bird.com/legal/legal-terms-updates). Bird's Acceptable Use Policy (https://bird.com/en-us/legal/acceptable-use-policy) requires permission-based lists with valid consent and a working unsubscribe, and forbids unsolicited bulk mail and bought or rented lists, as the archived SparkPost Messaging Policy did (https://bird.com/legal/sparkpost-messaging-policy). Bulk marketing to opted-in lists is therefore allowed on every stream.

Index

Constants

View Source
const (
	USBaseURL = "https://api.sparkpost.com"
	EUBaseURL = "https://api.eu.sparkpost.com"
)

API hosts per region.

View Source
const (
	MetaMessage = "rc_message"
	MetaStream  = "rc_stream"
)

Recipient metadata SparkPost echoes back on events (rcpt_meta).

View Source
const Adapter = "sparkpost"

Adapter is the registry key.

View Source
const WebhookUser = "reputecast"

WebhookUser is the basic-auth user ReputeCast registers on webhooks; the password is the provider's webhook secret.

Variables

This section is empty.

Functions

func Descriptor

func Descriptor() providers.Descriptor

Descriptor describes the adapter for the catalog.

func New

New builds the adapter from a connected provider's configuration.

Types

type Credentials

type Credentials struct {
	APIKey string `json:"api_key"`
}

Credentials are write-only.

type Provider

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

Provider talks to one SparkPost account.

func (*Provider) Adapter

func (p *Provider) Adapter() string

Adapter implements providers.Provider.

func (*Provider) AddDomain

func (p *Provider) AddDomain(ctx context.Context, domain string) ([]providers.DNSRecord, error)

AddDomain implements providers.DomainManager: a sending domain with a 2048-bit DKIM key, which also serves as bounce domain (a CNAME to SparkPost) when it is a subdomain, as SparkPost recommends. A domain already in the account is read instead.

func (*Provider) AddSuppressions

func (p *Provider) AddSuppressions(ctx context.Context, emails []string) error

AddSuppressions implements providers.SuppressionSyncer: each address is added to both lists, since ReputeCast marks its messages transactional (5,000 addresses, 10,000 entries per call).

func (*Provider) Backfill

func (p *Provider) Backfill(ctx context.Context, ids []string) ([]providers.Event, error)

Backfill implements providers.EventBackfiller from the events API (ten days of history): the latest outcome of each transmission.

func (*Provider) Capabilities

func (p *Provider) Capabilities() providers.Capabilities

Capabilities implements providers.Provider.

func (*Provider) DisableTracking

func (p *Provider) DisableTracking(ctx context.Context) error

DisableTracking implements providers.TrackingManager: the account's default open and click tracking off.

func (*Provider) DomainStatus

func (p *Provider) DomainStatus(ctx context.Context, domain string) ([]providers.DNSRecord, error)

DomainStatus implements providers.DomainManager. A domain whose DKIM or bounce CNAME isn't valid yet is verified again first.

func (*Provider) IdempotencyWindow

func (p *Provider) IdempotencyWindow() time.Duration

IdempotencyWindow implements providers.IdempotentSender: every message is its own transmission carrying Idempotency-Key "rc-" + the ReputeCast message id, and SparkPost keeps a key for 24 hours (Transmissions API › Idempotency; checked 2026-10-28). Within it the same request again is answered with the first one's response (X-Idempotent-Replayed: true) instead of a new transmission, and a request that differs answers 409 with code 1600 (see accepted). The engine stays inside the window with a margin.

func (*Provider) InspectWebhook

func (p *Provider) InspectWebhook(ctx context.Context, hookURL string) (providers.WebhookStatus, error)

InspectWebhook implements providers.WebhookInspector. SparkPost's batch status lists the batches that failed or were retried in the last day; those still failing count as queued.

func (*Provider) ListSuppressions

func (p *Provider) ListSuppressions(ctx context.Context, since time.Time) ([]providers.Suppression, error)

ListSuppressions implements providers.SuppressionSyncer over both of SparkPost's lists (transactional and non-transactional), one entry per address.

func (*Provider) ParseWebhook

func (p *Provider) ParseWebhook(ctx context.Context, r *http.Request, body []byte) ([]providers.Event, error)

ParseWebhook implements providers.Provider: the body is a JSON array of {"msys": {"<kind>_event": {…}}}; the empty test batch SparkPost posts when a webhook is created has no events.

func (*Provider) Quota

func (p *Provider) Quota(ctx context.Context) (providers.Quota, error)

Quota implements providers.QuotaReporter from the account's monthly (or, without one, daily) sending limit and usage. Enterprise accounts have no usage data.

func (*Provider) RegisterWebhook

func (p *Provider) RegisterWebhook(ctx context.Context, hookURL string) error

RegisterWebhook implements providers.WebhookRegistrar: a webhook with basic auth (SparkPost posts a test batch to it before saving, so the endpoint must be reachable). An existing webhook for the URL is updated.

func (*Provider) RemoveSuppressions

func (p *Provider) RemoveSuppressions(ctx context.Context, emails []string) error

RemoveSuppressions implements providers.SuppressionRemover: both the transactional and the non-transactional entries go.

func (*Provider) Reputation

func (p *Provider) Reputation(ctx context.Context) (providers.Reputation, error)

Reputation implements providers.ReputationReporter from the deliverability metrics of the last seven days: bounces per targeted message and spam complaints per accepted message.

func (*Provider) Send

func (p *Provider) Send(ctx context.Context, msgs []providers.Message) ([]providers.SendResult, error)

Send implements providers.Provider: one transmission per message.

func (*Provider) SendTestEvent

func (p *Provider) SendTestEvent(ctx context.Context, hookURL string) error

SendTestEvent implements providers.WebhookTester with the webhook's validate call (an empty event batch).

func (*Provider) SendingIPs

func (p *Provider) SendingIPs(ctx context.Context) (providers.SendingIPs, error)

SendingIPs implements providers.IPReporter with GET /api/v1/sending-ips, the account's dedicated sending IPs with their IP pool, returned whole, without pages. Transmissions go out through the connection's IP pool (or the default pool), so only its IPs count; an account without dedicated IPs has none and sends from SparkPost's shared IPs.

func (*Provider) StatusPageURL

func (p *Provider) StatusPageURL() (string, string)

StatusPageURL implements providers.StatusPage.

func (*Provider) Tracking

func (p *Provider) Tracking(ctx context.Context) (providers.Tracking, error)

Tracking implements providers.TrackingManager from the account's defaults. ReputeCast turns open and click tracking off on every transmission, so they never touch its mail.

func (*Provider) UnregisterWebhook

func (p *Provider) UnregisterWebhook(ctx context.Context, hookURL string) error

UnregisterWebhook implements providers.WebhookUnregistrar: DELETE /api/v1/webhooks/{id} for every webhook pointing at the URL (https://developers.sparkpost.com/api/webhooks/#webhooks-delete-delete-a-webhook). A webhook already gone (404) counts as removed.

func (*Provider) Verify

func (p *Provider) Verify(ctx context.Context) (providers.Quota, error)

Verify implements providers.Verifier.

func (*Provider) VerifyWebhook

func (p *Provider) VerifyWebhook(_ context.Context, r *http.Request, _ []byte) error

VerifyWebhook implements providers.WebhookVerifier: SparkPost doesn't sign payloads, so webhooks are registered with HTTP basic auth, over the webhook's unguessable URL.

type Settings

type Settings struct {
	// Region is "us" (default) or "eu".
	Region string `json:"region,omitempty"`
	// IPPool sends through a named IP pool (dedicated IPs).
	IPPool string `json:"ip_pool,omitempty"`
	// BaseURL overrides the API (tests).
	BaseURL string `json:"base_url,omitempty"`
}

Settings are the non-secret connection settings.

Jump to

Keyboard shortcuts

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