@serve.zone/interfaces 6.2.1 → 6.3.0

package/changelog.md

@@ -1,7 +1,19 @@
 # Changelog
 
-## Pending
+## 2026-06-05 - 6.3.0
 
+### Features
+
+- add mail interfaces and request contracts (mail)
+  - Define mail data models for resource owners, address patterns, domain authorities, bindings, credentials, spool items, delivery status, journal events, and message payloads.
+  - Add typed request contracts for mail authority and binding management, credential rotation, recipient resolution, inbound delivery, spool inspection, delivery journals, and outbound enqueueing.
+  - Export mail data and request modules and validate the mail request namespace in tests.
+
+### Fixes
+
+- update public API documentation for appstore and mail contracts (readme)
+  - Document the appstore root namespace and request group.
+  - List hostedapp and mail request groups plus mail gateway data contracts.
 
 ## 2026-05-28 - 6.2.1
 

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '6.2.1',
+    version: '6.3.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/index.d.ts

@@ -9,6 +9,7 @@ export * from './event.js';
 export * from './externalregistry.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './mail.js';
 export * from './registry.js';
 export * from './secretbundle.js';
 export * from './secretgroup.js';

package/dist_ts/data/index.js

@@ -9,6 +9,7 @@ export * from './event.js';
 export * from './externalregistry.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './mail.js';
 export * from './registry.js';
 export * from './secretbundle.js';
 export * from './secretgroup.js';
@@ -23,4 +24,4 @@ export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDIn0=

package/dist_ts/data/mail.d.ts

