← Public packages
@kody/agent-mail
AgentMail inboxes for agents: create/list inboxes, messages, threads, and Svix webhook ingress.
Files
import { agentMailRequest, clean, requireConfirmOrDryRun } from './core.ts'
import { listPath, normalizeEntry, slimEntry, type ListSelectorInput } from './lists.ts'
export type AddRuleInput = ListSelectorInput & {
/** Email address (`partner@example.com`) or domain (`example.com`). */
entry?: string
/** Alias for `entry`. */
match?: string
/** Optional reason; AgentMail only stores it on block lists. */
reason?: string
/** Preview the request without calling AgentMail. */
dryRun?: boolean
/** Required true for a live create (unless dryRun). */
confirm?: boolean
}
/**
* Add an email address or domain to an AgentMail allow or block list.
* Requires confirm: true for a live POST, or dryRun: true to preview.
* Uses POST /v0/lists/{direction}/{type} (or /v0/pods/{podId}/... or
* /v0/inboxes/{inboxId}/...). AgentMail enforces lists natively:
* - receive allow: once non-empty, only matching senders are accepted
* (allowlist-only mode for that scope)
* - receive block: matching senders are rejected
* - reply lists apply instead of receive lists to replies to your mail
* - inbox scope beats pod beats organization when a scope has a match
*
* @param input.type - `allow` or `block` (required)
* @param input.entry - Email address or domain (or `match`)
* @param input.direction - `receive` (default), `reply`, or `send`
* @param input.inboxId - Optional inbox scope
* @param input.podId - Optional pod scope
* @param input.reason - Optional reason (block lists)
* @param input.dryRun - Preview without creating
* @param input.confirm - Must be true for a live create
* @returns Created entry or dry-run preview
*
* @example
* import addRule from 'kody:@kody/agent-mail/add-rule'
* const preview = await addRule({
* type: 'allow',
* entry: 'my-other-harness@agentmail.to',
* inboxId: 'prime@agentmail.to',
* dryRun: true,
* })
*/
export default async function addRule(input: AddRuleInput) {
const mode = requireConfirmOrDryRun(input, 'add a live AgentMail list entry')
const { entry, entryType } = normalizeEntry(input.entry ?? input.match)
const target = listPath(input)
const body: Record<string, unknown> = { entry }
const reason = clean(input.reason)
if (reason && target.type === 'block') body.reason = reason
const base = {
scope: target.scope,
scopeId: target.scopeId,
direction: target.direction,
type: target.type,
entryType,
}
if (mode === 'dryRun') {
return {
dryRun: true as const,
...base,
method: 'POST',
path: target.path,
body,
...(reason && target.type !== 'block'
? { note: 'reason is ignored on allow lists' }
: {}),
}
}
const raw = await agentMailRequest({
method: 'POST',
path: target.path,
body,
label: 'AgentMail create list entry',
})
return { dryRun: false as const, ...base, entry: slimEntry(raw) }
}