fluxmail 0.9.0 → 0.11.0

package/dist/http/rest.js

@@ -1,9 +1,9 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { createRoute, OpenAPIHono, z } from '@hono/zod-openapi';
 import { HTTPException } from 'hono/http-exception';
 import { EmailError, isEmailError, mergeEmailQueries, parseEmailSearch, } from '@fluxmail/core';
 import { authenticateBearer, isBootstrapComplete } from '../auth.js';
-import { completeIdempotencyKey, reserveIdempotencyKey } from '../storage/restIdempotency.js';
+import { completeIdempotencyKey, lookupIdempotencyKey, reserveIdempotencyKey } from '../storage/restIdempotency.js';
 import { allowsCapability } from '../authorization.js';
 import { captureOperation } from '../telemetry.js';
 import { VERSION } from '../version.js';
@@ -12,6 +12,7 @@ import { recordAdminAuditEvent } from '../storage/adminAudit.js';
 import { identityOperationId, registerIdentityRoutes } from './identity.js';
 import { operationProperties } from './operationTelemetry.js';
 import { logCodedFailure, logFailure } from '../logging.js';
+import { ClientInputError, publicError } from '../service/publicErrors.js';
 const id = z.string().trim().min(1);
 const accountId = id.openapi({ example: 'acct_123' });
 const messageId = id.openapi({ example: 'msg_123' });
@@ -45,6 +46,16 @@ const MessageBodySchema = z
     .object({ text: z.string().optional(), html: z.string().optional() })
     .strict()
     .openapi('MessageBody');
+const MessageInputBodySchema = z
+    .object({
+    text: z
+        .string()
+        .optional()
+        .describe('Plain-text body. Line breaks appear in the sent email. Keep each prose paragraph on one continuous line and separate paragraphs with blank lines.'),
+    html: z.string().optional(),
+})
+    .strict()
+    .openapi('MessageInputBody');
 const AttachmentInputSchema = z
     .object({
     filename: z.string().min(1),
@@ -125,6 +136,13 @@ const MessageSchema = z
     subject: z.string(),
     date: z.string(),
     snippet: z.string().optional(),
+    searchContext: z
+        .union([
+        z.object({ status: z.literal('matched'), excerpt: z.string() }).strict(),
+        z.object({ status: z.enum(['no_literal_match', 'scan_limit', 'unavailable']) }).strict(),
+    ])
+        .optional()
+        .describe('Optional body excerpt status for a requested portable text search.'),
     body: MessageBodySchema.optional(),
     attachments: z.array(AttachmentMetaSchema).optional(),
     flags: z.object({ read: z.boolean(), starred: z.boolean(), draft: z.boolean() }).strict(),
@@ -195,6 +213,7 @@ const AccountSchema = z
         })
             .strict(),
         snippets: z.boolean(),
+        searchContext: z.boolean().optional().describe('Supports optional match-centered body excerpts.'),
     })
         .strict(),
     ownerMemberId: z.string(),