@@ -0,0 +1,291 @@
+export type TMailGatewayClientType = 'onebox' | 'cloudly' | 'custom' | (string & {});
+export type TMailAddressPatternType = 'exactAddress' | 'domainWildcard' | 'localPartPattern';
+export type TMailInboundTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'discard' | 'reject';
+export type TMailRecipientPolicyMode = 'acceptAll' | 'staticList' | 'cachedResolver' | 'appResolver';
+export type TMailCredentialType = 'smtp' | 'api';
+export type TMailCredentialStatus = 'active' | 'disabled' | 'rotated' | 'revoked';
+export type TMailResourceStatus = 'active' | 'disabled' | 'pending' | 'failed';
+export type TMailSpoolDirection = 'inbound' | 'outbound';
+export type TMailSpoolStatus = 'accepted' | 'queued' | 'delivering' | 'delivered' | 'deferred' | 'failed' | 'deadLettered' | 'rejected';
+export type TMailDeliveryTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'mtaRelay' | 'discard' | 'reject';
+export type TMailBounceType = 'hard' | 'soft' | 'complaint' | 'unknown';
+export type TMailInboundProtocol = 'smtp' | 'submission' | 'api';
+export type TMailRecipientResolutionAction = 'accept' | 'reject' | 'defer';
+export type TMailDeliveryJournalEventType = 'accepted' | 'queued' | 'deliveryStarted' | 'deliverySucceeded' | 'deliveryDeferred' | 'deliveryFailed' | 'deadLettered' | 'rejected' | 'bounced' | 'complaint';
+/**
+ * Runtime owner of a mail resource. `appInstanceId` is the deployed WorkApp or service
+ * instance, not an App Store template id.
+ */
+export interface IMailResourceOwner {
+    gatewayClientType: TMailGatewayClientType;
+    gatewayClientId: string;
+    appInstanceId?: string;
+}
+export interface IMailAddressPattern {
+    type: TMailAddressPatternType;
+    domain: string;
+    localPart?: string;
+    localPartPattern?: string;
+}
+export interface IMailWebhookTarget {
+    url: string;
+    signingSecretRef?: string;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+    maxInlineBytes?: number;
+}
+export interface IMailSmtpForwardTarget {
+    host: string;
+    port: number;
+    credentialRef?: string;
+    preserveHeaders?: boolean;
+    addHeaders?: Record<string, string>;
+}
+export interface IMailTypedEndpointTarget {
+    serviceRef?: string;
+    method: string;
+    queueName?: string;
+    timeoutMs?: number;
+}
+export interface IMailInboundTarget {
+    type: TMailInboundTargetType;
+    webhook?: IMailWebhookTarget;
+    smtpForward?: IMailSmtpForwardTarget;
+    typedEndpoint?: IMailTypedEndpointTarget;
+    reject?: {
+        smtpCode: number;
+        message: string;
+    };
+}
+export interface IMailRecipientResolverTarget {
+    type: 'webhook' | 'typedEndpoint';
+    webhook?: IMailWebhookTarget;
+    typedEndpoint?: IMailTypedEndpointTarget;
+}
+export interface IMailRecipientPolicy {
+    mode: TMailRecipientPolicyMode;
+    staticRecipients?: string[];
+    resolver?: IMailRecipientResolverTarget;
+    cacheTtlMs?: number;
+    unavailableResponse?: {
+        smtpCode: number;
+        message: string;
+    };
+}
+export interface IMailSpoolPolicy {
+    enabled: boolean;
+    maxRetryAgeMs?: number;
+    retentionMs?: number;
+    maxQueuedMessages?: number;
+    maxQueuedBytes?: number;
+    initialRetryDelayMs?: number;
+    maxRetryDelayMs?: number;
+    deadLetterOnExpiry?: boolean;
+}
+export interface IMailRateLimits {
+    messagesPerMinute?: number;
+    messagesPerHour?: number;
+    messagesPerDay?: number;
+    recipientsPerMessage?: number;
+}
+export interface IMailDomainAuthority {
+    id: string;
+    owner: IMailResourceOwner;
+    domain: string;
+    addressPattern: IMailAddressPattern;
+    enabled: boolean;
+    status: TMailResourceStatus;
+    inboundTarget?: IMailInboundTarget;
+    outboundPolicy?: {
+        allowedFromPatterns: IMailAddressPattern[];
+        dkimSelector?: string;
+        rateLimits?: IMailRateLimits;
+    };
+    recipientPolicy: IMailRecipientPolicy;
+    spoolPolicy?: IMailSpoolPolicy;
+    createdAt: number;
+    updatedAt: number;
+    createdBy?: string;
+}
+export interface IMailAddressBinding {
+    id: string;
+    owner: IMailResourceOwner;
+    address: string;
+    localPart: string;
+    domain: string;
+    enabled: boolean;
+    status: TMailResourceStatus;
+    inboundTarget?: IMailInboundTarget;
+    outboundIdentityId?: string;
+    recipientPolicy?: IMailRecipientPolicy;
+    spoolPolicy?: IMailSpoolPolicy;
+    createdAt: number;
+    updatedAt: number;
+    createdBy?: string;
+}
+export interface IMailCredentialPublic {
+    id: string;
+    type: TMailCredentialType;
+    status: TMailCredentialStatus;
+    username?: string;
+    scopes?: string[];
+    createdAt: number;
+    updatedAt: number;
+    lastRotatedAt?: number;
+}
+export interface IMailCredentialOneTimeSecret {
+    credential: IMailCredentialPublic;
+    secret: string;
+    secretShownOnce: true;
+}
+export interface IMailOutboundIdentity {
+    id: string;
+    owner: IMailResourceOwner;
+    enabled: boolean;
+    status: TMailResourceStatus;
+    allowedFromPatterns: IMailAddressPattern[];
+    defaultFrom?: string;
+    domain?: string;
+    dkimSelector?: string;
+    credential?: IMailCredentialPublic;
+    rateLimits?: IMailRateLimits;
+    createdAt: number;
+    updatedAt: number;
+    createdBy?: string;
+}
+export interface IWorkAppMailBinding {
+    id: string;
+    owner: IMailResourceOwner & {
+        appInstanceId: string;
+    };
+    enabled: boolean;
+    status: TMailResourceStatus;
+    domainAuthorityIds?: string[];
+    addressBindingIds?: string[];
+    outboundIdentityIds?: string[];
+    defaultFrom?: string;
+    inboundTarget?: IMailInboundTarget;
+    createdAt: number;
+    updatedAt: number;
+    createdBy?: string;
+}
+export interface IMailEnvelope {
+    mailFrom: string;
+    rcptTo: string[];
+}
+export interface IMailDeliveryTargetSummary {
+    type: TMailDeliveryTargetType;
+    label?: string;
+    address?: string;
+    url?: string;
+    host?: string;
+    port?: number;
+    serviceRef?: string;
+    method?: string;
+    queueName?: string;
+}
+export interface IMailConnectionInfo {
+    protocol: TMailInboundProtocol;
+    remoteAddress?: string;
+    proxyAddress?: string;
+    heloName?: string;
+    tls?: boolean;
+    authUsername?: string;
+    authenticatedCredentialId?: string;
+}
+export interface IMailRecipientResolution {
+    recipient: string;
+    action: TMailRecipientResolutionAction;
+    owner?: IMailResourceOwner;
+    domainAuthorityId?: string;
+    addressBindingId?: string;
+    target?: IMailInboundTarget;
+    smtpCode?: number;
+    message?: string;
+    cacheTtlMs?: number;
+}
+export interface IMailSpoolItem {
+    id: string;
+    owner?: IMailResourceOwner;
+    direction: TMailSpoolDirection;
+    status: TMailSpoolStatus;
+    envelope: IMailEnvelope;
+    messageId?: string;
+    subject?: string;
+    target?: IMailDeliveryTargetSummary;
+    attempts: number;
+    nextAttemptAt?: number;
+    lastError?: string;
+    rawAvailableUntil?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface IMailDeliveryAttempt {
+    id: string;
+    spoolItemId: string;
+    target: IMailDeliveryTargetSummary;
+    status: TMailSpoolStatus;
+    startedAt: number;
+    completedAt?: number;
+    smtpCode?: number;
+    response?: string;
+    error?: string;
+}
+export interface IMailBounceEvent {
+    id: string;
+    spoolItemId?: string;
+    owner?: IMailResourceOwner;
+    recipient: string;
+    bounceType: TMailBounceType;
+    diagnosticCode?: string;
+    receivedAt: number;
+}
+export interface IMailDeliveryStatus {
+    spoolItem?: IMailSpoolItem;
+    attempts: IMailDeliveryAttempt[];
+    bounceEvents?: IMailBounceEvent[];
+}
+export interface IMailDeliveryJournalEvent {
+    id: string;
+    spoolItemId: string;
+    owner?: IMailResourceOwner;
+    direction: TMailSpoolDirection;
+    type: TMailDeliveryJournalEventType;
+    status: TMailSpoolStatus;
+    envelope?: IMailEnvelope;
+    target?: IMailDeliveryTargetSummary;
+    attemptId?: string;
+    smtpCode?: number;
+    response?: string;
+    error?: string;
+    message?: string;
+    createdAt: number;
+}
+export interface IMailInboundMessagePayload {
+    spoolItemId: string;
+    owner?: IMailResourceOwner;
+    envelope: IMailEnvelope;
+    rawMessage: string;
+    sizeBytes?: number;
+    messageId?: string;
+    subject?: string;
+    headers?: Record<string, string | string[]>;
+    source?: IMailConnectionInfo;
+    receivedAt: number;
+}
+export interface IMailOutboundAttachmentPayload {
+    filename: string;
+    contentType?: string;
+    binaryAttachmentString: string;
+}
+export interface IMailOutboundMessagePayload {
+    from: string;
+    to: string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    headers?: Record<string, string>;
+    attachments?: IMailOutboundAttachmentPayload[];
+}

package/dist_ts/data/mail.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWFpbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvbWFpbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist_ts/requests/index.d.ts

@@ -15,6 +15,7 @@ import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
 import * as logRequests from './log.js';
+import * as mailRequests from './mail.js';
 import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
@@ -27,6 +28,7 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
 export * from './inform.js';
 export * from './hostedapp.js';
+export * from './mail.js';

package/dist_ts/requests/index.js

@@ -16,6 +16,7 @@ import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
 import * as logRequests from './log.js';
+import * as mailRequests from './mail.js';
 import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
@@ -28,7 +29,8 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
 export * from './inform.js';
 export * from './hostedapp.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGtCQUFrQixNQUFNLGlCQUFpQixDQUFDO0FBQ3RELE9BQU8sS0FBSyxXQUFXLE1BQU0sVUFBVSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyx3QkFBd0IsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRSxPQUFPLEtBQUssaUJBQWlCLE1BQU0sZ0JBQWdCLENBQUM7QUFDcEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxvQkFBb0IsTUFBTSxtQkFBbUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUVoRCxPQUFPLEVBQ0wsYUFBYSxJQUFJLEtBQUssRUFDdEIsZ0JBQWdCLElBQUksUUFBUSxFQUM1QixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLG1CQUFtQixJQUFJLFdBQVcsRUFDbEMsZUFBZSxJQUFJLE9BQU8sRUFDMUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsa0JBQWtCLElBQUksVUFBVSxFQUNoQyxXQUFXLElBQUksR0FBRyxFQUNsQixjQUFjLElBQUksTUFBTSxFQUN4Qix3QkFBd0IsSUFBSSxnQkFBZ0IsRUFDNUMsaUJBQWlCLElBQUksU0FBUyxFQUM5QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGFBQWEsSUFBSSxLQUFLLEVBQ3RCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLFdBQVcsSUFBSSxHQUFHLEVBQ2xCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUMifQ==
+export * from './mail.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGtCQUFrQixNQUFNLGlCQUFpQixDQUFDO0FBQ3RELE9BQU8sS0FBSyxXQUFXLE1BQU0sVUFBVSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyx3QkFBd0IsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRSxPQUFPLEtBQUssaUJBQWlCLE1BQU0sZ0JBQWdCLENBQUM7QUFDcEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxvQkFBb0IsTUFBTSxtQkFBbUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUVoRCxPQUFPLEVBQ0wsYUFBYSxJQUFJLEtBQUssRUFDdEIsZ0JBQWdCLElBQUksUUFBUSxFQUM1QixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLG1CQUFtQixJQUFJLFdBQVcsRUFDbEMsZUFBZSxJQUFJLE9BQU8sRUFDMUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsa0JBQWtCLElBQUksVUFBVSxFQUNoQyxXQUFXLElBQUksR0FBRyxFQUNsQixjQUFjLElBQUksTUFBTSxFQUN4Qix3QkFBd0IsSUFBSSxnQkFBZ0IsRUFDNUMsaUJBQWlCLElBQUksU0FBUyxFQUM5QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGFBQWEsSUFBSSxLQUFLLEVBQ3RCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLFdBQVcsSUFBSSxHQUFHLEVBQ2xCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxXQUFXLENBQUMifQ==

package/dist_ts/requests/mail.d.ts

@@ -0,0 +1,201 @@
+import * as plugins from '../plugins.js';
+import type { IIdentity } from '../data/user.js';
+import type { IMailAddressBinding, IMailCredentialOneTimeSecret, IMailConnectionInfo, IMailDeliveryJournalEvent, IMailDeliveryStatus, IMailDomainAuthority, IMailEnvelope, IMailInboundMessagePayload, IMailOutboundIdentity, IMailOutboundMessagePayload, IMailRecipientResolution, IMailResourceOwner, IMailSpoolItem, IWorkAppMailBinding } from '../data/mail.js';
+export interface IMailControlRequestAuth {
+    identity?: IIdentity;
+    apiToken?: string;
+}
+export interface IMailSubmissionRequestAuth extends IMailControlRequestAuth {
+    credentialId?: string;
+    credentialSecret?: string;
+}
+export type TMailDomainAuthoritySync = Omit<IMailDomainAuthority, 'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'> & {
+    id?: string;
+};
+export type TMailAddressBindingSync = Omit<IMailAddressBinding, 'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'> & {
+    id?: string;
+};
+export type TWorkAppMailBindingSync = Omit<IWorkAppMailBinding, 'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'> & {
+    id?: string;
+};
+export interface IReq_ListMailDomainAuthorities extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListMailDomainAuthorities> {
+    method: 'listMailDomainAuthorities';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner?: Partial<IMailResourceOwner>;
+        domain?: string;
+    };
+    response: {
+        authorities: IMailDomainAuthority[];
+    };
+}
+export interface IReq_SyncMailDomainAuthority extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncMailDomainAuthority> {
+    method: 'syncMailDomainAuthority';
+    request: {
+        auth: IMailControlRequestAuth;
+        authority: TMailDomainAuthoritySync;
+    };
+    response: {
+        success: boolean;
+        authority?: IMailDomainAuthority;
+        message?: string;
+    };
+}
+export interface IReq_DeleteMailDomainAuthority extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DeleteMailDomainAuthority> {
+    method: 'deleteMailDomainAuthority';
+    request: {
+        auth: IMailControlRequestAuth;
+        id: string;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}
+export interface IReq_ListMailAddressBindings extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListMailAddressBindings> {
+    method: 'listMailAddressBindings';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner?: Partial<IMailResourceOwner>;
+        domain?: string;
+        address?: string;
+    };
+    response: {
+        bindings: IMailAddressBinding[];
+    };
+}
+export interface IReq_SyncMailAddressBinding extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncMailAddressBinding> {
+    method: 'syncMailAddressBinding';
+    request: {
+        auth: IMailControlRequestAuth;
+        binding: TMailAddressBindingSync;
+    };
+    response: {
+        success: boolean;
+        binding?: IMailAddressBinding;
+        message?: string;
+    };
+}
+export interface IReq_DeleteMailAddressBinding extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DeleteMailAddressBinding> {
+    method: 'deleteMailAddressBinding';
+    request: {
+        auth: IMailControlRequestAuth;
+        id: string;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}
+export interface IReq_ListWorkAppMailBindings extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListWorkAppMailBindings> {
+    method: 'listWorkAppMailBindings';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner?: Partial<IMailResourceOwner>;
+    };
+    response: {
+        bindings: IWorkAppMailBinding[];
+    };
+}
+export interface IReq_SyncWorkAppMailBinding extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncWorkAppMailBinding> {
+    method: 'syncWorkAppMailBinding';
+    request: {
+        auth: IMailControlRequestAuth;
+        binding: TWorkAppMailBindingSync;
+    };
+    response: {
+        success: boolean;
+        binding?: IWorkAppMailBinding;
+        credentials?: IMailCredentialOneTimeSecret[];
+        message?: string;
+    };
+}
+export interface IReq_RotateMailCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_RotateMailCredential> {
+    method: 'rotateMailCredential';
+    request: {
+        auth: IMailControlRequestAuth;
+        credentialId: string;
+    };
+    response: {
+        success: boolean;
+        credential?: IMailCredentialOneTimeSecret;
+        message?: string;
+    };
+}
+export interface IReq_ResolveMailRecipients extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ResolveMailRecipients> {
+    method: 'resolveMailRecipients';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner: IMailResourceOwner;
+        domainAuthorityId?: string;
+        envelope: IMailEnvelope;
+        recipients: string[];
+        source?: IMailConnectionInfo;
+    };
+    response: {
+        resolutions: IMailRecipientResolution[];
+        cacheTtlMs?: number;
+    };
+}
+export interface IReq_DeliverInboundMail extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_DeliverInboundMail> {
+    method: 'deliverInboundMail';
+    request: {
+        auth: IMailControlRequestAuth;
+        delivery: IMailInboundMessagePayload;
+    };
+    response: {
+        accepted: boolean;
+        workAppMessageId?: string;
+        message?: string;
+    };
+}
+export interface IReq_GetMailDeliveryStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetMailDeliveryStatus> {
+    method: 'getMailDeliveryStatus';
+    request: {
+        auth: IMailControlRequestAuth;
+        spoolItemId: string;
+    };
+    response: IMailDeliveryStatus;
+}
+export interface IReq_ListMailSpoolItems extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListMailSpoolItems> {
+    method: 'listMailSpoolItems';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner?: Partial<IMailResourceOwner>;
+        status?: IMailSpoolItem['status'];
+        direction?: IMailSpoolItem['direction'];
+        limit?: number;
+    };
+    response: {
+        spoolItems: IMailSpoolItem[];
+    };
+}
+export interface IReq_ListMailDeliveryJournal extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ListMailDeliveryJournal> {
+    method: 'listMailDeliveryJournal';
+    request: {
+        auth: IMailControlRequestAuth;
+        owner?: Partial<IMailResourceOwner>;
+        spoolItemId?: string;
+        direction?: IMailSpoolItem['direction'];
+        status?: IMailSpoolItem['status'];
+        type?: IMailDeliveryJournalEvent['type'];
+        limit?: number;
+    };
+    response: {
+        events: IMailDeliveryJournalEvent[];
+    };
+}
+export interface IReq_EnqueueMail extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_EnqueueMail> {
+    method: 'enqueueMail';
+    request: {
+        auth: IMailSubmissionRequestAuth;
+        outboundIdentityId?: string;
+        message: IMailOutboundMessagePayload;
+    };
+    response: {
+        accepted: boolean;
+        spoolItemId?: string;
+        outboundIdentity?: IMailOutboundIdentity;
+        message?: string;
+    };
+}

