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
- func Descriptor() providers.Descriptor
- func MessageID(sgMessageID string) string
- func New(cfg providers.Config) (providers.Provider, error)
- func Verify(publicKey, signature, timestamp string, body []byte) 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) 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) 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) 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) 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(ctx context.Context, r *http.Request, body []byte) error
- type Settings
Constants ¶
const ( DefaultBaseURL = "https://api.sendgrid.com" EUBaseURL = "https://api.eu.sendgrid.com" )
API hosts.
const ( ArgMessage = "rc_message" ArgStream = "rc_stream" )
Custom args SendGrid echoes back on every event.
const ( SignatureHeader = "X-Twilio-Email-Event-Webhook-Signature" TimestampHeader = "X-Twilio-Email-Event-Webhook-Timestamp" )
Headers of the signed Event Webhook.
const Adapter = "sendgrid"
Adapter is the registry key.
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 ¶
MessageID returns the X-Message-Id an event's sg_message_id starts with ("XBg2anf2TqCy6WXKQFhieQ.filter0905p1mdw1-…" → "XBg2anf2TqCy6WXKQFhieQ").
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) AddDomain ¶
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 ¶
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 ¶
DisableTracking implements providers.TrackingManager: account-level open and click tracking off.
func (*Provider) DomainStatus ¶
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 ¶
Quota implements providers.QuotaReporter from the plan's credits (GET /v3/user/credits) and the account type and reputation.
func (*Provider) RegisterWebhook ¶
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 ¶
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 ¶
SendTestEvent implements providers.WebhookTester.
func (*Provider) StatusPageURL ¶
StatusPageURL implements providers.StatusPage.
func (*Provider) Tracking ¶
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 ¶
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.
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.