Keep vendor formats out of business code
The framework’s email and SMS paths use common message contracts. Provider modules translate those messages into their vendor’s request format and interpret the response back into a shared result.
Your product can keep its message intent while the integration owns authentication, encoding and vendor-specific response meaning.
Example — The same message through a different email provider
An invitation still has recipients, a subject and content when its email provider changes. The selected module builds the vendor request; the application does not add another vendor-shaped payload to the invitation flow.
For engineers
Distinguish the application call from the provider request
The application’s email service starts from a registered template, recipients and context. After rendering, it creates the standard provider request. This illustrative object shows that lower-level contract, not a replacement for the template service:
import type { StandardEmail_SendRequest } from '@wildo-ai/external-connectors-models';
const submission: StandardEmail_SendRequest = {
submissionId: 'invitation-example-001',
to: [{ email: 'reader@example.com' }],
from: { email: 'notifications@example.com', name: 'Example product' },
subject: 'Your invitation',
text: 'You have been invited to join the workspace.',
headers: { 'X-Product-Message': 'invitation' },
};
For real delivery, use a verified sender and an appropriate stable identity for the logical submission. A fixed example identifier must not be reused for unrelated messages. submissionId supports correlation across retries; it does not promise every provider offers exactly-once delivery.
Keep transport and message headers separate
Resend’s request builder maps message fields into its JSON payload and places the submission identity in a transport header. The relevant ending is:
payload: {
headers: request.headers,
tags: request.tags?.map((tag) => ({ name: tag, value: tag })),
scheduled_at: request.scheduledAt,
},
transportHeaders: {
'Idempotency-Key': request.submissionId,
},
The API header authenticating or identifying the submission is distinct from headers carried inside the email. The engine serializes the builder’s declared payload encoding; callers do not branch on the vendor name to produce a different body.
Interpret acceptance at the provider boundary
The provider response parser translates receipt details into a shared submission classification. Accepted, rejected and acceptance-unknown are different results: a successful submission receipt is not proof that a person received or read the email. The non-delivering preview provider uses its own delivery contract rather than pretending a network send occurred.
Standard email and SMS contracts do not make every optional vendor feature identical. Select a provider appropriate to the needed operation, credentials and message shape. Other integration families, such as billing and models, have their own runtime contracts rather than this message contract.