unit testing agent email in typescript with typed mocks

Your agent's test suite runs green. Every email function passes. Then you deploy, and the agent fires off 47 real emails to actual customers during a CI run. Someone forgot to mock the transport layer.

This happens more often than anyone will admit. And the problem compounds when email isn't a simple "fire and forget" call. Agents make decisions based on email content: parsing verification codes, routing based on sender, retrying after bounces, handling unsubscribes. The test surface is wide, and a careless mock hides bugs instead of catching them.

TypeScript should help. The type system gives you safety rails for defining email interfaces, matching response shapes, and catching mismatches at compile time. But most mocking approaches throw all of that away with as any casts the moment an email SDK gets involved. You end up with tests that compile, pass, and prove nothing about how your agent actually behaves.

This guide covers how to mock email dependencies in TypeScript without losing type safety, with a focus on agent workflows where email is part of a larger decision loop. Whether your agent creates its own inbox through auto-signup or uses a shared address, these patterns apply.

TypeScript email mocking libraries compared#

Five main approaches exist for mocking email in TypeScript tests. Each sits at a different abstraction level with different tradeoffs between type safety and setup effort.

The first three are general-purpose mocking libraries. They work for any TypeScript interface, including email. nodemailer-mock replaces Nodemailer's SMTP transport in-memory, which makes it a natural fit for projects already using Nodemailer, but it doesn't help when your agent uses a dedicated email API like LobsterMail. The last category, SDK-level mocking, means building a test double that mirrors your email provider's client interface, so agent code follows the same path in tests and production.

Three layers where you can intercept#

When an agent sends email, the call passes through at least three layers. Where you intercept determines what your test actually proves.

HTTP/transport layer#

Tools like msw (Mock Service Worker) or nock intercept outgoing HTTP requests before they leave the process. Your agent code and SDK client both run for real. Only the network call is faked.

import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  http.post('https://api.your-email-provider.com/v1/send', () => {
    return HttpResponse.json({
      id: 'msg_test_123',
      status: 'queued',
    });
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

This gives you high confidence because the full code path executes. It also makes it straightforward to simulate specific failures like 429 rate limits or 503 outages. If you're looking for patterns around testing agent email without hitting production, HTTP-layer interception is a solid starting point.

SDK/client layer#

Replace the email SDK instance with a typed stub. This is faster than HTTP-level mocking and isolates your agent logic from network serialization concerns.

import { mock, instance, when, verify, anything } from 'ts-mockito';
import type { EmailClient } from './email-client';

const mockClient = mock<EmailClient>();
when(mockClient.send(anything())).thenResolve({
  id: 'msg_test_456',
  status: 'queued',
});

const agent = new EmailAgent(instance(mockClient));
await agent.handleTask('send welcome email to user@example.com');

verify(mockClient.send(anything())).once();
ts-mockito generates mocks directly from TypeScript interfaces. No `as any`, no hand-typed return values. If your `EmailClient` interface changes (say, `send()` gains a required `priority` parameter), the mock breaks at compile time. That's exactly what you want from a typed mock.

For those unfamiliar: ts-mockito is a TypeScript mocking library inspired by Java's Mockito. It creates proxy objects that implement your interfaces and records calls for later verification with verify(). It works alongside Jest, Vitest, or Mocha without conflict.

Service abstraction layer#

Define your own interface that wraps the email provider. Mock that interface in tests. This decouples your agent from any specific SDK.

interface AgentMailer {
  send(to: string, subject: string, body: string): Promise<SendResult>;
  receive(inboxId: string): Promise<Email[]>;
  getInbox(name: string): Promise<Inbox>;
}

Mocking at this level is the fastest to write and easiest to maintain. The tradeoff: you're not testing the SDK integration path at all. Pair these unit tests with a small set of integration tests that hit a real sandbox environment to cover that gap.

Testing retry and fallback behavior#

Agents that send email need to handle failures. A 503 from the provider or a bounced address can't just crash the process. Your tests should verify the agent's response to these conditions, not just the happy path.

Here's a typed retry test using Jest:

const sendMock = jest.fn<Promise<SendResult>, [SendParams]>();

sendMock
  .mockRejectedValueOnce(new Error('503 Service Unavailable'))
  .mockResolvedValueOnce({ id: 'msg_789', status: 'queued' });

const agent = new EmailAgent({ send: sendMock } as AgentMailer);
const result = await agent.sendWithRetry({
  to: 'user@example.com',
  subject: 'Verification code',
  body: 'Your code is 4821',
});

expect(sendMock).toHaveBeenCalledTimes(2);
expect(result.status).toBe('queued');

The generic type on jest.fn() is doing real work here. Without <Promise<SendResult>, [SendParams]>, TypeScript can't verify that your mock returns the right shape. This is where most email test suites quietly fail: the mock accepts anything and returns anything, so the test passes even when the real implementation would throw a type error.

You should also test what happens when retries are exhausted. Does the agent fall back to a secondary provider? Log the failure and continue? Silently drop the message? Each behavior deserves an explicit test case, and a 429 should be tested separately from a 503 since the retry timing logic differs.

Mocking webhook events for agent state machines#

If your agent reacts to inbound email events (bounces, replies, delivery confirmations), you need to simulate those events in tests. Factory functions that produce realistic webhook payloads make this manageable:

function bounceEvent(overrides?: Partial<BounceEvent>): BounceEvent {
  return {
    type: 'bounce',
    recipient: 'invalid@example.com',
    reason: 'mailbox_full',
    timestamp: new Date().toISOString(),
    ...overrides,
  };
}

test('agent marks address as invalid after hard bounce', async () => {
  await agent.handleWebhook(bounceEvent({ reason: 'invalid_address' }));
  expect(agent.isAddressValid('invalid@example.com')).toBe(false);
});

For multi-step orchestration (send email, wait for reply, parse content, take action), chain your mocks into a sequence. jest.fn() supports .mockResolvedValueOnce() for exactly this purpose: each call returns the next value in the sequence, letting you simulate a realistic conversation timeline without any external dependencies.

Keeping mocks in sync as APIs evolve#

The biggest risk with any mock is drift. Your email provider ships a new SDK version. A field becomes required. A response shape changes. If your mocks don't break when this happens, they're actively hiding bugs.

Two practices that prevent drift:

1. Derive mock types from the real interface. Use jest.fn<ReturnType, ParamType>() or ts-mockito's mock<Interface>() instead of hand-writing mock objects. When the interface changes, the compiler catches it immediately.

2. Run at least one integration test against a real sandbox. Mocks verify logic. Integration tests verify compatibility. Even a single test that creates an inbox, sends an email, and reads it back catches drift that no mock will surface.

The right split for most agent projects is 80% unit tests with typed mocks for speed and 20% integration tests against a real environment for confidence. Unit tests run in milliseconds and cover branching logic. Integration tests take seconds but catch the things mocks structurally cannot.

Pick the right layer, then enforce the types#

If your agent treats email as simple outbound notifications, mock at the service abstraction layer and move on. If email events drive agent decisions (parsing replies, extracting verification codes), mock at the HTTP layer so you're testing the full deserialization path.

Whatever layer you choose, use TypeScript's type system to enforce the contract. Every as any in a test file is a spot where a real bug can hide undetected. ts-mockito and typed jest.fn() generics exist specifically to close those gaps. Combine them with one or two integration tests and you'll catch both logic errors and API drift before they reach production.

For agents that self-provision inboxes through LobsterMail, the same patterns apply to inbox creation, polling, and webhook handling. If you want to test against a real API, grab a free inbox here and write your first typed mock against the SDK.