Agents transactional email should be one of the easiest parts of an AI-built app: a user signs up, an authenticated server route calls an email API, and the user gets a useful message. The catch is that an agent can write code quickly, but it still needs clear boundaries around secrets, verified senders, retries, and what counts as a successful send.

This page is for builders using Agents as a broad label for AI coding tools and autonomous coding assistants. Whether you are prompting from an editor, a browser-based app builder, or a command-line agent, the reliable path is the same: give the agent a constrained task, keep email sending on the server, use Volanea's transactional send endpoint, and test before turning on real delivery.

Why Agents transactional email is a practical first integration

A transactional email is triggered by something a person did in your product. They create an account, request a password reset, receive an invite, place an order, change a billing setting, or need to know about an important account event.

That makes email a particularly good task for an AI coding agent. The behavior is concrete. There is an event in your application, a recipient address, a message, and a server-side call. An agent does not need to invent a complex product workflow to add the first version.

The first useful sends usually fall into a short list:

A welcome email after successful signup.
A verification or magic-link email.
A password-reset email.
An organization invitation.
An order, booking, invoice, or payment receipt.
A security alert for a new login, changed password, or changed email address.
An internal alert when an important background job fails.

These messages are not marketing broadcasts. They are tied to a specific user action or account state. That distinction matters because transactional email should be dependable, understandable, and sent only when the application has a real reason to send it.

For an AI-built app, the goal is not merely to make a message appear in an inbox. The goal is to create a small, reviewable system that will still behave correctly after your agent changes the signup form, your database schema, or your deployment environment.

The right mental model: the agent writes the integration, your app owns the decision

An agent can generate an email route, HTML content, and tests. It should not become the authority that decides whether a real customer gets a sensitive message. Your application should make that decision from trusted events and state.

For example, after signup, your server creates the user record first. Only after that succeeds should it ask the email layer to send the welcome email. For password resets, the reset token must be created and stored by your authentication system before the message is sent. For receipts, use the confirmed payment or order event rather than text scraped from a browser page.

A reliable integration has four separate responsibilities:

Your application event decides that a message is needed.
Your server-side email function validates inputs and builds the message.
Volanea accepts the transactional request and processes delivery through its sending pipeline.
Your logs and delivery events help you see whether the message was accepted, delivered, bounced, or otherwise needs attention.

Keeping those roles separate prevents a common agent-coding mistake: putting a secret API key in client-side code because that is the shortest route to a demo. It may work once, but anyone who opens browser developer tools can retrieve the credential and send email as your application.

The implementation below keeps the key on the server, where it belongs.

What Volanea gives an AI-built app

Volanea provides a REST API and SMTP relay for application email. For most new agent-built applications, a server-side REST call is the simplest place to start because the agent can use the platform's native fetch capability without adding an unverified SDK or wiring up a custom SMTP transport.

The single-message endpoint is POST /v1/send at the Volanea API base URL. A request can send to one recipient or up to 50 recipients, and it supports an Idempotency-Key header for safe retry behavior. The standard message body includes from, to, subject, text, and html fields.

That is intentionally a small surface area for your first feature. Your agent needs to know only a few facts:

The API key is a server secret, never browser code.
The sender must use a domain you have verified.
HTML email needs a plain-text fallback.
A stable idempotency key protects retryable business events from generating accidental duplicates.
A successful API response means the request was accepted for processing; it is not the same thing as proof that the recipient has opened or even received the message.

As the app grows, the same platform can support templates, delivery logs, event webhooks, suppressions, and campaign workflows. But do not force the first prompt to solve every future email problem. Start with one production-quality transactional message, then add the next trigger deliberately.

If your agent needs canonical endpoint details and setup guidance while you work, give it the email API reference and setup guides rather than relying on memory or copied snippets from unrelated providers.

Before you prompt the agent: do these human-owned setup tasks

Agents are good at changing a repository. They cannot reliably complete every external trust and account step without your supervision. Domain ownership, DNS access, secret creation, and production delivery should remain deliberate human-controlled actions.

1. Verify a sending domain

Create or select a domain that represents your product, such as example.com, then complete the sender authentication records Volanea gives you for that domain. Do not guess record names or copy DNS values from another email service. DNS values are provider- and domain-specific, so use the exact records displayed for your Volanea project.

Use an address on that verified domain as your sender, such as hello@example.com or support@example.com. A sender that looks familiar and aligns with your product domain is more trustworthy than a random mailbox used only because it was convenient during prototyping.

2. Create a test key and production key intentionally

Use a test key while your agent is building and exercising the flow. Test keys use the sk_test_... form and allow you to render and log the path without delivering real messages. Switch to a live secret only after you have reviewed the route, sender, copy, and test behavior.

