Mail.js | Arcane OS SDK

On this page

Overview

Builds complete reports and prefers the native mail capability with an explicit HTTP transport fallback.

Artifact
Mail.js · esm
Classification
public first party
Availability
Browser/native hybrid + cloud
Normalization
Mail inputs/results normalized; transport failures mixed.

Import and lifecycle

JavaScript

import * as module from '/arcane/modules/Mail.js';

Import installs window.mail once when window exists. After installation, every later new Mail(config) returns that existing singleton and ignores the new config. send() builds complete content, prefers native delivery, otherwise uses MailTransport; report/crisis formatting may lazily load User/DBOPFS and best-effort persist a report before delivery.

Application-facing behavior: default Mail, resolveMailConfig(); installs window.mail; send().

Protocol and host implementation

Arcane.mail.send or MailTransport HTTP(S) This detail does not widen the application-facing API or grant authority.

Exports, signatures, parameters, and results

Binding	Form	Declaration or signature	Parameter syntax
`resolveMailConfig`	function	`function resolveMailConfig( config=globalThis.arcane?.config?.mail\|\|{}, {document=globalThis.document,location=globalThis.location}={} )`	`config=globalThis.arcane?.config?.mail\|\|{}, {document=globalThis.document,location=globalThis.location}={}`
`default`	default · class	`class Mail`	`—`

Callable	Kind	Exact public signature	Parameter syntax
`resolveMailConfig`	exported-function	`function resolveMailConfig( config=globalThis.arcane?.config?.mail\|\|{}, {document=globalThis.document,location=globalThis.location}={} )`	`config=globalThis.arcane?.config?.mail\|\|{}, {document=globalThis.document,location=globalThis.location}={}`
`Mail.send`	public-member	`async send(to=[], subject='', payload={}, messageStyle='', messageType='')`	`to=[], subject='', payload={}, messageStyle='', messageType=''`

Member	Kind	Exact public declaration	Parameter syntax
`Mail.constructor`	constructor	`constructor(config=globalThis.arcane?.config?.mail\|\|{},options={})`	`config=globalThis.arcane?.config?.mail\|\|{},options={}`
`Mail.started`	get	`get started()`	`—`
`Mail.disposed`	get	`get disposed()`	`—`
`Mail.events`	get	`get events()`	`—`
`Mail.invalidOutboxRecords`	get	`get invalidOutboxRecords()`	`—`
`Mail.lastBackgroundError`	get	`get lastBackgroundError()`	`—`
`Mail.start`	async method	`async start({signal=null}={})`	`{signal=null}={}`
`Mail.drain`	async method	`async drain({reason='manual',signal=null}={})`	`{reason='manual',signal=null}={}`
`Mail.listOutbox`	async method	`async listOutbox()`	`—`
`Mail.auditOutbox`	async method	`async auditOutbox()`	`—`
`Mail.getOutboxRecord`	async method	`async getOutboxRecord(reportKey)`	`reportKey`
`Mail.deleteInvalidOutbox`	async method	`async deleteInvalidOutbox(fileName)`	`fileName`
`Mail.repairInvalidOutbox`	async method	`async repairInvalidOutbox(fileName,replacement)`	`fileName,replacement`
`Mail.quarantineInvalidOutbox`	async method	`async quarantineInvalidOutbox()`	`—`
`Mail.stop`	method	`stop()`	`—`
`Mail.dispose`	method	`dispose()`	`—`
`Mail.send`	async method	`async send(to=[], subject='', payload={}, messageStyle='', messageType='')`	`to=[], subject='', payload={}, messageStyle='', messageType=''`

Parameter meanings and results

resolveMailConfig(config,{document,location}) returns {appName,appKey,endpoint,requestTimeout}. The first new Mail(config) owns singleton configuration in a browser window; send(to[],subject,payload,messageStyle,messageType:'error'|'report'|'crisis_detected') resolves the transport result plus reportKey without content-size or recipient-count gates.

Events, side effects, and errors

Source-literal `CustomEvent` dispatches

No source-literal CustomEvent dispatch is part of this artifact.

Lifecycle and event flow

This artifact has no additional documented lifecycle event flow.

Direct coded failures

This artifact directly assigns no stable coded failure.

Exported Error subclasses

This artifact exports no Error subclass.

Documented failure behavior

Uncoded TypeError or structured-clone/serialization failure for malformed recipients, subject, payload, type, or configuration.
Native or HTTP transport rejection propagates; optional profile/storage failures are logged and contained.

Availability and capabilities

Browser/native hybrid + cloud. Mail inputs/results normalized; transport failures mixed.

Preferred Arcane.mail.send requires mail.send, is Core-only, and is limited to Precrisis/Warrior Spirit. HTTP fallback has caller-configured network authority.

Contract example