Programmatic SDK

Atlas can be used as a typed library in other Node.js applications. The SDK is available as a separate subpath import.

Installation

npm add m365-atlas

Creating an Instance

import { createAtlasInstance } from 'm365-atlas/sdk';

const atlas = createAtlasInstance({
  tenantId: 'your-azure-tenant-id',
  clientId: 'app-client-id',
  clientSecret: 'app-client-secret',
  s3Endpoint: 'http://localhost:9000',
  s3AccessKey: 'minioadmin',
  s3SecretKey: 'minioadmin',
  encryptionPassphrase: 'my-secret-passphrase',
});

All config is explicit -- the SDK does not read environment variables or config files. This is a deliberate security choice for multi-tenant environments: there is no risk of accidentally picking up credentials from a stale .env file or inheriting environment variables meant for a different tenant. Every value is passed explicitly at construction time.

The tenant is bound at creation time, so every method operates within that tenant scope.

The SDK uses standard ES6 camelCase naming. All methods are async and return Promises.

Available Methods

// backup a single mailbox (long-running)
const result = await atlas.backupMailbox('user@company.com', { force_full: true });

// list backed-up mailboxes
const mailboxes = await atlas.listMailboxes();

// list snapshots for a mailbox
const snapshots = await atlas.listSnapshots('user@company.com');

// verify snapshot integrity
const verification = await atlas.verifySnapshot('snapshot-id');

// restore from a specific snapshot (long-running)
const restore = await atlas.restoreSnapshot('snapshot-id', { folder_name: 'Inbox' });

// restore all snapshots for a mailbox (long-running)
const fullRestore = await atlas.restoreMailbox('user@company.com');

// save snapshot as EML zip archive
const save = await atlas.saveSnapshot('snapshot-id', {
  folder_name: 'Inbox',
  output_path: 'backup.zip',
});

// save all snapshots for a mailbox as EML zip archive
const fullSave = await atlas.saveMailbox('user@company.com', {
  output_path: 'full-backup.zip',
  skip_integrity_check: true,
});

// read a single message
const message = await atlas.readMessage('snapshot-id', 'msg-42');

// delete mailbox data
const deletion = await atlas.deleteMailboxData('user@company.com');

// check if a mailbox backup is current (fast delta peek)
const status = await atlas.checkMailboxStatus('user@company.com');
console.log(status.is_up_to_date, status.total_pending_changes);

// check storage readiness
const check = await atlas.checkStorage({ mode: 'GOVERNANCE', retention_days: 30 });

Save Options

The saveSnapshot and saveMailbox methods accept the following options:

Option	Type	Description
folder_name	string	Save only messages from this folder
message_ref	string	Save a single message by index or ID
start_date	Date	Include snapshots on or after this date
end_date	Date	Include snapshots on or before this date
output_path	string	Output zip file path (default: Restore-<timestamp>.zip)
skip_integrity_check	boolean	Skip SHA-256 verification (default: false)

Both methods return a SaveResult:

interface SaveResult {
  snapshot_id: string;
  saved_count: number;
  attachment_count: number;
  error_count: number;
  errors: string[];
  output_path: string;
  total_bytes: number;
  integrity_failures: string[];
}

Batch Processing

For backing up multiple mailboxes, the recommended approach is the CLI's built-in tenant-wide mode (atlas backup without -m), which handles parallel workers with rate limiting and a live dashboard.

For SDK usage, create one instance and iterate sequentially. Each backup/restore/save operation makes hundreds or thousands of Microsoft Graph API requests internally, so running mailboxes in parallel with Promise.all would overwhelm the Graph API and trigger aggressive throttling (HTTP 429 responses). Atlas retries throttled requests with exponential backoff up to 12 times, but parallel mailbox processing multiplies the request rate and makes throttling almost guaranteed. Sequential loops ensure reliable throughput:

const mailboxIds = ['alice@company.com', 'bob@company.com', 'carol@company.com'];

for (const mailboxId of mailboxIds) {
  const result = await atlas.backupMailbox(mailboxId);
  console.log(`${mailboxId}: snapshot ${result.snapshot.id}`);
}

Exports

The SDK exports its own types via m365-atlas/sdk. Domain types, port interfaces, and result types are available from the root m365-atlas import for advanced use cases. Status-related types (MailboxStatusResult, FolderStatus) are also exported from m365-atlas/sdk.