Store the key in your hosting provider's encrypted environment-variable system. Locally, keep it in a file such as .env.local that is excluded from version control. Never paste a live key into an agent prompt, a commit, an issue, a screenshot, or a client-side environment variable prefixed for browser exposure.

3. Decide where the trigger belongs

Write down the authoritative moment for each email. For a welcome email, that may be after the user record commits. For a password reset, it is after the reset token is generated. For a subscription receipt, it is after your payment provider confirms the event and your webhook signature has been verified.

This prevents duplicate sends caused by a user refreshing a page, a client retrying a request, or a background worker receiving the same event more than once.

4. Give the agent boundaries, not just an outcome

"Add email" is vague. It leaves the agent to choose where the secret goes, whether to call from the browser, and whether a failed request should block signup.

Instead, name the trigger, runtime, environment variable, sender address, failure behavior, and tests you expect. The next section gives you a prompt you can adapt directly.

A prompt to give your coding agent

Paste the following into your coding tool after replacing the bracketed values. It is written to make the agent inspect your existing project first rather than blindly assume a framework.

Add a transactional welcome-email integration using Volanea to this app.

First inspect the repository and identify the server-side signup completion point. Do not put the Volanea API key in browser code, public environment variables, or client components.

Requirements:
- Add a server-only function named sendWelcomeEmail.
- Read the API key from VOLANEA_API_KEY.
- Call POST https://api.volanea.com/v1/send with Authorization: Bearer <key>.
- Send JSON with from, to, subject, text, and html fields.
- Use the verified sender "Acme <hello@example.com>".
- Send to the newly created user's email address only after user creation succeeds.
- Include a plain-text version and escape any user-provided value used in HTML.
- Set an Idempotency-Key derived from the stable user ID, for example welcome:<userId>. Do not use a new random UUID for every retry.
- If email sending fails, log enough server-side context to debug it, but do not log the API key, reset tokens, or full sensitive message content.
- Do not fail or roll back a completed signup solely because the welcome email fails; return a successful signup and surface the email failure to server logs.
- Add a small test or a clearly isolated function that can be mocked.
- Add VOLANEA_API_KEY to the environment-variable example file without a real key.
- Explain which files you changed and how to test with a Volanea test key.

Use the project's existing language, routing conventions, and validation utilities. Do not install an email SDK unless the repository already uses one.

This prompt does more than produce code. It instructs the agent to discover the existing signup lifecycle, preserves the security boundary, and makes a reasonable product choice: a welcome email should not normally prevent a valid new account from being created.

For password resets, change the failure policy. You may still return a generic response to avoid leaking whether an email address exists, but you should treat the delivery attempt as a security-relevant operation and monitor it closely.

The resulting code: a server-side TypeScript email function

Here is a framework-neutral TypeScript implementation your agent can adapt for a server route, server action, API handler, job worker, or signup service. It relies only on standard fetch and crypto.randomUUID is not used for the production idempotency key because retries need the same value.

// lib/email/send-welcome-email.ts

type WelcomeEmailInput = {
  userId: string;
  email: string;
  firstName?: string | null;
};

function escapeHtml(value: string): string {
  return value
    .replaceAll("&", "&amp;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#039;");
}

export async function sendWelcomeEmail({
  userId,
  email,
  firstName,
}: WelcomeEmailInput) {
  const apiKey = process.env.VOLANEA_API_KEY;

  if (!apiKey) {
    throw new Error("VOLANEA_API_KEY is not configured");
  }

  const safeName = firstName?.trim() ? escapeHtml(firstName.trim()) : "there";
  const greetingText = firstName?.trim() ? `Hi ${firstName.trim()},` : "Hi there,";

  const response = await fetch("https://api.volanea.com/v1/send", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `welcome:${userId}`,
    },
    body: JSON.stringify({
      from: "Acme <hello@example.com>",
      to: email,
      subject: "Welcome to Acme",
      text: `${greetingText}\n\nWelcome to Acme. Your account is ready.\n\nVisit your dashboard: https://app.example.com/dashboard`,
      html: `
        <!doctype html>
        <html lang="en">
          <body style="margin:0;padding:24px;font-family:Arial,sans-serif;color:#1f2937;line-height:1.5;">
            <h1 style="font-size:24px;">Hi ${safeName},</h1>
            <p>Welcome to Acme. Your account is ready.</p>
            <p>
              <a href="https://app.example.com/dashboard">Open your dashboard</a>
            </p>
          </body>
        </html>
      `,
    }),
  });

  if (!response.ok) {
    const responseText = await response.text();

    throw new Error(
      `Volanea welcome email request failed: ${response.status} ${responseText}`,
    );
  }

  return response.json();
}

