Send email from a Bolt app

Add a server-side email send to this app. If it is a Next.js App Router project, create app/api/send/route.ts matching the route sample at https://agentisend.com/docs/guides/nextjs; otherwise add one POST route to the app's own server code. Install the npm package agentisend and read the contract at https://agentisend.com/openapi.json. There is no native AgentiSend connector to enable. Read the key from the project secret AGENTISEND_API_KEY and the sender from MAIL_FROM, and keep both out of client code. Derive the idempotency key from the recipient, return the message id, and save that id with the user it was sent to. On a refusal, return code and fix, and do not retry when retryable is false.

/**
 * app/api/send/route.ts — a Next.js App Router route handler.
 *
 * Runs on the server only, so the API key never reaches the browser. The
 * handler returns the message id, which is what you store against the user
 * row: every later question ("did it arrive?", "why was it held?") is answered
 * by GET /emails/:id and GET /emails/:id/explain with that id.
 */
import { AgentiSend, AgentiSendError } from 'agentisend';

const agentisend = new AgentiSend();

/** The verified sender. Failing here beats failing at the API with a 422. */
function mailFrom(): string {
  const from = process.env.MAIL_FROM;
  if (!from) throw new Error('Set MAIL_FROM to an address on a domain you have verified.');
  return from;
}

export const runtime = 'nodejs';

export async function POST(request: Request): Promise<Response> {
  const { email, name } = (await request.json()) as { email?: string; name?: string };
  if (!email) {
    return Response.json({ error: 'email is required' }, { status: 400 });
  }

  try {
    const { id } = await agentisend.emails.send(
      {
        from: mailFrom(),
        to: email,
        subject: 'Welcome',
        html: `<p>Hello ${name ?? 'there'} — your account is ready.</p>`,
      },
      // Derived from the user, not from the moment: a retried request after a
      // timeout replays the first send instead of mailing them twice.
      { idempotencyKey: `welcome/${email}` },
    );
    return Response.json({ id });
  } catch (err) {
    if (err instanceof AgentiSendError) {
      // Every 4xx carries `fix` — what to do, and which endpoint does it.
      return Response.json({ code: err.code, fix: err.fix }, { status: err.status });
    }
    throw err;
  }
}