@@ -206,10 +225,11 @@ const AccountSchema = z
 const ScheduledSendSchema = z
     .object({
     scheduleId: z.string(),
+    operationId: z.string().optional(),
     accountId: z.string(),
     draftId: z.string(),
     sendAt: z.string(),
-    status: z.enum(['pending', 'sending', 'sent', 'failed', 'canceled']),
+    status: z.enum(['pending', 'sending', 'sent', 'failed', 'uncertain', 'canceled']),
     attempts: z.number().int().nonnegative(),
     subject: z.string().optional(),
     to: z.string().optional(),
@@ -223,9 +243,50 @@ const SendResultSchema = z
     .object({ id: z.string(), threadId: z.string(), warnings: z.array(z.string()).optional() })
     .strict()
     .openapi('SendResult');
+const DeliveryOperationSchema = z
+    .object({
+    operationId: z.string(),
+    accountId: z.string(),
+    kind: z.enum(['send', 'forward', 'scheduled']),
+    status: z.enum(['queued', 'sending', 'succeeded', 'failed', 'uncertain']),
+    result: SendResultSchema.optional(),
+    error: z.object({ code: z.string() }).strict().optional(),
+    scheduleId: z.string().optional(),
+})
+    .strict()
+    .openapi('DeliveryOperation');
+const SendPreviewSchema = z
+    .object({
+    accountId: z.string(),
+    from: z.string(),
+    to: z.array(EmailAddressSchema),
+    cc: z.array(EmailAddressSchema),
+    bcc: z.array(EmailAddressSchema),
+    subject: z.string(),
+    attachments: z.array(z.object({ filename: z.string(), mimeType: z.string(), sizeBytes: z.number().int() }).strict()),
+    bodyTextChars: z.number().int(),
+    bodyHtmlChars: z.number().int(),
+})
+    .strict()
+    .openapi('SendPreview');
+const ModifyResultSchema = z
+    .object({
+    action: z.string(),
+    succeededIds: z.array(z.string()),
+    failed: z.array(z.object({ messageId: z.string(), code: z.string() }).strict()),
+    uncertainIds: z.array(z.string()),
+})
+    .strict();
 const ErrorSchema = z
     .object({
-    error: z.object({ code: z.string(), message: z.string(), data: z.record(z.unknown()).optional() }).strict(),
+    error: z
+        .object({
+        code: z.string(),
+        message: z.string(),
+        requestId: z.string().optional(),
+        data: z.record(z.unknown()).optional(),
+    })
+        .strict(),
 })
     .strict()
     .openapi('RestError');
@@ -311,7 +372,7 @@ const draftShape = {
     cc: z.array(EmailAddressSchema).optional(),
     bcc: z.array(EmailAddressSchema).optional(),
     subject: z.string().optional(),
-    body: MessageBodySchema,
+    body: MessageInputBodySchema,
     replyToMessageId: messageId.optional(),
     replyAll: z.boolean().optional().describe('Requires replyToMessageId when true.'),
     attachments: z.array(AttachmentInputSchema).optional(),
@@ -333,7 +394,10 @@ const ForwardRequestSchema = z
     from: z.string().email().optional(),
     to: z.array(EmailAddressSchema).min(1),
     cc: z.array(EmailAddressSchema).optional(),
-    comment: z.string().optional(),
+    comment: z
+        .string()
+        .optional()
+        .describe('Comment above the forwarded message. Keep prose paragraphs on one continuous line and separate paragraphs with blank lines.'),
     includeAttachments: z
         .boolean()
         .optional()
@@ -356,7 +420,10 @@ const modifyActionNames = [
 ];
 const ModifyRequestSchema = z
     .object({
-    messageIds: z.array(messageId).min(1),
+    messageIds: z
+        .array(messageId)
+        .min(1)
+        .refine((ids) => new Set(ids).size <= 100, 'At most 100 distinct message IDs are allowed.'),
     action: z.enum(modifyActionNames),
     folder: z
         .string()
@@ -407,6 +474,10 @@ const messageQuerySchema = z
         .optional(),
     pageToken: z.string().min(1).optional(),
     includeSnippet: z.enum(['true', 'false']).optional(),
+    includeSearchContext: z
+        .enum(['true', 'false'])
+        .optional()
+        .describe('Include a match-centered body excerpt. Requires a portable text query.'),
 })
     .strict();
 const portableFolder = z.enum(['inbox', 'sent', 'drafts', 'archive', 'spam', 'trash', 'all']);
@@ -429,6 +500,10 @@ const BatchSearchRequestSchema = z
     before: isoDate.optional(),
     pageSize: z.number().int().min(1).max(100).optional(),
     includeSnippet: z.boolean().optional(),
+    includeSearchContext: z
+        .boolean()
+        .optional()
+        .describe('Include a match-centered body excerpt. Requires a portable text query.'),
 })
     .strict()
     .openapi('BatchSearchRequest');
@@ -459,11 +534,12 @@ class RestFailure extends Error {
         this.retryAfter = retryAfter;
     }
 }