The from address in this example is a placeholder. Replace it with an address on your actual verified domain. The dashboard URL is also a placeholder; pull it from a trusted server configuration value if your app has different preview and production domains.

Calling it after signup

The exact location varies by framework, but the ordering matters. Create the user first, then call the email function. Catch the email failure separately so it does not accidentally undo a successful account creation.

const user = await users.create({
  email: input.email,
  firstName: input.firstName,
  passwordHash,
});

try {
  await sendWelcomeEmail({
    userId: user.id,
    email: user.email,
    firstName: user.firstName,
  });
} catch (error) {
  logger.error({ userId: user.id, error }, "Welcome email was not accepted");
}

return { userId: user.id };

For a higher-volume or more critical system, put the send request behind a durable queue or outbox table instead of making it inline with signup. The same stable idempotency key remains valuable: a worker retry can reuse welcome:<userId> without creating a second welcome message for the same event.

Why the idempotency key matters more than it first appears

Email is a side effect. If your server sends a request, waits too long, and times out, it may not know whether Volanea received the original request. An automatic retry without protection can send two identical emails.

That is annoying for a welcome email and potentially harmful for a receipt, password reset, invitation, or security notification. An idempotency key tells the API that repeated requests represent the same operation. Reuse the same key only for the same business event and same payload.

Good idempotency keys are stable and specific:

welcome:<userId> for the one welcome event associated with a user.
receipt:<paymentProviderEventId> for a payment receipt.
invite:<inviteId> for an organization invitation.
reset:<resetRequestId> for a password-reset request.

Bad idempotency keys are random values generated separately for every attempt. A random key makes every retry look new, defeating the duplicate-protection purpose. Equally risky is reusing one generic key, such as welcome-email, for unrelated users.

Your agent should derive the key from a server-trusted identifier, not a value supplied by the browser. That makes the behavior inspectable and avoids a malicious or accidental client controlling how your app deduplicates important events.

Test without turning a prototype into a production incident

AI agents are excellent at proposing a happy-path test. Ask them to test the unpleasant paths too: missing configuration, invalid email input, network failure, duplicate event delivery, and an unverified sender domain.

Start with a Volanea test key. Test-mode sends render and log like live messages without delivering them, which lets you inspect the shape of the integration before a real recipient is involved.

Use this checklist after your agent makes the change:

Confirm VOLANEA_API_KEY is available to the server runtime and absent from browser bundles.
Trigger signup with a test account and confirm the server makes one email request.
Trigger the exact same event again or retry the worker and confirm the stable idempotency behavior is intentional.
Inspect the message rendering for a greeting with a normal first name, no first name, and characters such as <, &, and quotes.
Confirm the plain-text version is understandable without HTML.
Replace the test key only after the sender domain is verified and the email content is approved.
Send to a real inbox you control and check the sender, subject, links, and reply path.

Do not consider an integration finished just because the agent's terminal reports a 200-level result. That result confirms request handling, while the full email lifecycle can still include suppression logic, asynchronous delivery, recipient mailbox filtering, bounces, or complaints.

Password reset email: similar API call, stricter product rules

A password reset uses the same general integration pattern, but it deserves different guardrails. The reset link is sensitive, the request may be abused, and your product should not disclose whether an account exists.

A sound reset flow looks like this:

Accept the email address and always return a neutral message such as "If an account exists, we sent instructions."
Rate-limit requests by account, IP address, and other appropriate signals.
Generate a short-lived, single-use reset token on the server.
Store only the data your authentication design requires, preferably in a form that limits the impact of database exposure.
Build a reset URL using a trusted application origin, never a host value supplied by the incoming request.
Send the message with an idempotency key linked to the reset-request ID.
Record operational data without logging the raw token or full reset URL.

Do not ask an agent to "make password reset email work" and accept whatever it writes. Give it those requirements explicitly, then review the token storage, expiry, route authorization, and logging behavior as carefully as you would review the email call.

The email API is only one link in the security chain. A perfectly delivered reset email can still be unsafe if its token never expires or its reset endpoint trusts unvalidated input.

MCP and tool calling: useful, but not required for your app integration

The agent-email ecosystem is emerging quickly, and terminology can be confusing. A coding agent may use ordinary repository access, a documentation skill, a command-line interface, or an MCP server. Those are different ways of helping an agent understand or operate a service.

Volanea has an MCP server endpoint for compatible clients. In broad terms, MCP lets an AI client discover tools and call them through a controlled interface. An authenticated agent could use such tools to check project state, inspect domains, create or render assets, run test sends, or investigate email activity.

