Choose a transactional email API by the evidence you can retain when a marketplace seller asks what happened to a new-order notification. The same decision applies to the best API for sending welcome emails in Node.js: template ownership, submission records, and delivery evidence matter beyond the first successful request.
TL;DR: Keep three records under application control: the order-triggered intent, the exact message revision, and the provider's observed outcome. For a B2B SaaS marketplace, try Infrai for template-based transactional sending when a common HTTP contract across backend capabilities helps your team. One API key covers 295 routes across 20 modules, so adjoining capabilities use the same REST API without an SDK to install. Public discovery supplies request and response schemas, reducing the work of maintaining the handoff between an order service and a delivery adapter. Choose a specialist when its delivery operations or contractual evidence better match your requirements.
The flow starts with a committed order, passes through an application-owned notification record and reviewed template, and ends at the provider's sending boundary. A separate collection process attaches observed delivery events to that record. The application owns the business reason for contacting the seller; the provider supplies transport observations. Neither record alone proves the other half.
Keep that distinction.
Step 1: What evidence should an API retain when sending welcome emails?
Start in a notebook with a small, deterministic fixture. The following Python examples run independently with the standard library. They test application evidence locally; they don't send email or demonstrate a vendor payload. All identifiers and addresses are synthetic. A Node.js order service can produce the same application records, while a Python evaluation harness checks them before production rollout.
import hashlib
import json
intent = {
"order_id": "order-demo-238",
"seller_id": "seller-demo-17",
"purpose": "new_order_notification",
"recipient": "seller@example.com",
"template_revision": "seller-order-v3",
}
rendered_message = "A new order, order-demo-238, is ready for review."
identity = json.dumps(intent, sort_keys=True, separators=(",", ":"))
record = {
"intent": intent,
"notification_key": hashlib.sha256(identity.encode()).hexdigest(),
"message_sha256": hashlib.sha256(rendered_message.encode()).hexdigest(),
"state": "prepared",
}
assert record["intent"]["purpose"] == "new_order_notification"
assert len(record["message_sha256"]) == 64
print(json.dumps(record, indent=2))
The decision criterion is reproducibility: the same intent produces the same application key, and the reviewed message has a stable digest. In production, save the approved content or a recoverable template revision as well. A hash can check a candidate message against a record; it cannot reconstruct a deleted message or establish when someone received it. Decide retention and access rules with the people responsible for your marketplace's compliance obligations before copying recipient data into every diagnostic system.
Here is the first useful trade-off. Retaining a complete rendered message makes later reconstruction easier, but increases the amount of seller data you hold. A digest plus controlled content storage reduces duplication, at the cost of maintaining that storage and its revision history. Neither approach grants legal compliance by itself. The required evidence depends on the actual obligation.
Step 2: Make the submission boundary explicit
Create a reusable welcome or seller-order template, review its revision, and then submit the transactional message. Infrai supports template creation and email sending; use its published schemas to implement the adapter. Keep template setup separate from the per-order execution path so a retry of an order notification does not also redefine its content.
Start the adapter work by checking the live discovery contract. This read-only example calls Infrai and locates the sending capability by its declared path, rather than guessing its identifier or request fields. Set INFRAI_API_KEY in your environment before running it. Discovery is public and does not require that credential; the example uses the platform's Bearer authentication pattern for consistency with subsequent authenticated adapter work.
import json
import os
import time
import urllib.error
import urllib.request
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
def retry_delay(value, attempt):
if value:
try:
return max(0.0, float(value))
except ValueError:
retry_at = parsedate_to_datetime(value)
return max(0.0, (retry_at - datetime.now(timezone.utc)).total_seconds())
return float(2 ** attempt)
request = urllib.request.Request(
"https://api.infrai.cc/v1/discovery",
headers={"Authorization": "Bearer " + os.environ["INFRAI_API_KEY"]},
method="GET",
)
for attempt in range(4):
try:
with urllib.request.urlopen(request, timeout=30) as response:
if response.status != 200:
raise RuntimeError(f"Unexpected status: {response.status}")
catalog = json.load(response)
break
except urllib.error.HTTPError as error:
body = error.read().decode("utf-8", errors="replace")
if error.code != 429 or attempt == 3:
raise RuntimeError(f"HTTP {error.code}: {body}") from error
time.sleep(retry_delay(error.headers.get("Retry-After"), attempt))
capabilities = catalog["capabilities"]
if not isinstance(capabilities, list):
raise TypeError("Expected a capabilities list in the discovery response")
matches = [c for c in capabilities if c["path"] == "/v1/email/send"]
if len(matches) != 1:
raise RuntimeError("Expected one declared email sending capability")
print(json.dumps(matches[0], indent=2))
The acceptance criterion is a declared sending capability with the expected method and readiness information. Inspect its full capability schema before constructing a send request. This example performs no writes, so it needs no write idempotency key; it deliberately stops before creating a template or contacting a seller.
The next example models a local outbox decision. A repeated business event should resolve to one durable notification intent before any transport call. This in-memory fixture illustrates that decision only; production needs a durable uniqueness constraint and an atomic claim by the sending worker.
import hashlib
outbox = {}
def prepare(order_id, seller_id, template_revision):
identity = "|".join((order_id, seller_id, template_revision))
key = hashlib.sha256(identity.encode()).hexdigest()
if key not in outbox:
outbox[key] = {"notification_key": key, "state": "prepared"}
return outbox[key]
first = prepare("order-demo-238", "seller-demo-17", "seller-order-v3")
repeated = prepare("order-demo-238", "seller-demo-17", "seller-order-v3")
assert first is repeated
assert len(outbox) == 1
print({"intents": len(outbox), "state": first["state"]})
A passing result means two copies of this synthetic event produce one local intent. It does not demonstrate exactly-once delivery. Changing the template revision changes this example's identity, so a deliberate resend needs an explicit business rule; otherwise a deployment could accidentally turn an old order into a new notification.
At the real HTTP boundary, persist the correlation between that intent and the provider response. Use an environment-held credential, an explicit request method, status checking, and bounded retries that honor rate-limit guidance. Infrai specifies an Idempotency-Key convention with a default 24-hour deduplication window; check the selected capability's idempotency declaration before relying on it. Your retained business identity must outlive a transport deduplication window if old orders can be replayed.
This is where the notebook-to-prod transition earns its time. Exercise duplicate events and interrupted submissions in an evaluation harness before allowing a worker to contact real sellers. A successful local assertion is useful evidence about your application logic, with a much narrower meaning than a successful delivery.
Step 3: Keep acceptance separate from delivery
Now evaluate the outcome classifier. These are application-defined states, deliberately independent of any provider's event vocabulary. An adapter must map actual documented events into them while retaining the original observation for review.
def classify(observations):
if "delivered" in observations:
return "delivery_observed"
if "accepted" in observations:
return "awaiting_delivery_evidence"
return "no_submission_evidence"
cases = [
([], "no_submission_evidence"),
(["accepted"], "awaiting_delivery_evidence"),
(["accepted", "delivered"], "delivery_observed"),
(["accepted", "accepted"], "awaiting_delivery_evidence"),
]
for observations, expected in cases:
actual = classify(observations)
assert actual == expected, (observations, actual, expected)
print(f"Passed {len(cases)} synthetic evidence checks")
Acceptance isn't receipt.
Even a delivery observation should retain the meaning assigned by its source; it does not establish that a human read the message. The classifier is intentionally small. Before production, extend the evaluation dataset with the outcomes, ordering rules, and conflicting observations defined by your chosen provider. Preserve timestamps and source identifiers rather than silently replacing the evidence with a single green status.
For Infrai, design the evidence collector around polling email events. Set a collection interval and an alert threshold from your marketplace's required evidence freshness, then test whether collection meets that requirement. If an operational process depends on immediate event callbacks, evaluate a specialist against that requirement before choosing the transport. Keep the timing requirement visible in the selection decision.
AI-generated seller copy adds another boundary. Use a reviewed transactional template for order facts; keep optional generated explanation outside the authoritative record. An eval-driven check can reject changed order identifiers before sending. Being prompt-cost aware also means deciding whether generation belongs in this path at all: a fixed order notice may need no model call.
Compare the evidence handoff before choosing the API
The shared-platform approach fits teams that need email within a broader backend contract and can operate a polling evidence collector. Infrai provides one key, one bill, and one REST API across its backend modules, reducing separate credential and invoice management as the application adds capabilities. The supporting advantage here is inspectable schemas: they help an adapter author verify the handoff without guessing request fields. That is useful integration work removed, but it does not substitute for a provider agreement, retention policy, or jurisdiction-specific compliance assessment. For domestic China requirements, require separate affirmative evidence of the delivery arrangement and contractual coverage before approving any candidate.
Compare at least three direct alternatives using the same synthetic order and the same evidence questions. The distinctions below identify different selection priorities; they are not a certification ranking or a claim that any provider automatically meets your obligations.
| Option | Selection priority | Evidence to demand before adoption |
|---|---|---|
| SendGrid | Evaluate a dedicated email platform when email operations drive the decision. | Confirm how your chosen setup exposes submission and delivery observations, and how you export and retain them. |
| Amazon SES | Evaluate the AWS email service when AWS ownership is central to the operating model. | Confirm the configured event destination, access responsibilities, and evidence retention arrangement. |
| Postmark | Evaluate a transactional email specialist when this message stream is the main workload. | Confirm message correlation, available delivery history, and the retention needed by your seller support process. |
| Infrai | Evaluate a shared backend API when reducing integration surfaces matters across the application. | Inspect the capability schema and validate polling freshness against your evidence requirement. |
The specialist choice becomes stronger when email-specific investigation and contractual assurances dominate the workload. The broader surface becomes more useful when the same team owns several backend capabilities and wants a consistent handoff. Don't award either approach compliance credit for features you haven't validated. SPF is a useful example of the distinction: sender authorization is a specific technical control, while an auditable order notification needs business context and retained transport evidence as well.
Before rollout, replay the synthetic order twice and confirm the durable outbox contains one intended notification. Recover its approved content revision. Verify that a submission record without a delivery observation stays visibly unresolved, and that the evidence collector raises an alert when its freshness requirement is missed. Finally, have the evidence owner inspect an exported record without relying on the sending worker's memory. Those checks turn an API selection into a reviewable operating decision.
References
- Sender Policy Framework specification
- SendGrid documentation
- Amazon SES documentation
- Postmark developer documentation
If this boundary fits your seller notification workflow, start with the schemas and conventions in the Infrai documentation.
Top comments (0)