AbsoluteJS

Email

@absolutejs/emailv0.1.0alphaMessaging

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

Provider-neutral email sync adapters for AbsoluteJS applications.

This package owns the provider mechanics:

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

Show 9 more

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

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

Provider-neutral email sync adapters for AbsoluteJS applications.

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.

#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",
});

#Microsoft Graph

Partial snippet

Working example for Microsoft Graph.

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",
});

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

52 symbols
bulkSignalsFromHeadersexportPermalink
TS
bulkSignalsFromHeaders
Exported from @absolutejs/email

Current package surface

What ships today

@absolutejs/emailv0.1.0 · betaMessagingnpmSource
3entry points54symbols

Import surface · click to copy