Sent Integration Starter
Bring up a Sent integration in four stages: authenticate, send idempotently, receive verified events, then harden. Do not conflate them — most broken integrations pass stage one and skip stage three.
Stage 1: client and credentials
Direct Sent v3 REST requests authenticate with the
header. An application proxy may accept
from its own callers, and the Sent MCP server uses client-managed OAuth, but neither changes the REST header sent to
. Organization keys may add
to act for a child profile; a profile-scoped key that sends that header receives
.
| Language | Package | Client |
|---|
| TypeScript | | |
| Python | (imports ) | or |
| Go | github.com/sentdm/sent-dm-go
| |
| Java | | SentOkHttpClient.fromEnv()
|
| C# | | |
| PHP | | new SentDm\Client($apiKey)
|
| Ruby | | |
Every SDK except PHP reads
automatically. Single-endpoint receiver samples read
; multi-tenant production receivers need a secret registry keyed by webhook id instead of one process-wide secret. Older documentation uses
and
— treat those as aliases and standardize on the
names.
Choose the client lifecycle from the credential model. A single-account service with one server-managed key should reuse a long-lived client and its connection pool. A multi-tenant proxy that resolves a caller or profile credential per request should construct the client for that request and discard it, so tenant credentials cannot leak through shared state. Framework-specific wiring, the Ruby
naming quirk, and per-ecosystem background-work choices are in
references/sdk-and-frameworks.md.
Validate configuration at boot and fail fast when the key is missing, rather than surfacing an auth error on the first customer send.
Stage 2: idempotent sends
json
{
"to": ["+14155551234"],
"template": {
"name": "order_confirmation",
"parameters": { "order_id": "12345" }
},
"sandbox": true
}
is the only required field. Supply
or
, and omit
to let automatic routing choose. Never write a
array with several values expecting fallback — that broadcasts and multiplies charges. Channel decisions belong to
.
Send
on every POST, PUT, and PATCH, derived deterministically from your own domain object (for example the order id plus the notification type) so a retry after a timeout cannot double-send. Keys are 1–255 characters of
, cached 24 hours per key per customer. A replay returns the cached body with
Idempotent-Replayed: true
and
. A duplicate arriving while the original is still in flight waits up to five seconds and then fails
; a
means the idempotency store was unavailable and the request was deliberately not executed.
means accepted, not delivered. Persist the returned
values immediately with your own tenant, profile, and logical send identifiers. Webhook events carry the Sent message id and account data, but never your application's tenant identifier.
Stage 3: verified webhook receiver
An integration without a receiver has no delivery truth. Register an endpoint, then verify every delivery: HMAC-SHA256 over
{x-webhook-id}.{x-webhook-timestamp}.{raw_body}
, keyed on the base64-decoded secret after stripping
, compared in constant time, rejecting timestamps outside 300 seconds. No SDK ships a verifier in any language.
Acknowledge with
before doing work, and deduplicate on
{message_id}:{message_status}
for outbound events and
for inbound. Ten consecutive failed deliveries disable the endpoint. Full mechanics belong to
; treat a verified, fast-acknowledging, deduplicating receiver as a launch requirement here.
Stage 4: harden
Retry policy by response class
| Response | Retry | How |
|---|
| No | Success |
| , | No | Fix the request |
| , | No | Stop immediately; ten consecutive auth failures lock the credential with escalating lockouts |
| | No | The referenced object does not exist |
| Yes, once, after a pause | A concurrent duplicate is in flight |
| Yes | Honor ; jittered backoff |
| , | Yes | Exponential backoff with jitter and a ceiling |
| Timeout with no response | Retry safely only with evidence | Reuse the same ; without one, there is no reliable API lookup by key or recipient, so do not automate a resend |
The standard limit is 200 requests per minute on a sliding window.
POST /v3/webhooks/{id}/rotate-secret
and
POST /v3/webhooks/{id}/test
are limited to 10 per minute. Rate-limit headers appear
only on
responses, so pacing must be designed rather than measured — batch up to 1,000 recipients per request and pace at roughly one request per second for bulk work.
Error handling
Errors arrive as
{success, data, error: {code, message, details, doc_url}, meta: {request_id, timestamp, version}}
. Branch on the
prefix family (
,
,
,
,
,
,
) rather than on message text or on individual codes. The full 46-code catalog with retry classification is in
references/errors-and-limits.md.
Two codes are counterintuitive:
and
are documented as request-level errors, but on
the request is accepted with
and the affected messages finalize as
and
. Insufficient balance therefore does not fail the send call.
Observability
Log
on every response, success or failure — it is the correlation handle for support. Record the mapping from your logical send to the returned
values, and keep an append-only event history so a reroute's sequence remains auditable. Never log the API key, the webhook signing secret,
, or raw recipient message content beyond your retention policy.
Launch checklist
Verification
Run the local preflight, which needs no credentials and no network:
bash
python3 scripts/preflight.py --self-test
Then verify a real path with
, which authenticates and validates without executing, and finally with one live send confirmed to
through the receiver.
Boundaries
Use
for receiver depth,
for channel choice,
for a confirmed one-off send,
for inbound and consent,
sent-profile-provisioning
for multi-tenant provisioning, and
when replacing another CPaaS provider.