sendgrid

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: 24 Imported by: 0

Documentation

Overview

Package sendgrid is the Twilio SendGrid adapter (v3 API).

Terms (checked 2026-10-13): Twilio's Acceptable Use Policy (https://www.twilio.com/en-us/legal/aup) and Email Policy (https://www.twilio.com/en-us/legal/service-country-specific-terms/email) allow marketing email with affirmative, provable consent, renewed after long inactivity; every marketing email needs a physical address, an unsubscribe link and a privacy-policy link, and bought or rented lists are forbidden. Mail Send takes marketing as well as transactional email (https://www.twilio.com/docs/sendgrid/for-developers/sending-email/v3-mail-send-faq), so bulk marketing is allowed on every stream.

Batching: Mail Send's personalizations share one body, but ReputeCast renders every message for its recipient, so each message is its own call.

Index

Constants

View Source
const (
	DefaultBaseURL = "https://api.sendgrid.com"
	EUBaseURL      = "https://api.eu.sendgrid.com"
)

API hosts.

View Source
const (
	ArgMessage = "rc_message"
	ArgStream  = "rc_stream"
)

Custom args SendGrid echoes back on every event.

View Source
const (
	SignatureHeader = "X-Twilio-Email-Event-Webhook-Signature"
	TimestampHeader = "X-Twilio-Email-Event-Webhook-Timestamp"
)

Headers of the signed Event Webhook.

View Source
const Adapter = "sendgrid"

Adapter is the registry key.

View Source
const Window = 26 * time.Hour

Window is how old a signed timestamp may be. SendGrid retries a delivery for 24 hours and doesn't document whether a retry is signed again, so the window spans the retries. The signature covers the body: a replay within it repeats events ingest's dedupe drops.

Variables

This section is empty.

Functions

func Descriptor

func Descriptor() providers.Descriptor

Descriptor describes the adapter for the catalog.

func MessageID

func MessageID(sgMessageID string) string

MessageID returns the X-Message-Id an event's sg_message_id starts with ("XBg2anf2TqCy6WXKQFhieQ.filter0905p1mdw1-…" → "XBg2anf2TqCy6WXKQFhieQ").

func New

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

func Verify

func Verify(publicKey, signature, timestamp string, body []byte) error

Verify checks a signed Event Webhook payload: an ECDSA P-256 signature (base64 ASN.1) over the timestamp header followed by the raw body, verified with the webhook's public key (base64 DER). It checks the signature only; VerifyWebhook also bounds the timestamp's age (Window).

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 SendGrid account (or subuser).

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 with automated security (SendGrid hosts DKIM and SPF behind CNAMEs, so key rotation needs no DNS change). A domain already authenticated is read instead.

func (*Provider) AddSuppressions

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

AddSuppressions implements providers.SuppressionSyncer through the global unsubscribe group, which stops all mail to the address at SendGrid.

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: account-level 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 that isn't valid yet is validated again, so the records show SendGrid's latest check.

func (*Provider) InspectWebhook

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

InspectWebhook implements providers.WebhookInspector.

func (*Provider) ListSuppressions

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

ListSuppressions implements providers.SuppressionSyncer.

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 events.

func (*Provider) Quota

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

Quota implements providers.QuotaReporter from the plan's credits (GET /v3/user/credits) and the account type and reputation.

func (*Provider) RegisterWebhook

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

RegisterWebhook implements providers.WebhookRegistrar: an Event Webhook without opens and clicks (ReputeCast's own), with signature verification turned on. An existing webhook for the URL is updated.

func (*Provider) Reputation

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

Reputation implements providers.ReputationReporter from the account's global stats over the last seven days: bounces per request and spam reports per delivered message.

func (*Provider) Send

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

Send implements providers.Provider: one Mail Send call per message.

func (*Provider) SendTestEvent

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

SendTestEvent implements providers.WebhookTester.

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. ReputeCast turns SendGrid's open, click and subscription tracking off on every message it sends, so account-level tracking never touches its mail.

func (*Provider) UnregisterWebhook

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

UnregisterWebhook implements providers.WebhookUnregistrar with DELETE /v3/user/webhooks/event/settings/{id} (https://www.twilio.com/docs/sendgrid/api-reference/webhooks/delete-an-event-webhook): every Event Webhook for the URL is deleted. A 404 is a webhook already gone.

func (*Provider) Verify

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

Verify implements providers.Verifier.

func (*Provider) VerifyWebhook

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

VerifyWebhook implements providers.WebhookVerifier.

type Settings

type Settings struct {
	// Region is "global" (default) or "eu" (EU subusers on Pro plans and up).
	Region string `json:"region,omitempty"`
	// IPPool sends through a named IP pool (dedicated IPs).
	IPPool string `json:"ip_pool,omitempty"`
	// WebhookVerificationKey is the signed Event Webhook's public key
	// (base64 DER). It is read from SendGrid for webhooks ReputeCast
	// registers; enter it only for a webhook set up by hand.
	WebhookVerificationKey string `json:"webhook_verification_key,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