integration.provider-email

@lssm-tech/integration.provider-email

Website: https://contractspec.io

Email provider implementations for ContractSpec.

Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the ./impls/* subpaths.

Included Providers

• GmailInboundProvider for thread and message sync. listThreadsPage keeps the provider continuation; message metadata records timestampSource (provider_internal_date, date_header or observed_at_fetch) instead of presenting a fetch time as an observed provider time, and attachments are referenced by stable MIME part id (the Gmail attachment handle is volatile).
• GmailMailboxReader (./impls/gmail-mailbox-reader) is the read port for durable synchronization: mailbox profile and history baseline, keyed message paging, history changes (added, deleted, label changes) with a typed history_expired failure, and verified send-as identities. A message payload that cannot be transformed raises non-retryable payload_invalid.
• createDeferredGmailOAuth2Client (./impls/gmail-auth) loads the mailbox credential from custody on first use and on every refresh (a reconnect is picked up, no refresh token in configuration); a missing credential is reauthorization_required.
• GmailAttachmentOriginalReader (./impls/gmail-attachments) acquires original attachment bytes by message + part identity with size bounds and a SHA-256 digest, producing a GmailAttachmentOriginalHandOff record (./impls/gmail-evidence) for the document-custody port. Equal bytes from two mailboxes share a digest but keep separate account-bound source keys.
• GmailOutboundProvider for Gmail-based outbound delivery. Messages are built by ./impls/gmail-mime (RFC 2047 Unicode headers, Bcc, base64 parts); caller headers cannot set sender or envelope fields. Metadata gmailThreadId, gmailInReplyTo and gmailReferences produce a correctly threaded reply. A response without a message id raises response_unverified.
• GmailMailboxOperations (./impls/gmail-mailbox) for native drafts (create/update/get/send), label changes, archive (removes INBOX only) and read state. These are provider drivers; agent-initiated calls must arrive through Runtime Node authority.
• parseGmailPushNotification and GmailWatchOperations (./impls/gmail-push) treat Gmail push as a wake signal only; changes are fetched through history.
• MicrosoftGraphOutboundProvider for delegated Microsoft user mail. Graph 202 Accepted is represented as queued acceptance without a provider message id; ambiguous responses retain only sanitized diagnostic correlations.
• MicrosoftGraphInboundProvider for folder-scoped message delta sync. Complete opaque next/delta links are mailbox-bound, and deletion tombstones remain explicit reconciliation inputs.
• MicrosoftGraphMessageSubscriptionManager for bounded create, renewal, and deletion of Outlook message subscriptions. Notification batches require exact subscription/client-state binding; missed lifecycle events require delta sync.
• PostmarkEmailProvider for transactional email delivery
• ResendEmailProvider for outbound delivery with provider-native retry idempotency through a bounded EmailOutboundMessage.idempotencyKey
• MailerSendEmailProvider for outbound text, HTML, template, scheduled, bulk, personalized, tagged, header, CC/BCC/reply-to, and inline/regular attachment delivery through the official MailerSend REST API
• MailerSendInboundProvider for official inbound-route list/get/create/update/ delete operations with email and webhook forwards
• ingestMailerSendWebhook and authenticateMailerSendWebhook for raw-body HMAC-SHA256 verification, delivery receipts, inbound MIME projections, test callbacks, replay suppression, and non-regressing delivery status
• ingestResendWebhook for raw-body signature verification and svix-id replay deduplication plus non-regressing provider-message status projection through a caller-owned atomic event store. Results expose only a deterministic provider-message:sha256:* reference; raw provider message ids remain transient.
• SqlResendWebhookEventStore (./impls/resend-webhook-sql-store) is the durable SQL implementation of that store for a pg-compatible pool (no pg dependency): one transaction inserts into the host's replay ledger, rejects an event id reused for different content, advances the per-message status only for a higher RESEND_DELIVERY_STATUS_RANKS rank or a later equal-rank event, and runs an optional onStatusApplied host hook in the same transaction. Hosts own the two tables (validated plain identifiers) and their migrations; every failure surfaces as retryable ResendWebhookStoreUnavailableError.

MailerSend

Use the focused exports so browser bundles never pull server-only provider code:

import { MailerSendEmailProvider } from
  "@lssm-tech/integration.provider-email/impls/mailersend-email";
import { MailerSendInboundProvider } from
  "@lssm-tech/integration.provider-email/impls/mailersend-inbound";
import { ingestMailerSendWebhook } from
  "@lssm-tech/integration.provider-email/impls/mailersend-webhook";

The caller supplies apiKey and may inject baseUrl and fetch. Credentials must remain in a server-side vault; provider errors expose only status and a normalized code. Webhooks must pass the exact raw request body and Signature header with the endpoint signing secret. A successful handler should respond within three seconds; durable stores must deduplicate event ids because MailerSend retries failed delivery.

Inbound webhook projections preserve text, HTML, raw MIME, recipients, headers, SPF/DKIM results, and inline/regular attachments. Application code remains responsible for retention, attachment storage, malware scanning, and workspace policy before content enters CommunicationOS projections or AI context.

Compatibility

This package owns the email implementation slice split out of @lssm-tech/integration.providers-impls. The legacy package continues to re-export these subpaths for existing consumers.