Documentation
¶
Overview ¶
Package ses is the Amazon SES adapter (SES API v2 through aws-sdk-go-v2), with events delivered through SNS.
Index ¶
- Constants
- Variables
- func Descriptor() providers.Descriptor
- func New(cfg providers.Config) (providers.Provider, error)
- func RolePrincipal(s string) string
- func TenantName(slug, suffix string) string
- func ValidCertURL(u string) bool
- type Credentials
- type Envelope
- type Provider
- func (p *Provider) AccessTemplate(ctx context.Context, in providers.AccessTemplateInput) (providers.AccessTemplate, error)
- func (p *Provider) AccountID(ctx context.Context) (string, error)
- func (p *Provider) AckEvents(ctx context.Context, handles []string) error
- 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) AddSuppressionsWithReason(ctx context.Context, list []providers.Suppression) error
- func (p *Provider) CallerARN() string
- 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) EventCheckAddress() string
- func (p *Provider) EventCheckFrom(ctx context.Context, candidates []string) (string, error)
- func (p *Provider) Handshake(ctx context.Context, _ *http.Request, body []byte) (bool, []byte, error)
- func (p *Provider) ListSuppressions(ctx context.Context, since time.Time) ([]providers.Suppression, error)
- func (p *Provider) ParseWebhook(ctx context.Context, _ *http.Request, body []byte) ([]providers.Event, error)
- func (p *Provider) Provision(ctx context.Context, step string, in providers.ProvisionInput) (providers.ProvisionResult, error)
- func (p *Provider) ProvisionSteps(_ context.Context, in providers.ProvisionInput) []providers.ProvisionStep
- func (p *Provider) QueueEnabled() bool
- func (p *Provider) Quota(ctx context.Context) (providers.Quota, error)
- func (p *Provider) ReceiveEvents(ctx context.Context, maxEvents int, wait time.Duration) ([]providers.QueuedEvent, error)
- func (p *Provider) RemoveSuppressions(ctx context.Context, emails []string) error
- func (p *Provider) RequestProductionAccess(ctx context.Context, r providers.ProductionAccessRequest) error
- func (p *Provider) ScanRegions(ctx context.Context) ([]providers.RegionStatus, error)
- func (p *Provider) Send(ctx context.Context, msgs []providers.Message) ([]providers.SendResult, error)
- func (p *Provider) SendWithExtras(ctx context.Context, msgs []providers.Message, ...) ([]providers.SendResult, error)
- func (p *Provider) SendingIPs(ctx context.Context) (providers.SendingIPs, error)
- func (p *Provider) ServiceStatus(ctx context.Context) (providers.ServiceStatus, error)
- func (p *Provider) StatusPageURL() (string, string)
- func (p *Provider) SuppressionScope() providers.SuppressionScope
- func (p *Provider) Tracking(ctx context.Context) (providers.Tracking, error)
- func (p *Provider) Verify(ctx context.Context) (providers.Quota, error)
- func (p *Provider) VerifyWebhook(ctx context.Context, _ *http.Request, body []byte) error
- type Settings
Constants ¶
const ( TopicName = "reputecast-events" // QueueName is the SQS queue of the queue mode (PR-4). QueueName = "reputecast-events" RoleName = "ReputeCastSES" // EventDestination names the configuration sets' event destination. EventDestination = "reputecast" )
Resource names created by provisioning. A suffix is added when another connection of the same instance already uses them in the account.
const ( TagMessage = "rc_message" TagStream = "rc_stream" )
Tag names SES echoes back on events.
const Adapter = "ses"
Adapter is the registry key.
const BatchSize = 50
BatchSize is how many messages one Send call handles (in parallel).
const Policy = `` /* 760-byte string literal not displayed */
Policy is the least-privilege IAM policy ReputeCast needs.
const QueueWait = 20 * time.Second
QueueWait is one long poll of the queue: the cadence the setup promises ("polls every 20 s").
const SimulatorAddress = "success@simulator.amazonses.com"
SimulatorAddress is SES's mailbox simulator: it accepts mail and makes SES report a delivery, without touching the account's bounce or complaint rates.
const Template = `` /* 2470-byte string literal not displayed */
Template is the CloudFormation template that creates the role.
Variables ¶
var RegionNames = map[string]string{
"us-east-1": "N. Virginia", "us-east-2": "Ohio", "us-west-1": "N. California", "us-west-2": "Oregon",
"ca-central-1": "Canada (Central)", "eu-west-1": "Ireland", "eu-west-2": "London", "eu-west-3": "Paris",
"eu-central-1": "Frankfurt", "eu-north-1": "Stockholm", "eu-south-1": "Milan", "ap-south-1": "Mumbai",
"ap-northeast-1": "Tokyo", "ap-northeast-2": "Seoul", "ap-northeast-3": "Osaka", "ap-southeast-1": "Singapore",
"ap-southeast-2": "Sydney", "sa-east-1": "São Paulo", "me-south-1": "Bahrain", "af-south-1": "Cape Town",
"il-central-1": "Tel Aviv",
}
RegionNames are the SES regions with the names the AWS console uses.
var StatusFeedURL = "https://status.aws.amazon.com/rss/ses-%s.rss"
StatusFeedURL is the public AWS status RSS feed for SES in a region. It is read only while a provider is down, to say whether AWS reports an incident.
Functions ¶
func Descriptor ¶
func Descriptor() providers.Descriptor
Descriptor describes the adapter for the catalog.
func RolePrincipal ¶
RolePrincipal turns an assumed-role session ARN (arn:aws:sts::123:assumed-role/Name/session) into the role ARN a trust policy can name; other ARNs are returned unchanged.
func TenantName ¶
TenantName is the tenant of a workspace: its slug in the characters SES allows (letters, digits, - and _), at most 64.
func ValidCertURL ¶
ValidCertURL reports whether u may host an SNS signing certificate.
Types ¶
type Credentials ¶
type Credentials struct {
AccessKeyID string `json:"access_key_id,omitempty"`
SecretAccessKey string `json:"secret_access_key,omitempty"`
SessionToken string `json:"session_token,omitempty"`
}
Credentials are write-only.
type Envelope ¶
type Envelope struct {
Type string `json:"Type"`
MessageID string `json:"MessageId"`
Token string `json:"Token,omitempty"`
TopicArn string `json:"TopicArn"`
Subject string `json:"Subject,omitempty"`
Message string `json:"Message"`
Timestamp string `json:"Timestamp"`
SignatureVersion string `json:"SignatureVersion"`
Signature string `json:"Signature"`
SigningCertURL string `json:"SigningCertURL"`
SubscribeURL string `json:"SubscribeURL,omitempty"`
UnsubscribeURL string `json:"UnsubscribeURL,omitempty"`
}
Envelope is an SNS HTTP(S) message.
func (Envelope) StringToSign ¶
StringToSign builds the canonical string SNS signs for this message type.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider talks to SES in one region.
func (*Provider) AccessTemplate ¶
func (p *Provider) AccessTemplate(ctx context.Context, in providers.AccessTemplateInput) (providers.AccessTemplate, error)
AccessTemplate implements providers.AccessTemplater.
func (*Provider) AckEvents ¶
AckEvents implements providers.EventQueue: stored messages leave the queue, ten per call.
func (*Provider) AddDomain ¶
AddDomain implements providers.DomainManager: Easy DKIM and a custom MAIL FROM domain (bounce.<domain>), associated with the workspace's tenant.
func (*Provider) AddSuppressions ¶
AddSuppressions implements providers.SuppressionSyncer as hard bounces. It never writes the account-level list: without a tenant it does nothing and says so (providers.ErrNotSupported).
func (*Provider) AddSuppressionsWithReason ¶
func (p *Provider) AddSuppressionsWithReason(ctx context.Context, list []providers.Suppression) error
AddSuppressionsWithReason implements providers.SuppressionReasonAdder: the tenant's list, a complaint as COMPLAINT and a hard bounce as BOUNCE.
func (*Provider) CallerARN ¶
CallerARN is who the credentials belong to, as the last AccountID call read it ("arn:aws:iam::123456789012:user/reputecast-ses").
func (*Provider) Capabilities ¶
func (p *Provider) Capabilities() providers.Capabilities
Capabilities implements providers.Provider.
func (*Provider) DisableTracking ¶
DisableTracking implements providers.TrackingManager by removing OPEN and CLICK from every event destination of the configuration set.
func (*Provider) DomainStatus ¶
DomainStatus implements providers.DomainManager.
func (*Provider) EventCheckAddress ¶
EventCheckAddress implements providers.EventChecker (PR-3).
func (*Provider) EventCheckFrom ¶
EventCheckFrom implements providers.EventChecker: SES sends only from verified identities, the simulator's mail included.
func (*Provider) Handshake ¶
func (p *Provider) Handshake(ctx context.Context, _ *http.Request, body []byte) (bool, []byte, error)
Handshake implements providers.WebhookHandshaker: it confirms SNS subscriptions to the provider's topic by visiting SubscribeURL.
func (*Provider) ListSuppressions ¶
func (p *Provider) ListSuppressions(ctx context.Context, since time.Time) ([]providers.Suppression, error)
ListSuppressions implements providers.SuppressionSyncer: the tenant's list, or the account-level list without a tenant.
func (*Provider) ParseWebhook ¶
func (p *Provider) ParseWebhook(ctx context.Context, _ *http.Request, body []byte) ([]providers.Event, error)
ParseWebhook implements providers.Provider for SNS notifications.
func (*Provider) Provision ¶
func (p *Provider) Provision(ctx context.Context, step string, in providers.ProvisionInput) (providers.ProvisionResult, error)
Provision implements providers.Provisioner.
func (*Provider) ProvisionSteps ¶
func (p *Provider) ProvisionSteps(_ context.Context, in providers.ProvisionInput) []providers.ProvisionStep
ProvisionSteps implements providers.Provisioner: the workspace's tenant (PR-11), the event path (SNS calling the webhook, or SNS into an SQS queue ReputeCast polls, PR-4) and a configuration set per stream.
func (*Provider) QueueEnabled ¶
QueueEnabled implements providers.EventQueue.
func (*Provider) ReceiveEvents ¶
func (p *Provider) ReceiveEvents(ctx context.Context, maxEvents int, wait time.Duration) ([]providers.QueuedEvent, error)
ReceiveEvents implements providers.EventQueue: up to max SNS envelopes, each one SES event, waiting up to wait for the first.
func (*Provider) RemoveSuppressions ¶
RemoveSuppressions implements providers.SuppressionRemover on the tenant's list only.
func (*Provider) RequestProductionAccess ¶
func (p *Provider) RequestProductionAccess(ctx context.Context, r providers.ProductionAccessRequest) error
RequestProductionAccess implements providers.ProductionAccessRequester.
func (*Provider) ScanRegions ¶
ScanRegions implements providers.RegionScanner: GetAccount in every SES region, ten at a time.
func (*Provider) Send ¶
func (p *Provider) Send(ctx context.Context, msgs []providers.Message) ([]providers.SendResult, error)
Send implements providers.Provider: SendEmail with raw MIME per message, up to ten at a time. A batch fails as a whole only when every message failed for the same account-level reason (outage, credentials).
func (*Provider) SendWithExtras ¶
func (p *Provider) SendWithExtras(ctx context.Context, msgs []providers.Message, extras []providers.MessageExtras) ([]providers.SendResult, error)
SendWithExtras implements providers.ExtrasSender: copies and attachments (transactional mail) go in the raw message, every recipient in the destination.
func (*Provider) SendingIPs ¶
SendingIPs implements providers.IPReporter with GetDedicatedIps, every page of it: the dedicated IPs of the account in the connection's region, standard and managed pools alike. An account without any sends from SES's shared pool. Access that can't call it (a role or keys from before ReputeCast asked for ses:GetDedicatedIps) is an error that says what to allow, so the IPs ReputeCast knows stay.
func (*Provider) ServiceStatus ¶
ServiceStatus implements providers.StatusReporter.
func (*Provider) StatusPageURL ¶
StatusPageURL implements providers.StatusPage.
func (*Provider) SuppressionScope ¶
func (p *Provider) SuppressionScope() providers.SuppressionScope
SuppressionScope implements providers.SuppressionScoper: the tenant's own list when the workspace has a tenant; otherwise the account-level list, which ReputeCast only reads, because every app on the AWS account shares it.
func (*Provider) Tracking ¶
Tracking implements providers.TrackingManager: SES rewrites links and adds an open pixel when the configuration set publishes OPEN or CLICK events.
type Settings ¶
type Settings struct {
Region string `json:"region"`
ConfigurationSet string `json:"configuration_set,omitempty"`
// ConfigurationSets names a configuration set per stream ("broadcast",
// "automation", "system"), as provisioned by the connect flow; streams
// without one use ConfigurationSet.
ConfigurationSets map[string]string `json:"configuration_sets,omitempty"`
// Access is "keys" (access key in the credentials) or "role" (assume
// RoleARN with ExternalID from the instance's own AWS credentials, as
// set up by the CloudFormation template).
Access string `json:"access,omitempty"`
RoleARN string `json:"role_arn,omitempty"`
ExternalID string `json:"external_id,omitempty"`
// TopicARNs restricts which SNS topics may post events.
TopicARNs []string `json:"topic_arns,omitempty"`
// Tenant is the SES tenant of the workspace (PR-11): its own suppression
// list and reputation, so a bounce in this workspace never stops mail of
// another workspace or app on the same AWS account. Sends name it.
Tenant string `json:"tenant,omitempty"`
// Events is how SES events come back: "" (SNS calls the webhook) or
// "queue" (an SQS queue ReputeCast polls, PR-4), with the queue's URL
// and ARN once provisioned.
Events string `json:"events,omitempty"`
QueueURL string `json:"queue_url,omitempty"`
QueueARN string `json:"queue_arn,omitempty"`
// AccountID is the AWS account (the tenant's resource ARNs).
AccountID string `json:"account_id,omitempty"`
// Endpoint overrides the SES API endpoint (tests, VPC endpoints).
Endpoint string `json:"endpoint,omitempty"`
}
Settings are the non-secret connection settings.