// Wildduck API Type Definitions // REST API request and response types based on Joi schemas export namespace Wildduck { // ============================================================================ // Common API Types // ============================================================================ /** * Base API response structure * All API responses include success field */ export interface WildduckAPIResponse { success: boolean; error?: string; code?: string; } /** * API error response */ export interface WildduckAPIErrorResponse { success: false; error: string; code: string; details?: Array<{ message: string; path: string[]; type: string; }>; } /** * Paginated API response with cursor-based pagination */ export interface WildduckPaginatedResponse extends WildduckAPIResponse { success: true; total: number; page: number; previousCursor: string | false; nextCursor: string | false; results: T[]; } /** * Quota information */ export interface WildduckQuota { allowed: number; used: number; } // ============================================================================ // User API Types // ============================================================================ /** * User list item response (GET /users) */ export interface WildduckGetUsersResultItem { id: string; username: string; name: string; address: string; tags: string[]; targets: string[]; enabled2fa: string[]; autoreply: boolean; encryptMessages: boolean; encryptForwarded: boolean; quota: WildduckQuota; hasPasswordSet: boolean; activated: boolean; disabled: boolean; suspended: boolean; metaData?: Record; internalData?: Record; } /** * GET /users response */ export interface WildduckGetUsersResponse extends WildduckPaginatedResponse { query: string; } /** * POST /users request body */ export interface WildduckCreateUserRequest { username: string; password: string | false; hashedPassword?: boolean; allowUnsafe?: boolean; address?: string; name?: string; quota?: number; retention?: number; enabled2fa?: string[]; disabledScopes?: string[]; tags?: string[]; addTagsToAddress?: boolean; uploadSentMessages?: boolean; encryptMessages?: boolean; encryptForwarded?: boolean; pubKey?: string; metaData?: Record; internalData?: Record; sess?: string; ip?: string; } /** * POST /users response */ export interface WildduckCreateUserResponse extends WildduckAPIResponse { success: true; id: string; } /** * GET /users/:id response */ export interface WildduckGetUserResponse extends WildduckAPIResponse { success: true; id: string; username: string; name: string; address: string; retention: number; enabled2fa: string[]; disabledScopes: string[]; quota: WildduckQuota; tags: string[]; targets: string[]; encryptMessages: boolean; encryptForwarded: boolean; pubKey?: string; metaData?: Record; internalData?: Record; hasPasswordSet: boolean; activated: boolean; disabled: boolean; suspended: boolean; } /** * PUT /users/:id request body */ export interface WildduckUpdateUserRequest { name?: string; password?: string | false; hashedPassword?: boolean; allowUnsafe?: boolean; quota?: number; retention?: number; enabled2fa?: string[]; disabledScopes?: string[]; tags?: string[]; encryptMessages?: boolean; encryptForwarded?: boolean; pubKey?: string; metaData?: Record; internalData?: Record; disabled?: boolean; suspended?: boolean; sess?: string; ip?: string; } // ============================================================================ // Address API Types // ============================================================================ /** * Address list item response (GET /addresses) */ export interface WildduckGetAddressesResultItem { id: string; name?: string; address: string; user: string; forwarded: boolean; forwardedDisabled: boolean; targets?: string[]; tags: string[]; metaData?: Record; internalData?: Record; } /** * User address list item response (GET /users/:id/addresses) */ export interface WildduckGetUserAddressesResultItem { id: string; name?: string; address: string; main: boolean; created: Date; tags: string[]; metaData?: Record; internalData?: Record; } /** * Address forwarding limits */ export interface WildduckAddressLimits { forwards: { allowed: number; used: number; ttl: number; }; } /** * Autoreply information */ export interface WildduckAutoreplyInfo { status: boolean; name?: string; subject?: string; text?: string; html?: string; } /** * Autoreply request body */ export interface WildduckAutoreplyRequest { status?: boolean; start?: Date | false; end?: Date | false; name?: string; subject?: string; text?: string; html?: string; } /** * POST /users/:id/addresses request body */ export interface WildduckCreateAddressRequest { address: string; name?: string; main?: boolean; tags?: string[]; metaData?: Record; internalData?: Record; sess?: string; ip?: string; } // ============================================================================ // Mailbox API Types // ============================================================================ /** * Mailbox list item response (GET /users/:id/mailboxes) */ export interface WildduckGetMailboxesResultItem { id: string; name: string; path: string; specialUse: string; modifyIndex: number; subscribed: boolean; retention?: number; hidden: boolean; encryptMessages: boolean; total: number; unseen: number; size?: number; } /** * GET /users/:id/mailboxes response */ export interface WildduckGetMailboxesResponse extends WildduckAPIResponse { success: true; results: WildduckGetMailboxesResultItem[]; } /** * POST /users/:id/mailboxes request body */ export interface WildduckCreateMailboxRequest { path: string; hidden?: boolean; retention?: number; subscribed?: boolean; sess?: string; ip?: string; } /** * POST /users/:id/mailboxes response */ export interface WildduckCreateMailboxResponse extends WildduckAPIResponse { success: true; id: string; } /** * PUT /users/:id/mailboxes/:mailbox request body */ export interface WildduckUpdateMailboxRequest { path?: string; retention?: number; subscribed?: boolean; hidden?: boolean; sess?: string; ip?: string; } // ============================================================================ // Message API Types // ============================================================================ /** * SMTP envelope (for message delivery tracking) */ export interface WildduckSMTPEnvelope { from: string; rcpt: Array<{ value: string; formatted: string; }>; } /** * Message address (for composition) */ export interface WildduckMessageAddress { name?: string; address: string; } /** * Message header */ export interface WildduckMessageHeader { key: string; value: string; } /** * Message attachment (for composition) */ export interface WildduckMessageAttachment { filename?: string; contentType?: string; encoding?: string; contentTransferEncoding?: string; content: string; cid?: string; contentDisposition?: 'inline' | 'attachment'; } /** * Message reference (for reply/forward) */ export interface WildduckMessageReference { mailbox: string; id: number; action: 'reply' | 'replyAll' | 'forward'; attachments?: boolean | string[]; } /** * BIMI configuration */ export interface WildduckMessageBimi { domain: string; selector?: string; } /** * POST /users/:id/mailboxes/:mailbox/messages request body */ export interface WildduckUploadMessageRequest { date?: Date; flags?: string[]; raw?: string; sess?: string; ip?: string; } /** * POST /users/:id/submit request body (send message) */ export interface WildduckSubmitMessageRequest { reference?: WildduckMessageReference; mailbox?: string; uploadOnly?: boolean; sendTime?: Date; from?: WildduckMessageAddress; to?: WildduckMessageAddress[]; cc?: WildduckMessageAddress[]; bcc?: WildduckMessageAddress[]; subject?: string; text?: string; html?: string; headers?: WildduckMessageHeader[]; attachments?: WildduckMessageAttachment[]; files?: string[]; bimi?: WildduckMessageBimi; sess?: string; ip?: string; } /** * POST /users/:id/submit response */ export interface WildduckSubmitMessageResponse extends WildduckAPIResponse { success: true; message: { id: string; mailbox: string; queueId?: string; }; } /** * PUT /users/:id/mailboxes/:mailbox/messages/:message request body */ export interface WildduckUpdateMessageRequest { moveTo?: string; seen?: boolean; flagged?: boolean; draft?: boolean; expires?: Date | false; sess?: string; ip?: string; } // ============================================================================ // Filter API Types // ============================================================================ /** * Filter query conditions */ export interface WildduckFilterQuery { from?: string; to?: string; subject?: string; listId?: string; text?: string; ha?: boolean; size?: number; } /** * Filter actions */ export interface WildduckFilterAction { seen?: boolean; flag?: boolean; delete?: boolean; spam?: boolean; mailbox?: string; targets?: string[]; } /** * Filter list item response (GET /users/:id/filters) */ export interface WildduckGetFiltersResultItem { id: string; name: string; created: Date; query: string[][]; action: string[][]; disabled: boolean; metaData?: Record; } /** * Filter list item response with user (GET /filters) */ export interface WildduckGetAllFiltersResultItem extends WildduckGetFiltersResultItem { user: string; targets?: string[]; } /** * POST /users/:id/filters request body */ export interface WildduckCreateFilterRequest { name?: string; query: WildduckFilterQuery; action: WildduckFilterAction; disabled?: boolean; metaData?: Record; sess?: string; ip?: string; } /** * POST /users/:id/filters response */ export interface WildduckCreateFilterResponse extends WildduckAPIResponse { success: true; id: string; } /** * PUT /users/:id/filters/:filter request body */ export interface WildduckUpdateFilterRequest { name?: string; query?: WildduckFilterQuery; action?: WildduckFilterAction; disabled?: boolean; metaData?: Record; sess?: string; ip?: string; } // ============================================================================ // Authentication API Types // ============================================================================ /** * POST /authenticate request body (standard mode) */ export interface WildduckAuthenticateRequest { username: string; password: string; protocol?: string; scope?: string; appId?: string; token?: boolean; sess?: string; ip?: string; } /** * POST /authenticate request body (crypto emails mode) */ export interface WildduckAuthenticateCryptoRequest { username: string; signature: string; message: string; nonce: string; emailDomain: string; protocol?: string; scope?: string; appId?: string; token?: boolean; sess?: string; ip?: string; signer?: string; } /** * POST /authenticate response */ export interface WildduckAuthenticateResponse extends WildduckAPIResponse { success: true; id: string; username: string; scope: string; require2fa?: string[]; requirePasswordChange?: boolean; token?: string; } // ============================================================================ // Application-Specific Password (ASP) API Types // ============================================================================ /** * ASP list item response (GET /users/:id/asps) */ export interface WildduckGetASPsResultItem { id: string; description: string; scopes: string[]; created: Date; lastUse?: { time: Date; event: string; }; } /** * POST /users/:id/asps request body */ export interface WildduckCreateASPRequest { description: string; scopes: string[]; generateMobileconfig?: boolean; sess?: string; ip?: string; } /** * POST /users/:id/asps response */ export interface WildduckCreateASPResponse extends WildduckAPIResponse { success: true; id: string; password: string; mobileconfig?: string; } // ============================================================================ // 2FA API Types // ============================================================================ /** * TOTP enable request (POST /users/:id/2fa/totp/enable) */ export interface WildduckEnable2FARequest { token: string; sess?: string; ip?: string; } /** * TOTP setup response (POST /users/:id/2fa/totp/setup) */ export interface WildduckSetup2FAResponse extends WildduckAPIResponse { success: true; secret: string; dataurl: string; } // ============================================================================ // Webhook API Types // ============================================================================ /** * Webhook list item response (GET /webhooks) */ export interface WildduckGetWebhooksResultItem { id: string; type: string[]; user?: string; url: string; active: boolean; } /** * POST /webhooks request body */ export interface WildduckCreateWebhookRequest { type: string[]; url: string; user?: string; sess?: string; ip?: string; } /** * POST /webhooks response */ export interface WildduckCreateWebhookResponse extends WildduckAPIResponse { success: true; id: string; } // ============================================================================ // DKIM API Types // ============================================================================ /** * DKIM list item response (GET /dkim) */ export interface WildduckGetDKIMResultItem { id: string; domain: string; selector: string; description: string; fingerprint: string; created: Date; } /** * POST /dkim request body */ export interface WildduckCreateDKIMRequest { domain: string; selector: string; description?: string; privateKey?: string; sess?: string; ip?: string; } /** * POST /dkim response */ export interface WildduckCreateDKIMResponse extends WildduckAPIResponse { success: true; id: string; domain: string; selector: string; publicKey: string; dnsTxt: { name: string; value: string; }; } // ============================================================================ // Settings API Types // ============================================================================ /** * Settings list item response (GET /settings) */ export interface WildduckGetSettingsResultItem { key: string; value: any; name?: string; description?: string; } /** * PUT /settings/:key request body */ export interface WildduckUpdateSettingRequest { value: any; } // ============================================================================ // Storage/Stats API Types // ============================================================================ /** * GET /users/:id/storage response */ export interface WildduckGetStorageResponse extends WildduckAPIResponse { success: true; storageUsed: number; quota: number; } /** * POST /users/:id/storage request body (upload file) */ export interface WildduckUploadFileRequest { filename?: string; contentType?: string; encoding?: 'base64'; content: Buffer | string; cid?: string; sess?: string; ip?: string; } /** * POST /users/:id/storage response */ export interface WildduckUploadFileResponse extends WildduckAPIResponse { success: true; id: string; } /** * Storage file list item response (GET /users/:id/storage) */ export interface WildduckGetFilesResultItem { id: string; filename?: string; contentType?: string; cid?: string; size: number; created: Date; md5: string; } /** * GET /users/:id/storage response */ export interface WildduckGetFilesResponse extends WildduckPaginatedResponse {} // ============================================================================ // Message API Types (Extended) // ============================================================================ /** * Message list item (GET /users/:id/mailboxes/:mailbox/messages) */ export interface WildduckGetMessagesResultItem { id: number; mailbox: string; thread: string; threadMessageCount?: number; from?: WildduckMessageAddress; to: WildduckMessageAddress[]; cc: WildduckMessageAddress[]; bcc: WildduckMessageAddress[]; messageId: string; subject: string; date: Date; idate?: Date; intro: string; attachments: boolean; attachmentsList?: Array<{ id: string; hash?: string; filename: string; contentType: string; disposition: string; transferEncoding: string; related: boolean; sizeKb: number; }>; size: number; seen: boolean; deleted: boolean; flagged: boolean; draft: boolean; answered: boolean; forwarded: boolean; references?: WildduckMessageReference[]; bimi?: WildduckMessageBimi; headers?: Record; contentType?: { value: string; params: Record; }; encrypted?: boolean; metaData?: Record; } /** * GET /users/:id/mailboxes/:mailbox/messages response */ export interface WildduckGetMessagesResponse extends WildduckPaginatedResponse { specialUse: string; } /** * Message search result item (GET /users/:id/search) */ export interface WildduckSearchMessagesResultItem { id: number; mailbox: string; messageId: string; thread: string; threadMessageCount?: number; from?: WildduckMessageAddress; to: WildduckMessageAddress[]; cc: WildduckMessageAddress[]; bcc: WildduckMessageAddress[]; subject: string; date: Date; idate?: Date; size: number; intro: string; attachments: boolean; seen: boolean; deleted: boolean; flagged: boolean; answered: boolean; forwarded: boolean; draft: boolean; contentType: { value: string; params: Record; }; metadata?: Record; headers?: Record; encrypted?: boolean; references?: WildduckMessageReference[]; bimi?: WildduckMessageBimi; } /** * GET /users/:id/search response */ export interface WildduckSearchMessagesResponse extends WildduckPaginatedResponse { query: string; } /** * POST /users/:id/search request body (search and update) */ export interface WildduckSearchApplyRequest { query?: string; datestart?: Date; dateend?: Date; from?: string; to?: string; subject?: string; attachments?: boolean; flagged?: boolean; unseen?: boolean; searchable?: boolean; action: { seen?: boolean; flagged?: boolean; delete?: boolean; moveTo?: string; spam?: boolean; }; sess?: string; ip?: string; } /** * POST /users/:id/search response */ export interface WildduckSearchApplyResponse extends WildduckAPIResponse { success: true; updated: number; deleted?: number; } /** * Message details (GET /users/:id/mailboxes/:mailbox/messages/:message) */ export interface WildduckGetMessageResponse extends WildduckAPIResponse { success: true; id: number; mailbox: string; user: string; from?: WildduckMessageAddress; to: WildduckMessageAddress[]; cc: WildduckMessageAddress[]; bcc: WildduckMessageAddress[]; subject: string; messageId: string; date: Date; idate?: Date; list?: { id?: string; unsubscribe?: string; }; expires?: Date; seen: boolean; deleted: boolean; flagged: boolean; draft: boolean; answered: boolean; forwarded: boolean; html?: string[]; text?: string; attachments?: Array<{ id: string; hash?: string; filename: string; contentType: string; disposition: string; transferEncoding: string; related: boolean; sizeKb: number; }>; size: number; headers?: Record; references?: WildduckMessageReference[]; bimi?: WildduckMessageBimi; metaData?: Record; files?: string[]; contentType?: { value: string; params: Record; }; encrypted?: boolean; verificationResults?: { tls?: { name: string; version: string; }; }; } /** * POST /users/:id/mailboxes/:mailbox/messages/:message/forward request */ export interface WildduckForwardMessageRequest { target: number; addresses?: WildduckMessageAddress[]; sess?: string; ip?: string; } /** * POST /users/:id/mailboxes/:mailbox/messages/:message/submit request */ export interface WildduckSubmitDraftRequest { deleteFiles?: boolean; sendTime?: Date; sess?: string; ip?: string; } /** * Archived messages list item (GET /users/:id/archived/messages) */ export interface WildduckGetArchivedMessagesResultItem { id: string; msgid: number; mailbox: string; user: string; specialUse?: string; size: number; subject?: string; from?: WildduckMessageAddress; to?: WildduckMessageAddress[]; created: Date; exp: boolean; rdate?: Date; retention?: number; } /** * GET /users/:id/archived/messages response */ export interface WildduckGetArchivedMessagesResponse extends WildduckPaginatedResponse {} /** * POST /users/:id/archived/restore request (bulk restore) */ export interface WildduckRestoreMessagesRequest { start?: Date; end?: Date; sess?: string; ip?: string; } /** * POST /users/:id/archived/restore response */ export interface WildduckRestoreMessagesResponse extends WildduckAPIResponse { success: true; restored: number; } // ============================================================================ // Audit API Types // ============================================================================ /** * POST /audit request body */ export interface WildduckCreateAuditRequest { user: string; start?: Date | false; end?: Date | false; expires: Date; sess?: string; ip?: string; } /** * POST /audit response */ export interface WildduckCreateAuditResponse extends WildduckAPIResponse { success: true; id: string; } /** * GET /audit/:audit response */ export interface WildduckGetAuditResponse extends WildduckAPIResponse { success: true; id: string; user: string; start?: Date | false; end?: Date | false; expires: Date; import: { status: string; failed: number; copied: number; }; } // ============================================================================ // Health API Types // ============================================================================ /** * GET /health response (success) */ export interface WildduckHealthResponse extends WildduckAPIResponse { success: true; } /** * GET /health response (failure) */ export interface WildduckHealthErrorResponse extends WildduckAPIResponse { success: false; message: string; } // ============================================================================ // Certificate API Types // ============================================================================ /** * Certificate list item response (GET /certs) */ export interface WildduckGetCertsResultItem { id: string; servername: string; altNames?: string[]; fingerprint: string; validFrom: Date; validTo: Date; } /** * POST /certs request body */ export interface WildduckCreateCertRequest { servername: string; privateKey: string; cert: string; ca?: string[]; description?: string; sess?: string; ip?: string; } /** * POST /certs response */ export interface WildduckCreateCertResponse extends WildduckAPIResponse { success: true; id: string; } // ============================================================================ // Domain Aliases API Types // ============================================================================ /** * Domain alias list item response (GET /domainaliases) */ export interface WildduckGetDomainAliasesResultItem { id: string; alias: string; domain: string; created: Date; } /** * POST /domainaliases request body */ export interface WildduckCreateDomainAliasRequest { alias: string; domain: string; sess?: string; ip?: string; } /** * POST /domainaliases response */ export interface WildduckCreateDomainAliasResponse extends WildduckAPIResponse { success: true; id: string; } /** * GET /domainaliases/:alias response */ export interface WildduckGetDomainAliasResponse extends WildduckAPIResponse { success: true; id: string; alias: string; domain: string; created: Date; } /** * Domain alias resolve response (GET /domainaliases/resolve/:domain) */ export interface WildduckResolveDomainResponse extends WildduckAPIResponse { success: true; domain: string; } // ============================================================================ // Updates API Types // ============================================================================ /** * GET /updates response */ export interface WildduckGetUpdatesResponse extends WildduckAPIResponse { success: true; versions: { wildduck: string; node: string; }; license: string; } }