package/dist_ts/requests/mail.js

@@ -0,0 +1,2 @@
+import * as plugins from '../plugins.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWFpbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL21haWwudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "6.2.1",
+  "version": "6.3.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -14,14 +14,15 @@ pnpm add @serve.zone/interfaces
 
 ## Public API
 
-The root export exposes four namespaces:
+The root export exposes five namespaces:
 
 ```typescript
-import { data, platform, platformservice, requests } from '@serve.zone/interfaces';
+import { appstore, data, platform, platformservice, requests } from '@serve.zone/interfaces';
 ```
 
 | Namespace | Purpose |
 | --- | --- |
+| `appstore` | App Store catalog, manifest, service requirement, and upgrade contracts. |
 | `data` | Durable platform object shapes such as clusters, services, deployments, images, domains, DNS entries, secrets, users, status, settings, backups, registries, BaseOS metadata, and task executions. |
 | `requests` | TypedRequest contracts for Cloudly and serve.zone control-plane RPC methods. |
 | `platform` | Current platform-service contracts for email, SMS, push notifications, letters, AI, databases, object storage, logging, backups, and SIP. |
@@ -71,6 +72,7 @@ Common data contracts include:
 - `IService`, `IDeployment`, `IImage`, `IRegistryTarget`, and `IExternalRegistry` for workload delivery.
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
 - `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
+- Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, credentials, spool items, delivery journals, and inbound/outbound message payloads.
 - `IUser`, `IIdentity`, and token-related contracts for authentication context.
 - `ICloudlyConfig`, `ICloudlySettings`, status, server, bare-metal, BaseOS, backup, and task execution interfaces for control-plane state.
 
@@ -99,6 +101,7 @@ interface IExampleRequest {
 Request groups are exported by product area:
 
 - `requests.admin`
+- `requests.appstore`
 - `requests.baremetal`
 - `requests.baseos`
 - `requests.backup`
@@ -109,10 +112,12 @@ Request groups are exported by product area:
 - `requests.dns`
 - `requests.domain`
 - `requests.externalRegistry`
+- `requests.hostedapp`
 - `requests.identity`
 - `requests.image`
 - `requests.inform`
 - `requests.log`
+- `requests.mail`
 - `requests.network`
 - `requests.node`
 - `requests.platform`

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '6.2.1',
+  version: '6.3.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/index.ts

@@ -9,6 +9,7 @@ export * from './event.js';
 export * from './externalregistry.js';
 export * from './hostedapp.js';
 export * from './image.js';
+export * from './mail.js';
 export * from './registry.js';
 export * from './secretbundle.js';
 export * from './secretgroup.js';

package/ts/data/mail.ts

@@ -0,0 +1,354 @@
+export type TMailGatewayClientType = 'onebox' | 'cloudly' | 'custom' | (string & {});
+
+export type TMailAddressPatternType = 'exactAddress' | 'domainWildcard' | 'localPartPattern';
+
+export type TMailInboundTargetType = 'webhook' | 'smtpForward' | 'typedEndpoint' | 'discard' | 'reject';
+
+export type TMailRecipientPolicyMode = 'acceptAll' | 'staticList' | 'cachedResolver' | 'appResolver';
+
+export type TMailCredentialType = 'smtp' | 'api';
+
+export type TMailCredentialStatus = 'active' | 'disabled' | 'rotated' | 'revoked';
+
+export type TMailResourceStatus = 'active' | 'disabled' | 'pending' | 'failed';
+
+export type TMailSpoolDirection = 'inbound' | 'outbound';
+
+export type TMailSpoolStatus =
+  | 'accepted'
+  | 'queued'
+  | 'delivering'
+  | 'delivered'
+  | 'deferred'
+  | 'failed'
+  | 'deadLettered'
+  | 'rejected';
+
+export type TMailDeliveryTargetType =
+  | 'webhook'
+  | 'smtpForward'
+  | 'typedEndpoint'
+  | 'mtaRelay'
+  | 'discard'
+  | 'reject';
+
+export type TMailBounceType = 'hard' | 'soft' | 'complaint' | 'unknown';
+
+export type TMailInboundProtocol = 'smtp' | 'submission' | 'api';
+
+export type TMailRecipientResolutionAction = 'accept' | 'reject' | 'defer';
+
+export type TMailDeliveryJournalEventType =
+  | 'accepted'
+  | 'queued'
+  | 'deliveryStarted'
+  | 'deliverySucceeded'
+  | 'deliveryDeferred'
+  | 'deliveryFailed'
+  | 'deadLettered'
+  | 'rejected'
+  | 'bounced'
+  | 'complaint';
+
+/**
+ * Runtime owner of a mail resource. `appInstanceId` is the deployed WorkApp or service
+ * instance, not an App Store template id.
+ */
+export interface IMailResourceOwner {
+  gatewayClientType: TMailGatewayClientType;
+  gatewayClientId: string;
+  appInstanceId?: string;
+}
+
+export interface IMailAddressPattern {
+  type: TMailAddressPatternType;
+  domain: string;
+  localPart?: string;
+  localPartPattern?: string;
+}
+
+export interface IMailWebhookTarget {
+  url: string;
+  signingSecretRef?: string;
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+  maxInlineBytes?: number;
+}
+
+export interface IMailSmtpForwardTarget {
+  host: string;
+  port: number;
+  credentialRef?: string;
+  preserveHeaders?: boolean;
+  addHeaders?: Record<string, string>;
+}
+
+export interface IMailTypedEndpointTarget {
+  serviceRef?: string;
+  method: string;
+  queueName?: string;
+  timeoutMs?: number;
+}
+
+export interface IMailInboundTarget {
+  type: TMailInboundTargetType;
+  webhook?: IMailWebhookTarget;
+  smtpForward?: IMailSmtpForwardTarget;
+  typedEndpoint?: IMailTypedEndpointTarget;
+  reject?: {
+    smtpCode: number;
+    message: string;
+  };
+}
+
+export interface IMailRecipientResolverTarget {
+  type: 'webhook' | 'typedEndpoint';
+  webhook?: IMailWebhookTarget;
+  typedEndpoint?: IMailTypedEndpointTarget;
+}
+
+export interface IMailRecipientPolicy {
+  mode: TMailRecipientPolicyMode;
+  staticRecipients?: string[];
+  resolver?: IMailRecipientResolverTarget;
+  cacheTtlMs?: number;
+  unavailableResponse?: {
+    smtpCode: number;
+    message: string;
+  };
+}
+
+export interface IMailSpoolPolicy {
+  enabled: boolean;
+  maxRetryAgeMs?: number;
+  retentionMs?: number;
+  maxQueuedMessages?: number;
+  maxQueuedBytes?: number;
+  initialRetryDelayMs?: number;
+  maxRetryDelayMs?: number;
+  deadLetterOnExpiry?: boolean;
+}
+
+export interface IMailRateLimits {
+  messagesPerMinute?: number;
+  messagesPerHour?: number;
+  messagesPerDay?: number;
+  recipientsPerMessage?: number;
+}
+
+export interface IMailDomainAuthority {
+  id: string;
+  owner: IMailResourceOwner;
+  domain: string;
+  addressPattern: IMailAddressPattern;
+  enabled: boolean;
+  status: TMailResourceStatus;
+  inboundTarget?: IMailInboundTarget;
+  outboundPolicy?: {
+    allowedFromPatterns: IMailAddressPattern[];
+    dkimSelector?: string;
+    rateLimits?: IMailRateLimits;
+  };
+  recipientPolicy: IMailRecipientPolicy;
+  spoolPolicy?: IMailSpoolPolicy;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface IMailAddressBinding {
+  id: string;
+  owner: IMailResourceOwner;
+  address: string;
+  localPart: string;
+  domain: string;
+  enabled: boolean;
+  status: TMailResourceStatus;
+  inboundTarget?: IMailInboundTarget;
+  outboundIdentityId?: string;
+  recipientPolicy?: IMailRecipientPolicy;
+  spoolPolicy?: IMailSpoolPolicy;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface IMailCredentialPublic {
+  id: string;
+  type: TMailCredentialType;
+  status: TMailCredentialStatus;
+  username?: string;
+  scopes?: string[];
+  createdAt: number;
+  updatedAt: number;
+  lastRotatedAt?: number;
+}
+
+export interface IMailCredentialOneTimeSecret {
+  credential: IMailCredentialPublic;
+  secret: string;
+  secretShownOnce: true;
+}
+
+export interface IMailOutboundIdentity {
+  id: string;
+  owner: IMailResourceOwner;
+  enabled: boolean;
+  status: TMailResourceStatus;
+  allowedFromPatterns: IMailAddressPattern[];
+  defaultFrom?: string;
+  domain?: string;
+  dkimSelector?: string;
+  credential?: IMailCredentialPublic;
+  rateLimits?: IMailRateLimits;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface IWorkAppMailBinding {
+  id: string;
+  owner: IMailResourceOwner & { appInstanceId: string };
+  enabled: boolean;
+  status: TMailResourceStatus;
+  domainAuthorityIds?: string[];
+  addressBindingIds?: string[];
+  outboundIdentityIds?: string[];
+  defaultFrom?: string;
+  inboundTarget?: IMailInboundTarget;
+  createdAt: number;
+  updatedAt: number;
+  createdBy?: string;
+}
+
+export interface IMailEnvelope {
+  mailFrom: string;
+  rcptTo: string[];
+}
+
+export interface IMailDeliveryTargetSummary {
+  type: TMailDeliveryTargetType;
+  label?: string;
+  address?: string;
+  url?: string;
+  host?: string;
+  port?: number;
+  serviceRef?: string;
+  method?: string;
+  queueName?: string;
+}
+
+export interface IMailConnectionInfo {
+  protocol: TMailInboundProtocol;
+  remoteAddress?: string;
+  proxyAddress?: string;
+  heloName?: string;
+  tls?: boolean;
+  authUsername?: string;
+  authenticatedCredentialId?: string;
+}
+
+export interface IMailRecipientResolution {
+  recipient: string;
+  action: TMailRecipientResolutionAction;
+  owner?: IMailResourceOwner;
+  domainAuthorityId?: string;
+  addressBindingId?: string;
+  target?: IMailInboundTarget;
+  smtpCode?: number;
+  message?: string;
+  cacheTtlMs?: number;
+}
+
+export interface IMailSpoolItem {
+  id: string;
+  owner?: IMailResourceOwner;
+  direction: TMailSpoolDirection;
+  status: TMailSpoolStatus;
+  envelope: IMailEnvelope;
+  messageId?: string;
+  subject?: string;
+  target?: IMailDeliveryTargetSummary;
+  attempts: number;
+  nextAttemptAt?: number;
+  lastError?: string;
+  rawAvailableUntil?: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface IMailDeliveryAttempt {
+  id: string;
+  spoolItemId: string;
+  target: IMailDeliveryTargetSummary;
+  status: TMailSpoolStatus;
+  startedAt: number;
+  completedAt?: number;
+  smtpCode?: number;
+  response?: string;
+  error?: string;
+}
+
+export interface IMailBounceEvent {
+  id: string;
+  spoolItemId?: string;
+  owner?: IMailResourceOwner;
+  recipient: string;
+  bounceType: TMailBounceType;
+  diagnosticCode?: string;
+  receivedAt: number;
+}
+
+export interface IMailDeliveryStatus {
+  spoolItem?: IMailSpoolItem;
+  attempts: IMailDeliveryAttempt[];
+  bounceEvents?: IMailBounceEvent[];
+}
+
+export interface IMailDeliveryJournalEvent {
+  id: string;
+  spoolItemId: string;
+  owner?: IMailResourceOwner;
+  direction: TMailSpoolDirection;
+  type: TMailDeliveryJournalEventType;
+  status: TMailSpoolStatus;
+  envelope?: IMailEnvelope;
+  target?: IMailDeliveryTargetSummary;
+  attemptId?: string;
+  smtpCode?: number;
+  response?: string;
+  error?: string;
+  message?: string;
+  createdAt: number;
+}
+
+export interface IMailInboundMessagePayload {
+  spoolItemId: string;
+  owner?: IMailResourceOwner;
+  envelope: IMailEnvelope;
+  rawMessage: string;
+  sizeBytes?: number;
+  messageId?: string;
+  subject?: string;
+  headers?: Record<string, string | string[]>;
+  source?: IMailConnectionInfo;
+  receivedAt: number;
+}
+
+export interface IMailOutboundAttachmentPayload {
+  filename: string;
+  contentType?: string;
+  binaryAttachmentString: string;
+}
+
+export interface IMailOutboundMessagePayload {
+  from: string;
+  to: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  headers?: Record<string, string>;
+  attachments?: IMailOutboundAttachmentPayload[];
+}

package/ts/requests/index.ts

@@ -17,6 +17,7 @@ import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
 import * as informRequests from './inform.js';
 import * as logRequests from './log.js';
+import * as mailRequests from './mail.js';
 import * as networkRequests from './network.js';
 import * as nodeRequests from './node.js';
 import * as platformRequests from './platform.js';
@@ -48,6 +49,7 @@ export {
   imageRequests as image,
   informRequests as inform,
   logRequests as log,
+  mailRequests as mail,
   networkRequests as network,
   nodeRequests as node,
   platformRequests as platform,
@@ -64,3 +66,4 @@ export {
 
 export * from './inform.js';
 export * from './hostedapp.js';
+export * from './mail.js';

package/ts/requests/mail.ts

@@ -0,0 +1,290 @@
+import * as plugins from '../plugins.js';
+import type { IIdentity } from '../data/user.js';
+import type {
+  IMailAddressBinding,
+  IMailCredentialOneTimeSecret,
+  IMailConnectionInfo,
+  IMailDeliveryJournalEvent,
+  IMailDeliveryStatus,
+  IMailDomainAuthority,
+  IMailEnvelope,
+  IMailInboundMessagePayload,
+  IMailOutboundIdentity,
+  IMailOutboundMessagePayload,
+  IMailRecipientResolution,
+  IMailResourceOwner,
+  IMailSpoolItem,
+  IWorkAppMailBinding,
+} from '../data/mail.js';
+
+export interface IMailControlRequestAuth {
+  identity?: IIdentity;
+  apiToken?: string;
+}
+
+export interface IMailSubmissionRequestAuth extends IMailControlRequestAuth {
+  credentialId?: string;
+  credentialSecret?: string;
+}
+
+export type TMailDomainAuthoritySync = Omit<
+  IMailDomainAuthority,
+  'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'
+> & {
+  id?: string;
+};
+
+export type TMailAddressBindingSync = Omit<
+  IMailAddressBinding,
+  'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'
+> & {
+  id?: string;
+};
+
+export type TWorkAppMailBindingSync = Omit<
+  IWorkAppMailBinding,
+  'id' | 'status' | 'createdAt' | 'updatedAt' | 'createdBy'
+> & {
+  id?: string;
+};
+
+export interface IReq_ListMailDomainAuthorities extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListMailDomainAuthorities
+> {
+  method: 'listMailDomainAuthorities';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner?: Partial<IMailResourceOwner>;
+    domain?: string;
+  };
+  response: {
+    authorities: IMailDomainAuthority[];
+  };
+}
+
+export interface IReq_SyncMailDomainAuthority extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SyncMailDomainAuthority
+> {
+  method: 'syncMailDomainAuthority';
+  request: {
+    auth: IMailControlRequestAuth;
+    authority: TMailDomainAuthoritySync;
+  };
+  response: {
+    success: boolean;
+    authority?: IMailDomainAuthority;
+    message?: string;
+  };
+}
+
+export interface IReq_DeleteMailDomainAuthority extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_DeleteMailDomainAuthority
+> {
+  method: 'deleteMailDomainAuthority';
+  request: {
+    auth: IMailControlRequestAuth;
+    id: string;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
+export interface IReq_ListMailAddressBindings extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListMailAddressBindings
+> {
+  method: 'listMailAddressBindings';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner?: Partial<IMailResourceOwner>;
+    domain?: string;
+    address?: string;
+  };
+  response: {
+    bindings: IMailAddressBinding[];
+  };
+}
+
+export interface IReq_SyncMailAddressBinding extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SyncMailAddressBinding
+> {
+  method: 'syncMailAddressBinding';
+  request: {
+    auth: IMailControlRequestAuth;
+    binding: TMailAddressBindingSync;
+  };
+  response: {
+    success: boolean;
+    binding?: IMailAddressBinding;
+    message?: string;
+  };
+}
+
+export interface IReq_DeleteMailAddressBinding extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_DeleteMailAddressBinding
+> {
+  method: 'deleteMailAddressBinding';
+  request: {
+    auth: IMailControlRequestAuth;
+    id: string;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}
+
+export interface IReq_ListWorkAppMailBindings extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListWorkAppMailBindings
+> {
+  method: 'listWorkAppMailBindings';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner?: Partial<IMailResourceOwner>;
+  };
+  response: {
+    bindings: IWorkAppMailBinding[];
+  };
+}
+
+export interface IReq_SyncWorkAppMailBinding extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SyncWorkAppMailBinding
+> {
+  method: 'syncWorkAppMailBinding';
+  request: {
+    auth: IMailControlRequestAuth;
+    binding: TWorkAppMailBindingSync;
+  };
+  response: {
+    success: boolean;
+    binding?: IWorkAppMailBinding;
+    credentials?: IMailCredentialOneTimeSecret[];
+    message?: string;
+  };
+}
+
+export interface IReq_RotateMailCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_RotateMailCredential
+> {
+  method: 'rotateMailCredential';
+  request: {
+    auth: IMailControlRequestAuth;
+    credentialId: string;
+  };
+  response: {
+    success: boolean;
+    credential?: IMailCredentialOneTimeSecret;
+    message?: string;
+  };
+}
+
+export interface IReq_ResolveMailRecipients extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ResolveMailRecipients
+> {
+  method: 'resolveMailRecipients';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner: IMailResourceOwner;
+    domainAuthorityId?: string;
+    envelope: IMailEnvelope;
+    recipients: string[];
+    source?: IMailConnectionInfo;
+  };
+  response: {
+    resolutions: IMailRecipientResolution[];
+    cacheTtlMs?: number;
+  };
+}
+
+export interface IReq_DeliverInboundMail extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_DeliverInboundMail
+> {
+  method: 'deliverInboundMail';
+  request: {
+    auth: IMailControlRequestAuth;
+    delivery: IMailInboundMessagePayload;
+  };
+  response: {
+    accepted: boolean;
+    workAppMessageId?: string;
+    message?: string;
+  };
+}
+
+export interface IReq_GetMailDeliveryStatus extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetMailDeliveryStatus
+> {
+  method: 'getMailDeliveryStatus';
+  request: {
+    auth: IMailControlRequestAuth;
+    spoolItemId: string;
+  };
+  response: IMailDeliveryStatus;
+}
+
+export interface IReq_ListMailSpoolItems extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListMailSpoolItems
+> {
+  method: 'listMailSpoolItems';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner?: Partial<IMailResourceOwner>;
+    status?: IMailSpoolItem['status'];
+    direction?: IMailSpoolItem['direction'];
+    limit?: number;
+  };
+  response: {
+    spoolItems: IMailSpoolItem[];
+  };
+}
+
+export interface IReq_ListMailDeliveryJournal extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ListMailDeliveryJournal
+> {
+  method: 'listMailDeliveryJournal';
+  request: {
+    auth: IMailControlRequestAuth;
+    owner?: Partial<IMailResourceOwner>;
+    spoolItemId?: string;
+    direction?: IMailSpoolItem['direction'];
+    status?: IMailSpoolItem['status'];
+    type?: IMailDeliveryJournalEvent['type'];
+    limit?: number;
+  };
+  response: {
+    events: IMailDeliveryJournalEvent[];
+  };
+}
+
+export interface IReq_EnqueueMail extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_EnqueueMail
+> {
+  method: 'enqueueMail';
+  request: {
+    auth: IMailSubmissionRequestAuth;
+    outboundIdentityId?: string;
+    message: IMailOutboundMessagePayload;
+  };
+  response: {
+    accepted: boolean;
+    spoolItemId?: string;
+    outboundIdentity?: IMailOutboundIdentity;
+    message?: string;
+  };
+}