Best Practices
Reuse a single client instance
NotificationHubClient owns a shared HTTP client (java.net.http.HttpClient in Java, fetch in Node.js). Build one instance at application startup and inject or import it everywhere you need to send notifications, rather than constructing a new client per request or per notification.
Load credentials from the environment
Never hardcode apiKey/apiSecret in source. Use environment variables, a secrets manager, or — on Spring Boot — NotificationHubAutoConfiguration backed by application.yml placeholders. See Authentication for the full guidance on protecting your secret.
Use idempotency keys for anything retried
If your call site has its own retry logic (a queue consumer, a webhook handler, a cron job), generate the idempotency key once per logical send and reuse it across retries with sendWithIdempotency — this makes retries safe even if a prior attempt actually succeeded server-side but the response was lost.
Prefer templates over inline content for anything reused
If the same subject/body shape is sent more than once (welcome emails, password resets, shipping updates), create a template and reference it by templateId with addVariable(...), rather than rebuilding the same string in application code repeatedly. This keeps copy changes out of your deployment pipeline.
Handle each error category deliberately
Don't blanket-catch and retry everything — see Error Handling for which categories are safe to retry and which mean your request itself needs to change.
Poll the dead-letter queue
Failed deliveries land in the DLQ rather than disappearing silently. Build a periodic job that checks getDeadLetterQueue, and either fix the underlying issue (bad recipient, expired provider credential) and call retryFailedNotification, or surface it to an on-call channel.
Test provider credentials before saving them
Call testConnection with a candidate credential set before calling configure/update, so a bad credential is caught immediately instead of surfacing later as failed sends.