-function logRestFailure(deps, operation, error, startedAt) {
+function logRestFailure(deps, operation, error, startedAt, requestId) {
     const context = {
         productSurface: 'rest',
         operation,
         durationMs: performance.now() - startedAt,
+        ...(requestId ? { details: { request_id: requestId } } : {}),
     };
     if (error instanceof RestFailure) {
         logCodedFailure(deps.logger, 'rest.operation_failed', error.code, error.message, context);
@@ -472,17 +548,18 @@ function logRestFailure(deps, operation, error, startedAt) {
         logFailure(deps.logger, 'rest.operation_failed', error, context);
     }
 }
-function apiFailure(err) {
+function apiFailure(err, requestId = randomUUID()) {
     if (err instanceof RestFailure) {
         return {
             status: err.status,
-            payload: { error: { code: err.code, message: err.message, ...(err.data ? { data: err.data } : {}) } },
+            payload: { error: { code: err.code, message: err.message, requestId, ...(err.data ? { data: err.data } : {}) } },
             ...(err.retryAfter ? { retryAfter: err.retryAfter } : {}),
         };
     }
     if (isEmailError(err)) {
         const status = {
             invalid_request: 400,
+            idempotency_conflict: 409,
             permission_denied: 403,
             entitlement_exceeded: 403,
             not_found: 404,
@@ -491,16 +568,19 @@ function apiFailure(err) {
             rate_limited: 429,
             provider_unavailable: 503,
         };
+        const safe = publicError(err, requestId);
+        const retryAfterMs = safe.data?.retryAfterMs;
         return {
             status: status[err.code] ?? 500,
-            payload: {
-                error: { code: err.code, message: err.message, ...(err.data ? { data: err.data } : {}) },
-            },
+            payload: { error: safe },
+            ...(typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) && retryAfterMs >= 0
+                ? { retryAfter: String(Math.max(1, Math.ceil(retryAfterMs / 1000))) }
+                : {}),
         };
     }
     return {
         status: 500,
-        payload: { error: { code: 'internal', message: 'The request could not be completed.' } },
+        payload: { error: publicError(err, requestId) },
     };
 }
 function jsonResponse(body, status, headers = {}) {
@@ -543,6 +623,7 @@ function safeAttachmentFilename(filename) {
 async function runJson(c, deps, options, fn) {
     const finishActivity = deps.telemetry?.beginActivity?.();
     const startedAt = performance.now();
+    const requestId = randomUUID();
     let outcome = 'error';
     let errorCode;
     let idempotencyStatus;
@@ -554,6 +635,32 @@ async function runJson(c, deps, options, fn) {
             throw new EmailError('permission_denied', `This API key does not allow: ${missing.join(', ')}.`);
         }
         const service = c.get('restService');
+        if (options.legacyReplay) {
+            const key = c.req.header('idempotency-key');
+            if (!key || !/^[\x21-\x7e]{1,255}$/.test(key)) {
+                throw new RestFailure('invalid_request', 'Idempotency-Key is required.', 400);
+            }
+            if (options.accountId !== undefined)
+                service.assertAccountAccess(options.accountId);
+            const legacy = lookupIdempotencyKey(deps.db, auth.principalId, key);
+            if (legacy) {
+                if (legacy.requestHash !== requestHash(options.operation, options.request)) {
+                    throw new RestFailure('idempotency_conflict', 'This Idempotency-Key was already used for a different request.', 409);
+                }
+                if (legacy.state !== 'completed' || legacy.responseStatus === null || legacy.responseBody === null) {
+                    throw new RestFailure('idempotency_in_progress', 'The earlier delivery outcome is uncertain.', 409);
+                }
+                return new Response(legacy.responseBody, {
+                    status: legacy.responseStatus,
+                    headers: {
+                        'content-type': 'application/json; charset=UTF-8',
+                        'cache-control': 'no-store',
+                        'idempotency-replayed': 'true',
+                        'x-request-id': requestId,
+                    },
+                });
+            }
+        }
         if (options.idempotent) {
             const idempotencyKey = c.req.header('idempotency-key');
             if (!idempotencyKey || !/^[\x21-\x7e]{1,255}$/.test(idempotencyKey)) {
@@ -590,6 +697,7 @@ async function runJson(c, deps, options, fn) {
                         'content-type': 'application/json; charset=UTF-8',
                         'cache-control': 'no-store',
                         'idempotency-replayed': 'true',
+                        'x-request-id': requestId,
                     },
                 });
             }
@@ -613,12 +721,16 @@ async function runJson(c, deps, options, fn) {
                 errorCode = 'account_failure';
             return new Response(body, {
                 status,
-                headers: { 'content-type': 'application/json; charset=UTF-8', 'cache-control': 'no-store' },
+                headers: {
+                    'content-type': 'application/json; charset=UTF-8',
+                    'cache-control': 'no-store',
+                    'x-request-id': requestId,
+                },
             });
         }
         catch (err) {
-            logRestFailure(deps, options.operation, err, startedAt);
-            const failure = apiFailure(err);
+            logRestFailure(deps, options.operation, err, startedAt, requestId);
+            const failure = apiFailure(err, requestId);
             const body = JSON.stringify(failure.payload);
             if (reservation) {
                 completeIdempotencyKey(deps.db, {
@@ -633,16 +745,20 @@ async function runJson(c, deps, options, fn) {
                 headers: {
                     'content-type': 'application/json; charset=UTF-8',
                     'cache-control': 'no-store',
+                    'x-request-id': requestId,
                     ...(failure.retryAfter ? { 'retry-after': failure.retryAfter } : {}),
                 },
             });
         }
     }
     catch (err) {
-        logRestFailure(deps, options.operation, err, startedAt);
-        const failure = apiFailure(err);
+        logRestFailure(deps, options.operation, err, startedAt, requestId);
+        const failure = apiFailure(err, requestId);
         errorCode = failure.payload.error.code;
-        return jsonResponse(failure.payload, failure.status, failure.retryAfter ? { 'retry-after': failure.retryAfter } : {});
+        return jsonResponse(failure.payload, failure.status, {
+            'x-request-id': requestId,
+            ...(failure.retryAfter ? { 'retry-after': failure.retryAfter } : {}),
+        });
     }
     finally {
         captureOperation(deps.telemetry, {
@@ -662,6 +778,7 @@ async function runJson(c, deps, options, fn) {
 async function runAttachment(c, deps, accountId, messageId, attachmentId) {
     const finishActivity = deps.telemetry?.beginActivity?.();
     const startedAt = performance.now();
+    const requestId = randomUUID();
     let outcome = 'error';
     let errorCode;
     try {
@@ -673,7 +790,7 @@ async function runAttachment(c, deps, accountId, messageId, attachmentId) {
         const warning = service.enforceQuota();
         const { meta, content } = await service.getAttachment(accountId, messageId, attachmentId, deps.config.maxAttachmentBytes);
         if (content.length > deps.config.maxAttachmentBytes) {
-            throw new EmailError('invalid_request', 'Attachment is too large to return through the REST API.', {
+            throw new ClientInputError('invalid_request', 'Attachment is too large to return through the REST API.', {
                 sizeBytes: content.length,
                 maxBytes: deps.config.maxAttachmentBytes,
             });
@@ -691,15 +808,16 @@ async function runAttachment(c, deps, accountId, messageId, attachmentId) {
                 'content-length': String(content.length),
                 'content-disposition': `attachment; filename="${asciiName}"; filename*=UTF-8''${encodeContentDispositionFilename(safeName)}`,
                 'cache-control': 'no-store',
+                'x-request-id': requestId,
                 ...(warning ? { 'fluxmail-warning': warning.replace(/[\r\n]/g, ' ') } : {}),
             },
         });
     }
     catch (err) {
-        logRestFailure(deps, 'downloadAttachment', err, startedAt);
-        const failure = apiFailure(err);
+        logRestFailure(deps, 'downloadAttachment', err, startedAt, requestId);
+        const failure = apiFailure(err, requestId);
         errorCode = failure.payload.error.code;
-        return jsonResponse(failure.payload, failure.status);
+        return jsonResponse(failure.payload, failure.status, { 'x-request-id': requestId });
     }
     finally {
         captureOperation(deps.telemetry, {
@@ -741,13 +859,13 @@ function toEmailQuery(input) {
         const parsed = parseEmailSearch(input.query);
         diagnostics = parsed.diagnostics;
         if (!parsed.valid) {
-            throw new EmailError('invalid_request', parsed.diagnostics.map((item) => item.message).join(' '), {
+            throw new ClientInputError('invalid_request', parsed.diagnostics.map((item) => item.message).join(' '), {
                 diagnostics: parsed.diagnostics,
             });
         }
         const merged = mergeEmailQueries(parsed.query, structured);
         if (!merged.success) {
-            throw new EmailError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
+            throw new ClientInputError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
                 diagnostics: merged.diagnostics,
             });
         }
@@ -760,6 +878,9 @@ function toEmailQuery(input) {
             ...(input.pageSize ? { pageSize: Number(input.pageSize) } : {}),
             ...(input.pageToken ? { pageToken: input.pageToken } : {}),
             ...(input.includeSnippet !== undefined ? { includeSnippet: input.includeSnippet === 'true' } : {}),
+            ...(input.includeSearchContext !== undefined
+                ? { includeSearchContext: input.includeSearchContext === 'true' }
+                : {}),
         },
     };
 }
@@ -786,7 +907,7 @@ function modifyAction(input) {
     if (input.action === 'move') {
         const folder = input.folder;
         if (PROTECTED_MOVE_DESTINATIONS.has(folder.trim().toLowerCase())) {
-            throw new EmailError('invalid_request', 'Use the dedicated archive or trash action for this folder.');
+            throw new ClientInputError('invalid_request', 'Use the dedicated archive or trash action for this folder.');
         }
         return { move: folder };
     }
@@ -999,6 +1120,12 @@ export function createRestApi(deps) {
             return jsonResponse({ error: { code: 'unauthorized', message: 'Pass a member session or API key as a Bearer token.' } }, 401, { 'www-authenticate': 'Bearer' });
         }
         c.set('restAuth', auth);
+        if (!administrative && ['POST', 'PATCH', 'PUT'].includes(c.req.method)) {
+            const limit = Math.ceil((deps.config.maxAttachmentBytes * 4) / 3) + 2 * 1024 * 1024;
+            if (await requestBodyExceedsLimit(c.req.raw, limit)) {
+                return jsonResponse({ error: { code: 'request_too_large', message: 'Mail request body exceeds the size limit.' } }, 413);
+            }
+        }
         if (administrative && (c.req.method === 'POST' || c.req.method === 'PATCH' || c.req.method === 'PUT')) {
             const mediaType = c.req.header('content-type')?.split(';', 1)[0]?.trim().toLowerCase();
             if (mediaType !== 'application/json') {
@@ -1217,7 +1344,7 @@ export function createRestApi(deps) {
         const input = c.req.valid('json');
         const parsed = parseEmailSearch(input.query);
         if (!parsed.valid) {
-            throw new EmailError('invalid_request', parsed.diagnostics.map((item) => item.message).join(' '), {
+            throw new ClientInputError('invalid_request', parsed.diagnostics.map((item) => item.message).join(' '), {
                 diagnostics: parsed.diagnostics,
             });
         }
@@ -1232,7 +1359,7 @@ export function createRestApi(deps) {
         }
         const merged = mergeEmailQueries(parsed.query, structured);
         if (!merged.success) {
-            throw new EmailError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
+            throw new ClientInputError('invalid_request', merged.diagnostics.map((item) => item.message).join(' '), {
                 diagnostics: merged.diagnostics,
             });
         }
@@ -1241,6 +1368,7 @@ export function createRestApi(deps) {
             query: merged.query,
             ...(input.pageSize !== undefined ? { pageSize: input.pageSize } : {}),
             ...(input.includeSnippet !== undefined ? { includeSnippet: input.includeSnippet } : {}),
+            ...(input.includeSearchContext !== undefined ? { includeSearchContext: input.includeSearchContext } : {}),
         });
         return {
             data: result.groups.map((group) => {
@@ -1304,6 +1432,24 @@ export function createRestApi(deps) {
             data: await c.get('restService').getThread(accountId, threadId),
         }));
     });
+    const getDraftRoute = createRoute({
+        method: 'get',
+        path: '/api/v1/accounts/{accountId}/drafts/{draftId}',
+        operationId: 'getDraft',
+        summary: 'Get a draft',
+        request: { params: draftParams },
+        ...protectedRoute,
+        responses: {
+            200: { content: { 'application/json': { schema: dataEnvelope(MessageSchema) } }, description: 'Draft' },
+            ...errorResponses,
+        },
+    });
+    app.openapi(getDraftRoute, (c) => {
+        const { accountId, draftId } = c.req.valid('param');
+        return runJson(c, deps, { operation: 'getDraft', capabilities: ['mail.drafts'] }, async () => ({
+            data: await c.get('restService').getDraft(accountId, draftId),
+        }));
+    });
     const createDraftRoute = createRoute({
         method: 'post',
         path: '/api/v1/accounts/{accountId}/drafts',
@@ -1375,6 +1521,37 @@ export function createRestApi(deps) {
             return { data: { deleted: draftId } };
         });
     });
+    const previewSendRoute = createRoute({
+        method: 'post',
+        path: '/api/v1/accounts/{accountId}/send/preview',
+        operationId: 'previewSend',
+        summary: 'Preview a send',
+        request: {
+            params: accountParams,
+            body: { required: true, content: { 'application/json': { schema: SendRequestSchema } } },
+        },
+        ...protectedRoute,
+        responses: {
+            200: {
+                content: { 'application/json': { schema: dataEnvelope(SendPreviewSchema) } },
+                description: 'Resolved send details',
+            },
+            ...errorResponses,
+        },
+    });
+    app.openapi(previewSendRoute, (c) => {
+        const { accountId } = c.req.valid('param');
+        const input = c.req.valid('json');
+        const capabilities = ['mail.send'];
+        if ('draftId' in input)
+            capabilities.push('mail.drafts');
+        if ('replyToMessageId' in input && input.replyToMessageId)
+            capabilities.push('mail.read');
+        const request = 'draftId' in input ? { draftId: input.draftId } : toSendInput(input);
+        return runJson(c, deps, { operation: 'previewSend', capabilities }, async () => ({
+            data: await c.get('restService').previewSend(accountId, request),
+        }));
+    });
     const sendRoute = createRoute({
         method: 'post',
         path: '/api/v1/accounts/{accountId}/send',
@@ -1388,9 +1565,12 @@ export function createRestApi(deps) {
         },
         ...protectedRoute,
         responses: {
-            200: { content: { 'application/json': { schema: dataEnvelope(SendResultSchema) } }, description: 'Message sent' },
+            200: {
+                content: { 'application/json': { schema: dataEnvelope(DeliveryOperationSchema) } },
+                description: 'Delivery operation',
+            },
             202: {
-                content: { 'application/json': { schema: dataEnvelope(ScheduledSendSchema) } },
+                content: { 'application/json': { schema: dataEnvelope(DeliveryOperationSchema) } },
                 description: 'Message scheduled',
             },
             ...errorResponses,
@@ -1410,17 +1590,46 @@ export function createRestApi(deps) {
             capabilities,
             successStatus: sendAt ? 202 : 200,
             request: { accountId, input },
-            idempotent: true,
+            legacyReplay: true,
             accountId,
             telemetry: {
                 mode: 'draftId' in input ? 'draft' : input.replyToMessageId ? 'reply' : 'direct',
                 scheduled: sendAt !== undefined,
                 reply_all: 'replyAll' in input && input.replyAll === true,
             },
-        }, async () => ({
-            data: sendAt
-                ? await c.get('restService').scheduleSend(accountId, request, sendAt)
-                : await c.get('restService').send(accountId, request),
+        }, async () => {
+            const service = c.get('restService');
+            const key = c.req.header('idempotency-key');
+            if (sendAt) {
+                const operation = await service.scheduleDelivery(accountId, request, sendAt, key);
+                return {
+                    data: operation,
+                    operationFailed: operation.status === 'failed' || operation.status === 'uncertain',
+                };
+            }
+            const operation = await service.deliver(accountId, request, key);
+            return { data: operation, operationFailed: operation.status === 'failed' || operation.status === 'uncertain' };
+        });
+    });
+    const deliveryStatusRoute = createRoute({
+        method: 'get',
+        path: '/api/v1/accounts/{accountId}/delivery-operations/{operationId}',
+        operationId: 'getDeliveryOperation',
+        summary: 'Get a delivery outcome',
+        request: { params: z.object({ accountId, operationId: id }).strict() },
+        ...protectedRoute,
+        responses: {
+            200: {
+                content: { 'application/json': { schema: dataEnvelope(DeliveryOperationSchema) } },
+                description: 'Delivery outcome',
+            },
+            ...errorResponses,
+        },
+    });
+    app.openapi(deliveryStatusRoute, (c) => {
+        const { accountId, operationId } = c.req.valid('param');
+        return runJson(c, deps, { operation: 'getDeliveryOperation', capabilities: ['mail.send'], quota: false }, () => ({
+            data: c.get('restService').getDelivery(accountId, operationId),
         }));
     });
     const listScheduledRoute = createRoute({
@@ -1490,7 +1699,10 @@ export function createRestApi(deps) {
         },
         ...protectedRoute,
         responses: {
-            200: { content: { 'application/json': { schema: dataEnvelope(SendResultSchema) } }, description: 'Forward sent' },
+            200: {
+                content: { 'application/json': { schema: dataEnvelope(DeliveryOperationSchema) } },
+                description: 'Forward delivery operation',
+            },
             ...errorResponses,
         },
     });
@@ -1501,12 +1713,15 @@ export function createRestApi(deps) {
             operation: 'forwardMessage',
             capabilities: ['mail.send', 'mail.read'],
             request: { accountId, messageId, input },
-            idempotent: true,
+            legacyReplay: true,
             accountId,
             telemetry: { include_attachments: input.includeAttachments !== false },
-        }, async () => ({
-            data: await c.get('restService').forward(accountId, { messageId, ...input }),
-        }));
+        }, async () => {
+            const operation = await c
+                .get('restService')
+                .deliverForward(accountId, { messageId, ...input }, c.req.header('idempotency-key'));
+            return { data: operation, operationFailed: operation.status === 'failed' || operation.status === 'uncertain' };
+        });
     });
     const modifyRoute = createRoute({
         method: 'post',
@@ -1523,7 +1738,7 @@ export function createRestApi(deps) {
             200: {
                 content: {
                     'application/json': {
-                        schema: dataEnvelope(z.object({ modified: z.number().int(), action: z.enum(modifyActionNames) }).strict()),
+                        schema: dataEnvelope(ModifyResultSchema),
                     },
                 },
                 description: 'Messages modified',
@@ -1540,8 +1755,11 @@ export function createRestApi(deps) {
             capabilities: [capability],
             telemetry: { action: input.action },
         }, async () => {
-            await c.get('restService').modify(accountId, input.messageIds, modifyAction(input));
-            return { data: { modified: input.messageIds.length, action: input.action } };
+            const result = await c.get('restService').modify(accountId, input.messageIds, modifyAction(input));
+            return {
+                data: { ...result, action: input.action },
+                operationFailed: result.failed.length > 0 || result.uncertainIds.length > 0,
+            };
         });
     });
     const attachmentRoute = createRoute({
@@ -1577,12 +1795,16 @@ export function createRestApi(deps) {
     app.doc31('/api/v1/openapi.json', REST_OPENAPI_DOCUMENT);
     app.all('/api/v1/*', () => jsonResponse({ error: { code: 'not_found', message: 'No REST route matches this request.' } }, 404));
     app.onError((err) => {
+        const requestId = randomUUID();
         const malformedJson = err instanceof SyntaxError || (err instanceof HTTPException && err.status === 400)
-            ? new EmailError('invalid_request', 'Malformed JSON body.')
+            ? new ClientInputError('invalid_request', 'Malformed JSON body.')
             : err;
-        logFailure(deps.logger, 'rest.unhandled_error', malformedJson, { productSurface: 'rest' });
-        const failure = apiFailure(malformedJson);
-        return jsonResponse(failure.payload, failure.status);
+        logFailure(deps.logger, 'rest.unhandled_error', malformedJson, {
+            productSurface: 'rest',
+            details: { request_id: requestId },
+        });
+        const failure = apiFailure(malformedJson, requestId);
+        return jsonResponse(failure.payload, failure.status, { 'x-request-id': requestId });
     });
     return app;
 }