[opensourcedex]

AgentMail is a free, open source email & communication project written in TypeScript and released under MIT. It has 38 GitHub stars, 17 forks and 3 open issues, and was last pushed 28 hours ago. On this registry it ranks #13 of 13 tracked projects in Email & Communication, with 5 head-to-head comparisons available.

What is AgentMail?

AgentMail is a TypeScript client library and inbox API for AI agents and workflows, aimed at developers who need to give agents their own email inboxes rather than route everything through a human mailbox.

What it is

AgentMail is the Agentmail TypeScript library, an SDK published to npm as agentmail that provides convenient access to the Agentmail APIs from TypeScript. It lives in the TypeScript/Node ecosystem and is generated with Fern, which shapes much of its structure: subpackage exports, typed request and response interfaces, configurable environments, and per-request controls such as retries, timeouts, and request abortion.

The concrete problem it solves is the gap between an agent that can reason and an agent that can send and receive mail. Rather than writing raw HTTP calls, handling status codes, and parsing responses by hand, a developer instantiates AgentMailClient with an API key and calls typed methods such as client.inboxes.create(undefined). The library replaces hand-rolled email plumbing and ad hoc inbox handling for agent workloads — the thing it substitutes for is a bespoke integration layer between an agent and an email service, not a mail server itself.

Key capabilities

  • Inbox provisioning through client.inboxes.create(), with list operations typed as AgentMail.ListInboxesRequest.
  • Environment switching via AgentMailEnvironment.Prod so the same client code can point at different API endpoints.
  • Typed request and response interfaces exported under the AgentMail namespace, covering both directions of every call.
  • Structured error handling: non-success status codes throw a subclass of AgentMailError exposing statusCode, message, body, and rawResponse.
  • Binary response support through the BinaryResponse type, consumable as stream(), arrayBuffer(), blob(), or bytes(), with a bodyUsed flag; the README demonstrates saving client.domains.getZoneFile() output to disk.
  • Per-request retries, timeouts, and aborting, plus access to raw response data and logging.
  • Custom fetch support, additional headers, additional query string parameters, and documented runtime compatibility.

Who uses it and how

  • Backend and platform teams building Node.js or TypeScript services where each agent gets an inbox it can act on programmatically.
  • Agent and automation developers who need mail as a first-class tool call rather than a side channel, using the typed client inside an existing worker or service.
  • Teams that need DNS-level control alongside messaging, since the SDK exposes client.domains.getZoneFile() for domain configuration output.
  • Integrations where custom fetch, additional headers, or extra query parameters are required — for example, routing through a proxy or attaching tracing metadata.
  • Projects that must distinguish email failures from other faults, using AgentMailError and its statusCode and rawResponse fields.

Getting started

Install with npm i -s agentmail, then instantiate const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" }) and call methods such as client.inboxes.create(undefined). A full reference for the library is linked from the repository's reference.md.

How it compares

No comparable or competing tools are named in the available facts, so AgentMail stands alone in this registry on the evidence provided. Nothing here establishes how it stacks up against other email APIs or SDKs, and no claim to that effect should be inferred.

When to use it — and when not to

Use it when building TypeScript or Node services that need agents to own inboxes and you are content to call a hosted API, since the SDK targets the Agentmail APIs and selects an environment rather than shipping server components. The README covers only the client library: it documents no database, storage, SMTP setup, or self-hosting path, so anyone who must keep mail on their own infrastructure, or who needs a language other than TypeScript, should look elsewhere. The repository shows 38 stars, 17 forks, and 3 open issues with no topics listed, so the surrounding documentation and community are thin relative to the surface area of the SDK; verify the hosted service's terms and availability before depending on it in production.

project readme (upstream, from github) — read inline

Agentmail TypeScript Library

fern shield npm shield

The Agentmail TypeScript library provides convenient access to the Agentmail APIs from TypeScript.

Table of Contents

Installation

npm i -s agentmail

Reference

A full reference for this library is available here.

Usage

Instantiate and use the client with the following:

import { AgentMailClient } from "agentmail";

const client = new AgentMailClient({ apiKey: "YOUR_API_KEY" });
await client.inboxes.create(undefined);

Environments

This SDK allows you to configure different environments for API requests.

import { AgentMailClient, AgentMailEnvironment } from "agentmail";

const client = new AgentMailClient({
    environment: AgentMailEnvironment.Prod,
});

Request and Response Types

The SDK exports all request and response types as TypeScript interfaces. Simply import them with the following namespace:

