Skip to content
ContractSpec
Start here

Package manual · integrations

·Integrations and provider selection

integration.provider-email

Email provider implementations for ContractSpec.

integrationsintegrationv3.0.5stableservernode
@lssm-tech/integration.provider-email
bun add @lssm-tech/integration.provider-email
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

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. Its additive getMessageMetadata method is compatible with gmail.metadata: only From/Subject/Date headers, provider receipt time, IDs and labels are requested and returned. Message snippets, bodies and attachment data are never included; deleted messages return null and a missing provider time stays absent.
  • 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:

ts
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.

Gmail convergence (TS-01-P-EMAIL)

  • GmailReadonlyReader (./impls/gmail-readonly-reader): scope-gated gmail.readonly list/history/message/profile with bounded requests, RFC 2047 subjects, bounded plain-text excerpts and history_expired → full resync.
  • GmailDelivery (./impls/gmail-delivery): one-attempt send of fixed MIME bytes (caller Message-ID + sha256), outcomes accepted/rejected/uncertain, findSentByMessageId and read-only reconcile.
  • createGmailControlledMailbox (./impls/gmail-fixture): zero-network controlled mailbox serving the Gmail REST routes through an injected fetch (tests and fixture qualification only).

Relationships

THIS PACKAGEintegration.provider-email32 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

4 declarations

Declared capabilities

Integration Provider Email

Email provider implementations for ContractSpec.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lint:checknode ../../../scripts/biome.cjs check .
  • lint:fixnode ../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit