Skip to content
Browse the docs

Frameworks and agents · Published 2026-09-28 · Updated 2026-11-09 · AgentiSend

Send email from Astro

An Astro API route that confirms a waitlist sign-up from a plain form post, refusing a malformed address before the API is called.

To send email from an Astro site, add an API route whose POST handler reads the form, calls AgentiSend and returns the message id. The route below confirms a waitlist sign-up: it refuses a malformed address before the API is called, and sends once per address however many times the form is submitted. It is run by the test suite against a local AgentiSend server, called with a real form post: one send, and one malformed address refused with nothing sent.

Install

pnpm add agentisend

API routes run on demand, so the project needs a server adapter such as @astrojs/node.

Environment

VariableRequiredWhat it is
AGENTISEND_API_KEYyesA key with sending_access.
MAIL_FROMyesThe From address, on a domain you have verified.
AGENTISEND_BASE_URLnoDefaults to https://api.agentisend.com.

The route

Save it as src/pages/api/waitlist.ts.

/**
 * Astro — `src/pages/api/waitlist.ts`, an API route that confirms a waitlist
 * sign-up.
 *
 * The route runs on the server, so the API key never reaches the browser.
 * `prerender = false` keeps it on demand when the rest of the site is static.
 *
 * In your own project the handler is typed with Astro's own export:
 * `import type { APIRoute } from 'astro'` and `export const POST: APIRoute = …`.
 * It is written against the one field of the context it reads here, so this
 * directory typechecks without Astro installed.
 */
import { AgentiSend, AgentiSendError } from 'agentisend';

const agentisend = new AgentiSend();

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;
}

/** Enough to refuse an obvious typo here; the API checks the address properly. */
const ADDRESS = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

export const prerender = false;

export const POST = async ({ request }: { request: Request }): Promise<Response> => {
  const form = await request.formData();
  const email = String(form.get('email') ?? '').trim();
  if (!ADDRESS.test(email)) {
    return Response.json({ error: 'Enter an email address.' }, { status: 400 });
  }

  try {
    const { id } = await agentisend.emails.send(
      {
        from: mailFrom(),
        to: email,
        subject: 'You are on the waitlist',
        text: 'Thanks for signing up. We will write once, when your invite is ready.',
      },
      // A second submit of the same form replays the first send.
      { idempotencyKey: `waitlist/${email}` },
    );
    return Response.json({ id });
  } catch (err) {
    if (err instanceof AgentiSendError) {
      return Response.json({ code: err.code, fix: err.fix }, { status: err.status });
    }
    throw err;
  }
};
examples/astro/waitlist.ts, run by the test suite against a local AgentiSend server

In your project, type the handler with Astro's own export:

import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  /* the body above */
};

The form

<form method="POST" action="/api/waitlist">
  <input type="email" name="email" required />
  <button type="submit">Join the waitlist</button>
</form>

The key and its budget

Give the site a key of its own rather than the one you signed in with. POST /api-keys with sending_access mints a key that can send and read what it sent, and nothing else. PATCH /limits/keys/{id} puts a ceiling on it with budget_per_period and period, so a form that is flooded stops at a number you chose: past it a send is refused with agent_budget_exceeded, and the route answers with that code and its fix.

The idempotency key

Every send carries Idempotency-Key: waitlist/<recipient>, derived from the sign-up and never from the moment. A second submit of the same address, or a retry after a timeout, replays the first send instead of mailing the person twice.

Try it

curl -X POST localhost:4321/api/waitlist \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'email=you@example.com'

What comes back when it goes wrong

Every refused request carries code, message, fix and docs_url. The route answers with the API's status and forwards code and fix, so the caller reads what to do rather than a number. The error catalogue lists every code.

Next

Examples

Prompt for your coding agent

1. Install

npm install agentisend

2. Environment

AGENTISEND_API_KEY
MAIL_FROM
AGENTISEND_BASE_URL=https://api.agentisend.com

3. Send call

/**
 * Astro — `src/pages/api/waitlist.ts`, an API route that confirms a waitlist
 * sign-up.
 *
 * The route runs on the server, so the API key never reaches the browser.
 * `prerender = false` keeps it on demand when the rest of the site is static.
 *
 * In your own project the handler is typed with Astro's own export:
 * `import type { APIRoute } from 'astro'` and `export const POST: APIRoute = …`.
 * It is written against the one field of the context it reads here, so this
 * directory typechecks without Astro installed.
 */
import { AgentiSend, AgentiSendError } from 'agentisend';

const agentisend = new AgentiSend();

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;
}

/** Enough to refuse an obvious typo here; the API checks the address properly. */
const ADDRESS = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

export const prerender = false;

export const POST = async ({ request }: { request: Request }): Promise<Response> => {
  const form = await request.formData();
  const email = String(form.get('email') ?? '').trim();
  if (!ADDRESS.test(email)) {
    return Response.json({ error: 'Enter an email address.' }, { status: 400 });
  }

  try {
    const { id } = await agentisend.emails.send(
      {
        from: mailFrom(),
        to: email,
        subject: 'You are on the waitlist',
        text: 'Thanks for signing up. We will write once, when your invite is ready.',
      },
      // A second submit of the same form replays the first send.
      { idempotencyKey: `waitlist/${email}` },
    );
    return Response.json({ id });
  } catch (err) {
    if (err instanceof AgentiSendError) {
      return Response.json({ code: err.code, fix: err.fix }, { status: err.status });
    }
    throw err;
  }
};

4. Parameter reference

POST /emails
attachments array<object>
bcc any
cc any
expires_at string
from string
headers object
html string
replyTo any
reply_to any
scheduledAt string
scheduled_at string
subject string
tags any
template object
template_id string
template_values object
text string
timezone string
to any required
topicId string
topic_id string
Idempotency-Key header
Resend-Idempotency-Key header

5. Rules

Read the API key on the server. Do not send it to the browser.
Send an Idempotency-Key derived from the thing being done, not from the clock.
A refusal is JSON with code, message, fix and docs_url. Follow fix.

6. Verify

GET /emails/{id}
The id is the one the send call returned.