Frameworks and agents · Published 2026-09-27 · Updated 2026-11-09 · AgentiSend
Send email from a LangChain.js agent
A send_email tool built with tool() from @langchain/core/tools that sends on the agent's own budgeted key and hands a refusal back to the model as code and fix.
To send email from a LangChain.js agent, give it one tool() from @langchain/core/tools whose function sends through the agent's own key and returns either the message id or the refusal's code and fix. The file below is that tool. It is run by the test suite against a local AgentiSend server, invoked directly with the arguments a model would produce: one send, the same call again replaying it, a third send refused once the key's budget is spent, and a call with no recipient refused by the schema before the API is reached.
Install
pnpm add @langchain/core zod agentisendEnvironment
| Variable | Required | What it is |
|---|---|---|
AGENTISEND_API_KEY | yes | The agent's key, with sending_access and a budget on it. Not your own. |
MAIL_FROM | yes | The From address, on a domain you have verified. |
AGENTISEND_BASE_URL | no | Defaults to https://api.agentisend.com. |
The tool
/**
* LangChain.js — a `send_email` tool for an agent that holds its own key.
*
* The key in `AGENTISEND_API_KEY` here is the agent's, not yours. It was
* minted with `POST /api-keys` as `sending_access`, given a ceiling with
* `PATCH /limits/keys/:id`, and `POST /limits/kill-all` stops it along with
* every other key. Those three calls run in examples/ai-agent-with-budget;
* this file is the other half, the tool the model calls once the key exists.
*
* Two rules make it safe to hand to a model. The idempotency key is derived
* from the purpose and the recipient, never from the moment, so a model that
* retries a timed-out call replays the first send instead of mailing someone
* twice. And a refusal is returned, not thrown: the model reads `code` and
* `fix` and acts on them — for `agent_budget_exceeded` and `approval_required`
* that means stopping and saying so, because the fix names a person.
*/
import { tool } from '@langchain/core/tools';
import { z } from 'zod';
import { AgentiSend, AgentiSendError } from 'agentisend';
/** The agent's own key: `sending_access`, with a budget on it. */
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;
}
/** What the model gets back: a message id, or a refusal it can act on. */
export type SendEmailResult =
| { sent: true; id: string }
| { sent: false; code: string; fix: string };
export const sendEmail = tool(
async ({ to, subject, text, purpose }): Promise<SendEmailResult> => {
try {
const { id } = await agentisend.emails.send(
{ from: mailFrom(), to, subject, text },
// Derived from the thing being done, not from the moment it was asked
// for: a retry after a timeout replays the first send.
{ idempotencyKey: `${purpose}/${to}` },
);
return { sent: true, id };
} catch (err) {
if (err instanceof AgentiSendError) {
// The API checked the address, the suppression list, the budget and
// the loop guard, and the refusal names its fix. The model can read
// that; it cannot read an exception.
return { sent: false, code: err.code, fix: err.fix };
}
throw err;
}
},
{
name: 'send_email',
description:
'Send one email to a person who asked for it. Returns the message id, or a refusal ' +
'with a code and a fix. When the fix says a person decides, stop and report it: ' +
'calling again will not change the answer.',
schema: z.object({
to: z.string().describe('The recipient, one address.'),
subject: z.string().min(1).max(200),
text: z.string().min(1).describe('The plain-text body.'),
purpose: z
.string()
.regex(/^[a-z0-9][a-z0-9_-]{0,63}$/)
.describe(
'What this message is, for example "ticket-4182-update". The same purpose to the ' +
'same recipient sends once, however many times it is called.',
),
}),
},
);Wire it to a model
import { createAgent } from 'langchain';
import { sendEmail } from './send-email-tool';
const agent = createAgent({ model, tools: [sendEmail] });
await agent.invoke({
messages: [{ role: 'user', content: 'Tell customer@example.com that ticket 4182 is being looked into.' }],
});LangChain checks the model's arguments against schema before the function runs, and serialises what the function returns into the tool message the model reads next. A refusal arrives as { sent: false, code, fix }, and the fix is written for that reader: it says what to do and which call does it, or that a person decides and a retry will not change the answer.
The key the agent holds
The agent gets a key of its own, minted with sending_access and given a budget before createAgent sees the tool. The calls that mint it, set the ceiling, kill it and trip the loop guard are run in An AI agent with a budget and a loop guard. Each of them reaches the model the same way as any other refusal: through the tool message LangChain builds from the function's return value, so a killed key or a spent budget reads as { sent: false, code, fix } and the agent can stop.
The idempotency key
The tool derives Idempotency-Key from the purpose argument and the recipient, never from the time. A model may repeat a tool call it is unsure about, and a repeated call with the same purpose returns the first send's id instead of mailing the person twice. The purpose field's description in the zod schema tells the model to name the message, not the moment: ticket-4182-update and ticket-4182-closed are two sends.
Next
Examples
Prompt for your coding agent
1. Install
npm install agentisend2. Environment
AGENTISEND_API_KEY
MAIL_FROM
AGENTISEND_BASE_URL=https://api.agentisend.com3. Send call
/**
* LangChain.js — a `send_email` tool for an agent that holds its own key.
*
* The key in `AGENTISEND_API_KEY` here is the agent's, not yours. It was
* minted with `POST /api-keys` as `sending_access`, given a ceiling with
* `PATCH /limits/keys/:id`, and `POST /limits/kill-all` stops it along with
* every other key. Those three calls run in examples/ai-agent-with-budget;
* this file is the other half, the tool the model calls once the key exists.
*
* Two rules make it safe to hand to a model. The idempotency key is derived
* from the purpose and the recipient, never from the moment, so a model that
* retries a timed-out call replays the first send instead of mailing someone
* twice. And a refusal is returned, not thrown: the model reads `code` and
* `fix` and acts on them — for `agent_budget_exceeded` and `approval_required`
* that means stopping and saying so, because the fix names a person.
*/
import { tool } from '@langchain/core/tools';
import { z } from 'zod';
import { AgentiSend, AgentiSendError } from 'agentisend';
/** The agent's own key: `sending_access`, with a budget on it. */
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;
}
/** What the model gets back: a message id, or a refusal it can act on. */
export type SendEmailResult =
| { sent: true; id: string }
| { sent: false; code: string; fix: string };
export const sendEmail = tool(
async ({ to, subject, text, purpose }): Promise<SendEmailResult> => {
try {
const { id } = await agentisend.emails.send(
{ from: mailFrom(), to, subject, text },
// Derived from the thing being done, not from the moment it was asked
// for: a retry after a timeout replays the first send.
{ idempotencyKey: `${purpose}/${to}` },
);
return { sent: true, id };
} catch (err) {
if (err instanceof AgentiSendError) {
// The API checked the address, the suppression list, the budget and
// the loop guard, and the refusal names its fix. The model can read
// that; it cannot read an exception.
return { sent: false, code: err.code, fix: err.fix };
}
throw err;
}
},
{
name: 'send_email',
description:
'Send one email to a person who asked for it. Returns the message id, or a refusal ' +
'with a code and a fix. When the fix says a person decides, stop and report it: ' +
'calling again will not change the answer.',
schema: z.object({
to: z.string().describe('The recipient, one address.'),
subject: z.string().min(1).max(200),
text: z.string().min(1).describe('The plain-text body.'),
purpose: z
.string()
.regex(/^[a-z0-9][a-z0-9_-]{0,63}$/)
.describe(
'What this message is, for example "ticket-4182-update". The same purpose to the ' +
'same recipient sends once, however many times it is called.',
),
}),
},
);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 header5. 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.