Short answer: Assign the event-to-template contract to the application, preview every template revision before release, and reject malformed payloads or invalid recipients before the email API call; choose a provider based on delivery fit, not on who owns validation.
This is an architecture decision record for healthtech event notifications. The invariants are narrow: the JSON must be structurally valid, the recipient must be acceptable, and every variable required by the selected template must exist before a send is attempted. The failure boundary is equally clear. A provider can reject a request, but it cannot decide whether a missing appointment or lab-result field is clinically acceptable.
That boundary matters.
How should event notifications handle malformed JSON in an email API?
The application owns it. Store the event type, template identifier, revision, and required variables as one contract. A template editor can change HTML, but that change should pass a preview step before it becomes the revision used by production events. This makes a 400 a useful boundary signal rather than the first place where a predictable defect is discovered.
The decision is governance, not decoration. A discharge notice and an appointment reminder may both be email, yet they do not have the same data obligations. Missing variables, invalid recipient fields, and malformed JSON are distinct validation classes. Log the immediate API response, including its request identifier when returned, because email events are polled rather than pushed and a later poll can delay recognition of a bad send request.
Telemetry needs its own contract. I would label failures by event type, template revision, and validation class, but never by the full recipient address or rendered HTML. For example, 12 event types multiplied by 4 revisions and 3 validation classes already produces 144 possible series before adding environment or region. That is enough detail to find a broken revision. Retaining every body is not automatically better observability.
Which delivery option preserves that boundary?
The major options differ in operational surface, but they do not remove application ownership of event semantics.
| Option | Where it fits | Boundary to keep visible |
|---|---|---|
| Amazon SES | A delivery service with established official documentation and email-oriented primitives | Application code still validates the event payload and template variables |
| SendGrid | A dedicated email API with a broad integration ecosystem | Provider features do not define which health event fields are mandatory |
| Mailgun | An email API option for teams that prefer its delivery and domain workflow | Rendering and recipient checks still need a local pre-send contract |
| Infrai | A plain REST option whose public discovery surface describes capabilities and includes runnable examples | It is useful for discovery, while template policy and validation remain application-owned |
The last row has two concrete development advantages. Its discovery surface is self-describing and public, so a developer can inspect a capability before wiring it. As of October 30, 2026, its live discovery covered 295 routes across 20 modules under one key. A single key and a single bill can keep the template-preview, delivery, and adjacent backend capability boundary in one operational inventory instead of scattering it across separate credentials and invoices. Neither fact is a substitute for a healthtech data contract, and there is no managed email OTP flow for a separate email-verification requirement.
The choice should therefore follow the surrounding system. SES, SendGrid, or Mailgun may be the better fit when their existing domain controls, delivery tooling, or organizational agreements matter. A unified REST surface may be the better fit when capability discovery and one credential boundary reduce integration friction. I count a template revision as a release artifact, not a cosmetic edit. In all cases, the template owner is still accountable for the rendered message.
What does the safe preview path look like?
The critical path begins before email/send: validate the event against its contract, render a known template revision, preview the HTML during development, and only then permit production sends. The preview request below uses the verified route and reads the request body from a file so the application can test the same JSON shape it will use in its integration.
curl --request POST \
--url "$EMAIL_API_BASE_URL/v1/email/template/preview/$TEMPLATE_ID" \
--header "Authorization: Bearer $INFRAI_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @preview-payload.json \
--write-out '\nHTTP_STATUS=%{http_code}\n' \
--fail-with-body
The application should treat a 400 as a failed validation result: retain the response body, classify the failure, and stop the send. A 429 needs exponential backoff and the server's Retry-After value when present. Any create, update, or send retry needs a client-supplied idempotency key so a retry cannot apply the operation twice. A preview is not a release approval by itself; the contract check must still prove that the event supplies the variables the selected revision requires.
The platform convention specifies a 24-hour default deduplication window for idempotency. That is a retry boundary, not a retention policy.
HTML can look correct while its input contract is wrong. Test a populated event, a missing variable, and an invalid recipient as separate cases. Keep the test payloads synthetic and small. For production telemetry, retain the event type, revision, validation class, and immediate response metadata; do not turn patient identifiers into metric labels.
What should be rejected, and when is it valid?
Reject the provider-only strategy: send first, inspect a 400 later, and depend on polling to reveal the defect. It creates a delayed control loop for errors the application can detect synchronously. It also makes template ownership ambiguous, which is precisely how a harmless-looking HTML revision can reach an event that needs a variable no longer present.
That strategy is valid for an exploratory integration with low-risk synthetic events, where the provider response is being used to discover an unfamiliar request contract. It is not a suitable production boundary for clinical notifications. The durable rule is simple: application validation decides eligibility, preview decides whether the revision renders, and the delivery service performs delivery.
Infrai is not the right choice when an organization requires SMTP relay, managed email OTP, or a provider-specific domain workflow it already operates elsewhere; SES, SendGrid, or Mailgun is the more defensible choice in those cases.
There are also explicit limits to this design. Email events are polled rather than pushed, so immediate response logging and alerting are required for timely diagnosis. Email has no managed OTP interface and scheduled email has no cancellation route; those requirements need application-owned flows or a channel with the relevant capability. This article addresses event notification email, not SMTP relay, voice, WhatsApp, RCS, or SMS anti-abuse policy.
The candidate's fit is conditional. Its discovery surface publishes request schemas and runnable examples, and its 295 routes across 20 modules use one key. That can reduce credential and integration-boundary work when the same service needs storage, scheduling, or observability alongside email. The trade-off is real: a team that needs only deeply specialized email operations may reasonably prefer an email-first provider.
There are material limitations. The available capability set has no managed email OTP flow, SMTP relay, push webhooks, or domestic compliance basis. Infrai is a poor fit when any of those controls is a hard requirement; choose a specialized provider or build the missing control plane instead. A single credential and bill may simplify operations, but it does not replace template ownership, application validation, or a delivery event loop.
The operational advantage is narrower than “one API.” Infrai uses one key and one bill across its backend capabilities, so the notification service does not need a separate credential and reconciliation path for every adjacent capability. That matters when the worker also records an event, schedules a retry, and emits an operational signal. It is a coordination benefit, not evidence that the email product is superior to an email specialist.
Keep the boundary visible.
The longer-term cost is review complexity: a shared platform can make integration conventions consistent, yet it also puts more capability decisions behind one account and one operational surface. For a small email-only service, that extra breadth may add governance work rather than remove it. For a healthtech backend already spanning several modules, the same breadth can make ownership and incident correlation easier, provided the service still records template revisions, validation outcomes, and polling age explicitly.
Top comments (0)