AbsoluteJS

Email

@absolutejs/emailv0.7.1alphaMessaging

Gmail, Microsoft Graph, and IMAP sync clients that return one normalized message shape.

Provider-neutral email sync adapters for AbsoluteJS applications, covering Gmail REST sync, Microsoft Graph delta sync, and IMAP over TLS. The package owns the provider mechanics — history and delta cursors, webhook payload parsing, and normalized message shapes — while your host app keeps ownership of consent, credential storage, persistence, and scheduling. Normalized messages come out in one shape regardless of provider, ready to persist, score, filter, or enrich.

#Installation

BASH
bun add @absolutejs/email

#Capabilities

Overview

The Gmail adapter can also locate a tagged delivery canary across Inbox, Spam, Trash, and other labels with findGmailMessagePlacement. The host application owns canary scheduling, mailbox credentials, alert policy, and persistence.

Provider-neutral email sync adapters for AbsoluteJS applications.

This package owns the provider mechanics:

Show 10 more

Gmail REST sync, users.watch, and Pub/Sub payload parsing

Microsoft Graph message delta sync and subscription notification parsing

IMAP over TLS for custom mailbox providers

Normalized message shapes that host apps can persist, score, filter, or enrich

Host applications own product policy:

user consent and privacy controls

credential storage

business-specific relevance scoring

database persistence

queue scheduling and UI

Tool-confined verification codes

@absolutejs/email/verification provides deterministic Gmail, Microsoft Graph, and IMAP lookups plus a strict parser for Agent Exchange source adapters. It is a library API, deliberately absent from the package's model-facing manifest tools.

The main verification entry point is browser-safe for Gmail and Microsoft Graph. Import the server-only IMAP lookup from @absolutejs/email/verification/imap so browser bundles never pull in Node TLS or imapflow.

Profiles bind a mailbox lookup to exact HTTPS origins, provider names, sender addresses, trusted RFC 8601 authentication services, aligned DMARC results, subject markers, body markers, a short time window, and one code length. Retrieval fails closed on missing or duplicated authentication evidence, unavailable candidates, excessive candidate/body sizes, no match, more than one matching message, or more than one marker-bound code occurrence.

Show 2 more

trustedAuthservIds is deployment-specific. Configure only the authserv-id inserted inside your mailbox provider's trusted boundary; never copy an untrusted Authentication-Results header from farther upstream. The required DMARC pass must align exactly with both the visible sender domain and an allowlisted domain. For cross-agent requests, also pass an unpredictable request challenge through requiredBodyText; time-only correlation is weaker.

Email codes remain bearer values and are not phishing-resistant. Prefer OAuth, passkeys, or provider-native delegated actions whenever the upstream service supports them.

Inbound mail (Resend)

Resend's email.received webhook carries metadata only; the body and headers come from the receiving API. resolveResendInboundEmail does both and returns a provider-neutral InboundEmailMessage. stripQuotedReply isolates the sender's own words (quoted history, signatures, mobile sign-offs and Outlook header blocks removed) so a host can act on a reply or preview it.

IMAP

Verification profiles may opt into codeLayout: "standalone-after-marker" for messages that display the code on its own line after introductory text. An exact configured body marker must precede the code within 512 characters. Multiple codes or matching messages remain ambiguous and fail closed. Sender authentication, recipient, service origin, subject, time window and candidate limits still apply. Gmail and Microsoft HTML normalization preserves block boundaries for this layout. The default layout remains a code immediately following its configured marker.

Gmail sync

createGmailClient handles Gmail REST history sync, users.watch registration, and Pub/Sub webhook payload parsing via parseGmailPubSubWebhook.

Microsoft Graph sync

createMicrosoftGraphEmailClient drives Graph message delta sync and parses subscription notifications for Microsoft 365 mailboxes.

IMAP over TLS

fetchImapMessages pulls mail over IMAP with TLS for Fastmail, self-hosted, and other custom mailbox providers.

Normalized message shapes

gmailMessagesToNormalized and microsoftMessagesToNormalized convert provider payloads into one message shape your app can persist or score.

Host app owns policy

The package never touches credential storage, consent, relevance scoring, or persistence — those stay in your application where product policy belongs.

Outcomes

What you can build

Overview

The Gmail adapter can also locate a tagged delivery canary across Inbox, Spam, Trash, and other labels with findGmailMessagePlacement. The host application owns canary scheduling, mailbox credentials, alert policy, and persistence.