import { AgentMail } from "agentmail";

const request: AgentMail.ListInboxesRequest = {
    ...
};

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown.

import { AgentMailError } from "agentmail";

try {
    await client.inboxes.create(...);
} catch (err) {
    if (err instanceof AgentMailError) {
        console.log(err.statusCode);
        console.log(err.message);
        console.log(err.body);
        console.log(err.rawResponse);
    }
}

Binary Response

You can consume binary data from endpoints using the BinaryResponse type which lets you choose how to consume the data:

const response = await client.domains.getZoneFile(...);
const stream: ReadableStream<Uint8Array> = response.stream();
// const arrayBuffer: ArrayBuffer = await response.arrayBuffer();
// const blob: Blob = response.blob();
// const bytes: Uint8Array = response.bytes();
// You can only use the response body once, so you must choose one of the above methods.
// If you want to check if the response body has been used, you can use the following property.
const bodyUsed = response.bodyUsed;
Save binary response to a file
Node.js
ReadableStream (most-efficient)
import { createWriteStream } from 'fs';
import { Readable } from 'stream';
import { pipeline } from 'stream/promises';

const response = await client.domains.getZoneFile(...);

const stream = response.stream();
const nodeStream = Readable.fromWeb(stream);
const writeStream = createWriteStream('path/to/file');

await pipeline(nodeStream, writeStream);
ArrayBuffer
import { writeFile } from 'fs/promises';

const response = await client.domains.getZoneFile(...);

const arrayBuffer = await response.arrayBuffer();
await writeFile('path/to/file', Buffer.from(arrayBuffer));
Blob
import { writeFile } from 'fs/promises';

const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
const arrayBuffer = await blob.arrayBuffer();
await writeFile('output.bin', Buffer.from(arrayBuffer));
Bytes (UIntArray8)
import { writeFile } from 'fs/promises';

const response = await client.domains.getZoneFile(...);

const bytes = await response.bytes();
await writeFile('path/to/file', bytes);
Bun
ReadableStream (most-efficient)
const response = await client.domains.getZoneFile(...);

const stream = response.stream();
await Bun.write('path/to/file', stream);
ArrayBuffer
const response = await client.domains.getZoneFile(...);

const arrayBuffer = await response.arrayBuffer();
await Bun.write('path/to/file', arrayBuffer);
Blob
const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
await Bun.write('path/to/file', blob);
Bytes (UIntArray8)
const response = await client.domains.getZoneFile(...);

const bytes = await response.bytes();
await Bun.write('path/to/file', bytes);
Deno
ReadableStream (most-efficient)
const response = await client.domains.getZoneFile(...);

const stream = response.stream();
const file = await Deno.open('path/to/file', { write: true, create: true });
await stream.pipeTo(file.writable);
ArrayBuffer
const response = await client.domains.getZoneFile(...);

const arrayBuffer = await response.arrayBuffer();
await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
Blob
const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
const arrayBuffer = await blob.arrayBuffer();
await Deno.writeFile('path/to/file', new Uint8Array(arrayBuffer));
Bytes (UIntArray8)
const response = await client.domains.getZoneFile(...);

const bytes = await response.bytes();
await Deno.writeFile('path/to/file', bytes);
Browser
Blob (most-efficient)
const response = await client.domains.getZoneFile(...);

const blob = await response.blob();
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
ReadableStream
const response = await client.domains.getZoneFile(...);

const stream = response.stream();
const reader = stream.getReader();
const chunks = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}

const blob = new Blob(chunks);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
ArrayBuffer
const response = await client.domains.getZoneFile(...);

const arrayBuffer = await response.arrayBuffer();
const blob = new Blob([arrayBuffer]);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
Bytes (UIntArray8)
const response = await client.domains.getZoneFile(...);

const bytes = await response.bytes();
const blob = new Blob([bytes]);
const url = URL.createObjectURL(blob);

// trigger download
const a = document.createElement('a');
a.href = url;
a.download = 'filename';
a.click();
URL.revokeObjectURL(url);
Convert binary response to text
ReadableStream
const response = await client.doma

readme truncated — read the full docs on github

Frequently asked questions

Is AgentMail free to use?

AgentMail is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does AgentMail do?

Email inbox API built for AI agents and workflows

What is AgentMail written in?

AgentMail is primarily written in TypeScript. Its source is publicly available at https://github.com/agentmail-to/agentmail-node, and it has 38 GitHub stars.