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
- func Descriptor() providers.Descriptor
- func New(cfg providers.Config) (providers.Provider, error)
- type Credentials
- type Provider
- func (p *Provider) Adapter() string
- func (p *Provider) AddDomain(ctx context.Context, domain string) ([]providers.DNSRecord, error)
- func (p *Provider) AddSuppressions(ctx context.Context, emails []string) error
- func (p *Provider) Backfill(ctx context.Context, ids []string) ([]providers.Event, error)
- func (p *Provider) Capabilities() providers.Capabilities
- func (p *Provider) DisableTracking(ctx context.Context) error
- func (p *Provider) DomainStatus(ctx context.Context, domain string) ([]providers.DNSRecord, error)
- func (p *Provider) IdempotencyWindow() time.Duration
- func (p *Provider) InspectWebhook(ctx context.Context, hookURL string) (providers.WebhookStatus, error)
- func (p *Provider) ListSuppressions(ctx context.Context, since time.Time) ([]providers.Suppression, error)
- func (p *Provider) ParseWebhook(ctx context.Context, r *http.Request, body []byte) ([]providers.Event, error)
- func (p *Provider) Quota(ctx context.Context) (providers.Quota, error)
- func (p *Provider) RegisterWebhook(ctx context.Context, hookURL string) error
- func (p *Provider) RemoveSuppressions(ctx context.Context, emails []string) error
- func (p *Provider) Reputation(ctx context.Context) (providers.Reputation, error)
- func (p *Provider) Send(ctx context.Context, msgs []providers.Message) ([]providers.SendResult, error)
- func (p *Provider) SendTestEvent(ctx context.Context, hookURL string) error
- func (p *Provider) SendingIPs(ctx context.Context) (providers.SendingIPs, error)
- func (p *Provider) StatusPageURL() (string, string)
- func (p *Provider) Tracking(ctx context.Context) (providers.Tracking, error)
- func (p *Provider) UnregisterWebhook(ctx context.Context, hookURL string) error
- func (p *Provider) Verify(ctx context.Context) (providers.Quota, error)
- func (p *Provider) VerifyWebhook(_ context.Context, r *http.Request, _ []byte) error
- type Settings
Constants ¶
const ( USBaseURL = "https://api.sparkpost.com" EUBaseURL = "https://api.eu.sparkpost.com" )
API hosts per region.
const ( MetaMessage = "rc_message" MetaStream = "rc_stream" )
Recipient metadata SparkPost echoes back on events (rcpt_meta).
const Adapter = "sparkpost"
Adapter is the registry key.
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.
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) AddDomain ¶
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 ¶
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 ¶
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 ¶
DisableTracking implements providers.TrackingManager: the account's default open and click tracking off.
func (*Provider) DomainStatus ¶
DomainStatus implements providers.DomainManager. A domain whose DKIM or bounce CNAME isn't valid yet is verified again first.
func (*Provider) IdempotencyWindow ¶
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 ¶
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 ¶
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 ¶
RemoveSuppressions implements providers.SuppressionRemover: both the transactional and the non-transactional entries go.
func (*Provider) Reputation ¶
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 ¶
SendTestEvent implements providers.WebhookTester with the webhook's validate call (an empty event batch).
func (*Provider) SendingIPs ¶
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 ¶
StatusPageURL implements providers.StatusPage.
func (*Provider) Tracking ¶
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 ¶
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.
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.