Fix strict batch preflight (#38)

## What changed

- split email creation into side-effect-free preparation and commit
phases
- preflight every message in a strict batch before persisting or
queueing any sibling
- document strict-only batch validation and add service/API regression
coverage

## Why

`createBatch` previously called `create` for every message concurrently.
If one message referenced a missing or unpublished template, or an
invalid uploaded attachment, another valid message could already be
stored and queued even though the batch request returned an error. A
caller retry could then duplicate delivery.

The official Resend API uses strict batch validation by default, where
one invalid message prevents the batch from being sent. HayaSend now
matches that safety behavior for its service-level validation.

## Impact

Successful single-email and batch response shapes are unchanged. Invalid
batches now fail before any valid sibling is accepted. Permissive batch
mode and distributed transaction handling for infrastructure failures
remain out of scope.

## Validation

- `npm run check`
- `npm test` — 21 files, 144 tests
- `npm run build`
- `npm audit --omit=dev --audit-level=high` — 0 vulnerabilities
- `cfn-lint==1.53.2 template.yaml`
- Redocly 2.12.5 OpenAPI lint
- Lambda entry-point bundles
- `actionlint`
- `gitleaks git --staged`
- signed commit with DCO sign-off

Signed-off-by: Yusuke Hayashi <yusuke8h@gmail.com>

Author: yhay81

CHANGELOG.md

@@ -18,6 +18,8 @@ No unreleased changes.
   a CLI for substituting operator assumptions.
 - Reject malformed scoped API keys before any DynamoDB or Secrets Manager
   lookup so unauthenticated input cannot turn storage limits into API errors.
+- Preflight every email in a strict batch before persisting or queueing any
+  message, preventing partial sends when a template or attachment is invalid.
 - Initial Resend-compatible sending, scheduling, receiving, webhook, and AWS
   deployment foundation.
 - Add Resend-compatible hosted templates with aliases, typed variables,

docs/compatibility.md

@@ -8,7 +8,7 @@ migration path. It does not claim full Resend API coverage.
 | Emails              | send                                            |        Implemented | HTML, text, recipients, headers, tags                              |
 | Emails              | retrieve/list                                   |        Implemented | HayaSend adds internal status fields                               |
 | Emails              | update/cancel                                   |        Implemented | queued or scheduled messages only                                  |
-| Batch               | send                                            |        Implemented | 1–100 messages                                                     |
+| Batch               | send                                            |        Implemented | 1–100 messages; strict validation only, without permissive mode    |
 | Attachments         | base64 content                                  |        Implemented | constrained by the 9 MiB serialized request guardrail              |
 | Attachments         | direct upload                                   | HayaSend extension | checksum-bound S3 PUT; 25 MiB decoded aggregate                    |
 | Attachments         | remote path                                     |           Rejected | avoids server-side URL fetching                                    |

src/services/email-service.ts

@@ -11,8 +11,10 @@ import type {
   CreateEmailResult,
   EmailRecord,
   EmailStatus,
+  IdempotencyClaim,
   Page,
   SendEmailInput,
+  SuppressionRecord,
   WebhookEventType,
 } from "../core/types.js";
 import type { EmailScheduler } from "../ports/email-scheduler.js";
@@ -82,6 +84,13 @@ function validateInput(
   }
 }
 