That can reduce setup friction during development, but it is not a substitute for application code. Your deployed app should still use a server-side API call or SMTP configuration with its own carefully scoped credentials. An agent tool helps build and operate the integration; it does not eliminate the need for your application to decide when a user should receive a message.

Use MCP or tool calling cautiously:

Prefer OAuth or a restricted test credential while an agent explores the account.
Review any action that can send externally, alter domains, change workflows, or create campaign content.
Do not grant an autonomous agent broad production access merely to generate a welcome-email function.
Keep a human approval step for high-impact sends and bulk communications.

The practical recommendation for most first-time builders is simple: use your agent to write the server-side REST integration shown above. Consider MCP later when you want the agent to help with repeatable setup, testing, diagnosis, or account operations.

Common agent-generated email mistakes—and the correction

The speed of agent coding makes small mistakes easy to ship. Most are predictable, so you can catch them with a short review.

Putting the API key in the frontend

The mistake: The agent writes a fetch call in a React component, mobile app, or browser action because it is easiest to demonstrate.

The correction: Move the request to a server route, action, worker, or backend service. Browser code calls your authenticated application endpoint; only the server calls Volanea.

Using a random idempotency key on every request

The mistake: The agent generates crypto.randomUUID() immediately before every send.

The correction: Derive the key from a stable business-event identifier. Generate a random ID once when creating the event only if your system persists and reuses it for retries.

Treating a send response as final delivery

The mistake: The UI tells users "Email delivered" as soon as the application receives an API response.

The correction: Say "Email sent" or "Check your inbox" when appropriate. Use delivery events and logs for operational truth.

Inserting user input straight into HTML

The mistake: The email template includes a user's name, project name, or message without escaping HTML.

The correction: Escape user-supplied strings or use a proven template renderer that does it by default. Keep links and sensitive tokens generated from trusted server state.

Making a non-critical email block the user journey

The mistake: A transient email-service failure prevents signup from finishing.

The correction: For non-critical messages, complete the core action and queue or log the email retry. For security-sensitive flows, design user-facing responses and monitoring intentionally instead of relying on accidental exception behavior.

Building a campaign system when the app needs one receipt

The mistake: The agent creates contact lists, automations, and a campaign workflow for an order confirmation.

The correction: Start with the transaction-triggered send. Add templates or broader lifecycle workflows when there is a real repeatable need.

From first email to a maintainable email layer

Once welcome email works, resist copying the same request body into five different route handlers. Ask your agent to consolidate the integration behind a small email module with named functions such as sendWelcomeEmail, sendPasswordResetEmail, and sendOrganizationInviteEmail.

The module should own provider-specific details: endpoint, headers, sender configuration, idempotency conventions, response parsing, and safe error reporting. Individual application features should own their trigger conditions and their business data.

A useful next-stage structure might include:

lib/email/client.ts for the low-level Volanea request function.
lib/email/templates.ts for trusted message builders.
lib/email/send-welcome-email.ts for the welcome use case.
lib/email/send-password-reset-email.ts for security-sensitive reset messages.
lib/email/types.ts for shared message and event types.
tests/email/ for mocked request and rendering tests.

This separation makes it easier to change a sender address, add a reply-to policy, migrate from inline sends to a queue, or introduce reusable provider templates later. It also gives your agent a stable place to work next time instead of encouraging it to scatter raw API calls through the repository.

As your send volume grows, review transactional email pricing and sending costs alongside your architecture. The meaningful cost is not only messages sent; it is also the operational cost of duplicate messages, unclear logs, poor sender reputation, and time spent repairing an improvised integration.

FAQ

Can Agents send Volanea email directly from my app?

Your deployed app should send through a server-side Volanea REST or SMTP integration. An AI coding agent can write, test, and maintain that integration, but a browser client should never contain the secret email API key.

Does Volanea require a native Agents plugin?

No. A standard server-side REST call is enough to add transactional email. Compatible AI clients can also use MCP-style tool calling for assisted setup and operations, but that is optional and separate from the application integration.

What should I tell my agent to build first?

Start with one event that is easy to verify, usually a welcome email after successful signup. Require server-only secrets, a verified sender, HTML plus plain text, stable idempotency, and a test-key workflow.

Should a welcome email failure block signup?

Usually no. Create the account first, then send or queue the welcome email. Log failures for retry and diagnosis. Password reset, verification, and security messages need more deliberate failure handling because the email may be necessary for the user to continue.

Can I use the same pattern for password reset emails?

Yes, but add reset-specific safeguards: a short-lived single-use token, rate limits, generic responses that do not reveal account existence, a trusted application URL, and careful logging that never includes the token.

Agents Transactional Email for AI-Built Apps