@kody/agent-mail

@kody/agent-mail — agent notes

Human setup and intent live in README.md. This file is for agents: import paths, smoke / dryRun execute snippets, edge cases, and fork setup. Secrets by name only — never paste API keys, webhook URLs, or whsec_… values into chat.

Secrets / auth names

Save URL for the API key:

https://kody.codes/account/secrets/new?name=agentmailApiKey&allowedHosts=api.agentmail.to,api.agentmail.eu&scope=user

Import paths

Prefer named exports over the package root. Prefer typed helpers over agentMailRequest from core.

Smoke test (read-only)

After agentmailApiKey is saved and the host is approved:

import smokeTest from 'kody:@kody/agent-mail/smoke-test'

export default async function main() {
	return await smokeTest()
	// => { ok: true, whoami?, inboxCount, inboxesSample, nextPageToken }
}

Lighter read-only check:

import listInboxes from 'kody:@kody/agent-mail/list-inboxes'

export default async function main() {
	return await listInboxes({ limit: 5 })
}

dryRun / confirm (mutations)

send-message, reply-to-message, and create-webhook require dryRun: true or confirm: true. Always prefer dry-run first:

import sendMessage from 'kody:@kody/agent-mail/send-message'

export default async function main() {
	return await sendMessage({
		inboxId: 'inbox_123',
		to: 'user@example.com',
		subject: 'Hello',
		text: 'Hi from an agent',
		dryRun: true,
	})
}

import replyToMessage from 'kody:@kody/agent-mail/reply-to-message'

export default async function main() {
	return await replyToMessage({
		inboxId: 'inbox_123',
		messageId: 'msg_123',
		text: 'Thanks — got it.',
		dryRun: true,
	})
}

import createWebhook from 'kody:@kody/agent-mail/create-webhook'

export default async function main() {
	return await createWebhook({
		url: 'https://example.invalid/inbound',
		eventTypes: ['message.received'],
		dryRun: true,
	})
}

create-inbox creates an inbox but does not auto-send. Use clientId for idempotent creates. Treat any returned AgentMail webhook secret as a credential — save as agentmailWebhookSecret, never paste into chat.

Edge cases

• Default API base is https://api.agentmail.to. Approve api.agentmail.eu as well if the caller's secret/host setup uses the EU API.
• Platform webhook verification cannot do Svix; handle-webhook verifies when agentmailWebhookSecret is present. Minted package webhook URLs are credentials — do not commit or paste them.
• requireConfirmOrDryRun throws if neither dryRun nor confirm: true is set on guarded writes.
• Prefer list-inboxes / smoke-test for auth checks before any send.

Fork / setup for agents

1. Fork this listing into the caller's account if they need their own AgentMail wiring (communityFork / adopt as appropriate).
2. Save the caller's agentmailApiKey (and optional agentmailWebhookSecret) with hosts approved; clear any pending_secret_package_approvals.
3. Smoke-test with kody:@kody/agent-mail/smoke-test from execute (read-only).
4. Keep brand/, icon.png, and community-icon.png intact unless deliberately updating official AgentMail artwork.
5. Do not disable the package inbound webhook or related jobs/webhooks.