Tool-confined verification codes

@absolutejs/email/verification provides deterministic Gmail, Microsoft Graph, and IMAP lookups plus a strict parser for Agent Exchange source adapters. It is a library API, deliberately absent from the package's model-facing manifest tools.

Inbound mail (Resend)

Resend's email.received webhook carries metadata only; the body and headers come from the receiving API. resolveResendInboundEmail does both and returns a provider-neutral InboundEmailMessage. stripQuotedReply isolates the sender's own words (quoted history, signatures, mobile sign-offs and Outlook header blocks removed) so a host can act on a reply or preview it.

Hardening checklist

Production guidance

Make every external boundary explicitPin the deployed @absolutejs/email version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.

Follow in order

Troubleshooting path

1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/email example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#Tool-confined verification codes

Partial snippet

@absolutejs/email/verification provides deterministic Gmail, Microsoft Graph, and IMAP lookups plus a strict parser for Agent Exchange source adapters. It is a library API, deliberately absent from the package's model-facing manifest tools.

TS
import {
  createGmailVerificationMessageLookup,
  retrieveEmailVerificationCode,
} from "@absolutejs/email/verification";

const result = await retrieveEmailVerificationCode(
  createGmailVerificationMessageLookup({ accountEmail, client: gmail }),
  {
    accountEmail,
    expectedOrigin: "https://accounts.example.com",
    notBefore: new Date(requestCreatedAt),
    notAfter: new Date(requestExpiresAt),
    profile: {
      bodyMarkers: ["verification code"],
      id: "accounts-example-six-digit-v1",
      origins: ["https://accounts.example.com"],
      providers: ["gmail"],
      senderAddresses: ["security@example.com"],
      senderAuthentication: {
        allowedHeaderFromDomains: ["example.com"],
        trustedAuthservIds: ["mx.mailbox.example"],
      },
      subjectIncludesAny: ["sign in"],
    },
  },
);

// Pass result.bytes directly to a trusted sink or E2EE envelope. Do not stringify
// it, log it, add it to a prompt, or return it from an agent tool.
result.bytes.fill(0);

#Gmail

Partial snippet

Working example for Gmail.

TS
import {
  createGmailClient,
  gmailMessagesToNormalized,
  parseGmailPubSubWebhook,
} from "@absolutejs/email";

const client = createGmailClient({ accessToken });
const { messages, cursor } = await client.listHistory({ cursor: historyId });
const normalized = await gmailMessagesToNormalized(client, messages, {
  accountEmail: "member@example.com",
});

#Quick Start (Gmail)

Partial snippet

Sync a Gmail mailbox from a history cursor and normalize the results. Persist the returned cursor and pass it back on the next sync.

TS
import {
	createGmailClient,
	gmailMessagesToNormalized
} from '@absolutejs/email';

const client = createGmailClient({ accessToken });

const { messages, cursor } = await client.listHistory({
	cursor: historyId
});

const normalized = await gmailMessagesToNormalized(client, messages, {
	accountEmail: 'member@example.com'
});

#Microsoft Graph

Partial snippet

Microsoft 365 mailboxes sync through Graph delta queries — the first listDelta call returns everything plus a delta cursor for incremental follow-ups.

TS
import {
	createMicrosoftGraphEmailClient,
	microsoftMessagesToNormalized
} from '@absolutejs/email';

const client = createMicrosoftGraphEmailClient({ accessToken });
const { messages, cursor } = await client.listDelta();

const normalized = microsoftMessagesToNormalized(messages, {
	accountEmail: 'member@example.com'
});

#IMAP

Partial snippet

For providers without a REST API, fetchImapMessages connects over IMAP with TLS and returns messages in the same normalized shape.

TS
import { fetchImapMessages } from '@absolutejs/email';

const result = await fetchImapMessages({
	accountEmail: 'member@example.com',
	auth: { pass: appPassword, user: 'member@example.com' },
	host: 'imap.fastmail.com',
	port: 993,
	secure: true
});
Early alpha
@absolutejs/email is pre-1.0 — client options and normalized message shapes may change between minor releases while the adapters harden against real provider traffic.

#API reference

Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.

80 symbols
bulkSignalsFromHeadersexportPermalink
TS
bulkSignalsFromHeaders
Exported from @absolutejs/email

Current package surface

What ships today

@absolutejs/emailv0.7.1 · betaMessagingnpmSource
5entry points94symbols

Import surface · click to copy