Skip to main content

Function: createEmailMarketing()

createEmailMarketing(options): object

Defined in: engine.ts:191

The email marketing engine: every e-mail goes through send, which applies the rules in order — a valid address, not suppressed, allowed, a sender — and adds the one-click unsubscribe headers and footer, so a caller cannot skip one.

It owns the rules and nothing else: suppressions persist through your store, delivery through the provider (@ttoss/email-marketing/ses).

Parameters​

ParameterType
optionsEmailMarketingOptions

Returns​

applyEvents​

applyEvents: (events) => Promise<DeliveryEvent[]>

Applies delivery events: a permanent bounce suppresses the address for every scope, a complaint for the scope that sent it (every scope when the event carries none). Returns the events for your metrics.

Parameters​

ParameterType
eventsDeliveryEvent[]

Returns​

Promise<DeliveryEvent[]>

applyUnsubscribe​

applyUnsubscribe: (token) => Promise<{ email: string; scope: string; } | null>

Applies an unsubscribe link: suppresses the address for its scope. Returns what the token named, or null for a token that is not ours. Call it on POST only — mail scanners open every link with GET.

Parameters​

ParameterType
tokenunknown

Returns​

Promise<{ email: string; scope: string; } | null>

handleWebhook​

handleWebhook: (request) => Promise<WebhookResult>

Parameters​

ParameterType
request{ body: unknown; headers?: Record<string, string | string[] | undefined>; }
request.bodyunknown
request.headers?Record<string, string | string[] | undefined>

Returns​

Promise<WebhookResult>

readUnsubscribeToken​

readUnsubscribeToken: (token) => { email: string; scope: string; } | null

Parameters​

ParameterType
tokenunknown

Returns​

{ email: string; scope: string; } | null

send​

send: (__namedParameters) => Promise<SendResult>

Parameters​

ParameterType
__namedParametersSendInput

Returns​

Promise<SendResult>

suppressions​

suppressions: object

suppressions.assertCanResubscribe​

assertCanResubscribe: (args) => Promise<void>

Throws ResubscribeRefusedError unless the address is free or only manually suppressed.

Parameters​
ParameterType
args{ email: string; scope: string; }
args.emailstring
args.scopestring
Returns​

Promise<void>

suppressions.find​

find: (__namedParameters) => Promise<Suppression | null>

The suppression that decides for this sender: the recipient's own over the sender's checkbox.

Parameters​
ParameterType
__namedParameters{ email: string; scope: string; }
__namedParameters.emailstring
__namedParameters.scopestring
Returns​

Promise<Suppression | null>

suppressions.isSuppressed​

isSuppressed: (args) => Promise<boolean>

Parameters​
ParameterType
args{ email: string; scope: string; }
args.emailstring
args.scopestring
Returns​

Promise<boolean>

suppressions.resubscribe​

resubscribe: (__namedParameters) => Promise<void>

Undoes the sender's own (manual) opt-out. Refused for any other reason.

Parameters​
ParameterType
__namedParameters{ email: string; scope: string; }
__namedParameters.emailstring
__namedParameters.scopestring
Returns​

Promise<void>

suppressions.suppress​

suppress: (__namedParameters) => Promise<boolean>

Stops marketing to the address for one sender, or for every sender with scope: null. Suppressing again keeps the stronger reason. Returns whether anything changed.

Parameters​
ParameterType
__namedParameters{ detail?: string | null; email: string; reason: SuppressionReason; scope: string | null; }
__namedParameters.detail?string | null
__namedParameters.emailstring
__namedParameters.reasonSuppressionReason
__namedParameters.scopestring | null
Returns​

Promise<boolean>

unsubscribeUrl​

unsubscribeUrl: (__namedParameters) => string

Parameters​

ParameterType
__namedParameters{ email: string; scope: string; }
__namedParameters.emailstring
__namedParameters.scopestring

Returns​

string

Example​

const marketing = createEmailMarketing({
provider: sesProvider({ region: 'us-east-1', topicArn }),
suppressions: { store },
unsubscribe: { secret, url: (t) => `https://api.app.com/email/unsubscribe?t=${t}` },
resolveSender: async ({ scope }) => ({ name: 'Acme', email: 'news@acme.com' }),
});
await marketing.send({ scope: 'company-1', kind: 'welcome', to, subject, html, text });