+interface PreparedEmail {
+  record: EmailRecord;
+  idempotency: IdempotencyClaim | undefined;
+  scheduledAt: string | undefined;
+  suppressedRecipients: SuppressionRecord[];
+}
+
 export class EmailService {
   constructor(
     private readonly store: Store,
@@ -98,6 +107,46 @@ export class EmailService {
     idempotencyKey?: string,
     now = new Date(),
   ): Promise<CreateEmailResult> {
+    return this.commitPreparedEmail(
+      await this.prepareEmail(input, idempotencyKey, now),
+      now,
+    );
+  }
+
+  async createBatch(
+    inputs: SendEmailInput[],
+    idempotencyKey?: string,
+  ): Promise<CreateEmailResult[]> {
+    if (inputs.length === 0 || inputs.length > 100) {
+      throw new ValidationError(
+        "A batch must contain between 1 and 100 emails.",
+      );
+    }
+    if (Buffer.byteLength(JSON.stringify(inputs), "utf8") > 9 * 1024 * 1024) {
+      throw new ValidationError(
+        "The serialized batch request must not exceed 9 MiB.",
+      );
+    }
+    const now = new Date();
+    const prepared = await Promise.all(
+      inputs.map((input, index) =>
+        this.prepareEmail(
+          input,
+          idempotencyKey ? `${idempotencyKey}:${index}` : undefined,
+          now,
+        ),
+      ),
+    );
+    return Promise.all(
+      prepared.map((email) => this.commitPreparedEmail(email, now)),
+    );
+  }
+
+  private async prepareEmail(
+    input: SendEmailInput,
+    idempotencyKey: string | undefined,
+    now: Date,
+  ): Promise<PreparedEmail> {
     const templateRequestHash = input.template ? requestHash(input) : undefined;
     if (input.template) {
       if (!this.templates) {
@@ -157,6 +206,23 @@ export class EmailService {
           expires_at: Math.floor(now.getTime() / 1_000) + 86_400,
         }
       : undefined;
+    return {
+      record,
+      idempotency,
+      scheduledAt,
+      suppressedRecipients,
+    };
+  }
+
+  private async commitPreparedEmail(
+    {
+      record,
+      idempotency,
+      scheduledAt,
+      suppressedRecipients,
+    }: PreparedEmail,
+    now: Date,
+  ): Promise<CreateEmailResult> {
     const created = await this.store.createEmail(record, idempotency);
     if (!created.replayed) {
       if (suppressedRecipients.length > 0) {
@@ -186,30 +252,6 @@ export class EmailService {
     return created;
   }
 
-  async createBatch(
-    inputs: SendEmailInput[],
-    idempotencyKey?: string,
-  ): Promise<CreateEmailResult[]> {
-    if (inputs.length === 0 || inputs.length > 100) {
-      throw new ValidationError(
-        "A batch must contain between 1 and 100 emails.",
-      );
-    }
-    if (Buffer.byteLength(JSON.stringify(inputs), "utf8") > 9 * 1024 * 1024) {
-      throw new ValidationError(
-        "The serialized batch request must not exceed 9 MiB.",
-      );
-    }
-    return Promise.all(
-      inputs.map((input, index) =>
-        this.create(
-          input,
-          idempotencyKey ? `${idempotencyKey}:${index}` : undefined,
-        ),
-      ),
-    );
-  }
-
   async get(id: string): Promise<EmailRecord> {
     const record = await this.store.getEmail(id);
     if (!record) {

tests/app.test.ts

@@ -644,6 +644,28 @@ describe("HTTP API", () => {
     expect(replayBody.id).not.toBe(deliveryId);
   });
 
+  it("rejects a strict batch before accepting any valid sibling", async () => {
+    const { queue, request, store } = fixture();
+    const response = await request("/emails/batch", {
+      method: "POST",
+      body: JSON.stringify([
+        email,
+        {
+          to: "template-recipient@example.net",
+          template: { id: "missing-template" },
+        },
+      ]),
+    });
+
+    expect(response.status).toBe(404);
+    await expect(response.json()).resolves.toMatchObject({
+      name: "not_found",
+      message: "Template was not found.",
+    });
+    await expect(store.listEmails(100)).resolves.toMatchObject({ data: [] });
+    expect(queue.jobs).toHaveLength(0);
+  });
+
   it("rejects unsupported attachment URLs rather than fetching them", async () => {
     const { request } = fixture();
     const response = await request("/emails", {

tests/email-service.test.ts

@@ -107,6 +107,23 @@ const input = {
 };
 
 describe("EmailService", () => {
+  it("preflights a strict batch before creating or queueing any email", async () => {
+    const { queue, service, store } = fixture();
+
+    await expect(
+      service.createBatch([
+        input,
+        {
+          to: ["template-recipient@example.net"],
+          template: { id: "missing-template" },
+        },
+      ]),
+    ).rejects.toThrow("Template");
+
+    await expect(store.listEmails(100)).resolves.toMatchObject({ data: [] });
+    expect(queue.jobs).toHaveLength(0);
+  });
+
   it("keeps a template send idempotent across later publications", async () => {
     const { queue, service, templates } = fixture();
     const template = await templates.create({