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) 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(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) RemoveSuppressions ¶
RemoveSuppressions implements providers.SuppressionRemover: the global suppressions ReputeCast added are taken off one by one.
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) SendingIPs ¶
SendingIPs implements providers.IPReporter with GET /v3/ips/assigned ("Retrieve all assigned IPs"), which returns the IPs assigned to the account whole, without pages. With an IP pool set, mail goes out through that pool's IPs only, so only those count. An account on SendGrid's shared IPs has none assigned. A key without access to IP Management is refused with what to change, so the IPs ReputeCast knows stay.
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.