thinwrap_notifications (thinwrap_notifications v1.2.0)

Send email, SMS, push and chat across 35 providers — one normalized surface, zero dependencies.

Every function takes a provider config and an input map and returns {ok, Result} or {error, ConnectorError}:

Config = #{provider => sendgrid, api_key => <<"SG....">>, from => <<"hello@acme.com">>},
{ok, #{status := queued, provider_message_id := Id}} =
    thinwrap_notifications:send_email(Config, #{
        to => <<"user@example.com">>,
        subject => <<"Welcome">>,
        text => <<"Thanks for signing up!">>
    }).

The config's provider selects the vendor; switching vendor changes only the config. Each provider serves exactly one channel (supports/2).

Two kinds of failure

Send failures — a vendor error response, a transport failure, or request data the connector rejects before sending (an invalid region, a header the vendor forbids, a header value with a line break, a value that cannot be encoded) — come back as {error, connector_error()}, a plain map whose code you branch on. invalid_request is never worth retrying.
Misuse — a config or input that is not a map, a missing required config key, an unknown key, a value of the wrong type, a provider used on the wrong channel — raises error({badarg, Description}). Folding those into {error, _} would make a bug in the calling code look like bad end-user input or, worse, a retryable outage.

The normalized surface

Every send returns #{success := true, status := send_status(), provider_message_id := binary(), raw := term()}. provider_message_id is <<>> when the vendor returned none; raw is the decoded vendor body (JSON null is the atom null, also used for an empty or non-JSON body).

Only fields at least 90% of a channel's providers support are first-class on the input (the baseline-coverage rule). Provider-specific fields flow through passthrough; provider-level settings live on the config.

Passthrough

Every input accepts passthrough => #{body => map(), headers => map(), query => map()}, forwarded as given and overriding what the connector set (auth included): body deep-merged, headers and query shallow-merged, header names case-insensitively. Write the vendor's own wire names. Seven connectors rewrite only the TOP-LEVEL body keys to the vendor's casing: Postmark and Twilio to PascalCase, Mailtrap, SparkPost, SendGrid, MailerSend and Scaleway to snake_case; nested maps always ride verbatim.

Errors

connector_error() carries code (one of the six canonical codes shared with the sibling libraries), message, and when known status, provider_message and cause. For a vendor error cause is #{<<"raw">> => DecodedBody} plus <<"retryAfter">> (the raw header) and <<"retryAfterSeconds">> when the vendor sent Retry-After. There is deliberately no top-level retry field: retry is the caller's policy.

Summary

Types

channel()

chat_input()

The chat baseline. to is the channel / room / recipient (unused by webhook-bound connectors, whose URL encodes the target). Rich content (blocks, attachments, threads) flows through passthrough.

config()

Provider configuration. provider selects the connector; the other keys depend on it (credentials are secret/0, everything else a binary; keys not listed as required are optional)

connector_error()

The send-failure value. code is the normalized classification shared with the sibling libraries; status is the HTTP status when the provider answered (absent for a transport failure or a pre-flight rejection); cause is #{<<"raw">> => DecodedVendorBody} (+ <<"retryAfter">>, <<"retryAfterSeconds">>), or for a transport or encoding failure only its kind, #{<<"raw">> => #{<<"exception">> => Kind}} — never the request.

email_attachment()

An attachment. content is the raw bytes (the connector base64-encodes as the vendor needs). With content_id set the attachment is inline, referenced as cid:<content_id> from the HTML.

email_input()

The ≥90%-baseline email payload. Every key is optional (empty by default, as in the siblings); from overrides the config's default sender. Header names and values are binaries.

passthrough()

provider()

Provider ids, byte-identical to the sibling libraries' values (hence the quoted atoms such as 'one-signal').

push_input()

The four-field push baseline. to is a single device token / recipient; topic and multi-target delivery, badge, sound, TTL and platform blocks flow through passthrough.

result()

What every send_* function returns.

secret()

A credential, or a zero-arity fun returning it. The fun form keeps the secret out of crash reports and logs that print the config map (EEF secure-coding guidance).

send_result()

send_status()

Normalized delivery status on every result.

sms_input()

The ≥90%-baseline SMS payload; from overrides the config's sender.

token_cache()

A bring-your-own cache for the FCM and APNs auth tokens. The library holds no token state: without a cache it signs a fresh token on every send. get(Key) returns {ok, {Token, ExpiresAt}} or error; set(Key, Token, ExpiresAt) is called after a fresh token is minted (its return value is ignored). ExpiresAt is an absolute Unix time in seconds. Nothing is evicted on a vendor 401/403 — eviction is the cache's policy. For APNs a cache is required in production: Apple rejects a new provider token more often than once per 20 minutes (429 TooManyProviderTokenUpdates).

Functions

providers(Channel)

The providers serving Channel, sorted.

send_chat(Config, Input)

Send a chat message (Telegram, Slack, WhatsApp Business, Discord, MS Teams, Google Chat, Mattermost, Rocket.Chat, LINE).

send_email(Config, Input)

Send an email (SES, Resend, Mailgun, SendGrid, Postmark, MailerSend, Mailtrap, Brevo, SparkPost, Scaleway).

send_push(Config, Input)

Send a push notification (FCM, Expo, APNs, OneSignal, Pusher Beams, WonderPush).

send_sms(Config, Input)

Send an SMS (Vonage, Twilio, Plivo, SNS, Sinch, Telnyx, Infobip, MessageBird, TextMagic, D7 Networks).

supports(Provider, Channel)

Whether Provider serves Channel.