SDKs

Both SDKs are thin, hand-written clients over the REST API. They cover the calls a test suite makes; anything else is a plain HTTP request with the same bearer key.

TypeScript

Node 18 or newer, or any runtime with fetch.

npm install --save-dev @mailcatchr/sdk

import { createClient } from "@mailcatchr/sdk";

const mc = createClient({ apiKey: process.env.MAILCATCHR_API_KEY! });

Method	Calls
mc.mailboxes.list()	GET /v1/mailboxes
mc.mailboxes.create(workspaceId, { name, subdomain?, retentionDays?, groupId? })	POST /v1/workspaces/{id}/mailboxes/
mc.messages.list(mailboxId, { limit?, before? })	GET /v1/mailboxes/{id}/messages
mc.messages.get(mailboxId, messageId)	GET /v1/mailboxes/{id}/messages/{id}
mc.messages.await(mailboxId, { to?, subject?, from?, since?, timeoutSeconds? })	GET …/messages/await; resolves to null on timeout
mc.send(mailboxId, { from, to, subject, textBody?, htmlBody?, cc?, bcc?, replyTo? })	POST /v1/mailboxes/{id}/send
mc.totps.code(totpId)	GET /v1/totp/{id}/code

Pass baseUrl to target another host and fetch to inject a polyfill or a mock. Errors throw MailcatchrError with the HTTP status and the parsed error body.

C#

.NET 8 or newer.

dotnet add package Mailcatchr.Sdk

using var mc = new MailcatchrClient(new MailcatchrClientOptions { ApiKey = apiKey });

Method	Calls
ListMailboxesAsync()	GET /v1/mailboxes
CreateMailboxAsync(workspaceId, name, retentionDays?, subdomain?, groupId?)	POST /v1/workspaces/{id}/mailboxes/
ListMessagesAsync(mailboxId, limit?, before?)	GET /v1/mailboxes/{id}/messages
GetMessageAsync(mailboxId, messageId)	GET /v1/mailboxes/{id}/messages/{id}
AwaitMessageAsync(mailboxId, subject?, from?, to?, since?, timeout?)	GET …/messages/await; returns null on timeout
SendAsync(mailboxId, request)	POST /v1/mailboxes/{id}/send

TOTP codes and webhook interceptors are not wrapped in the C# client yet. Call them with HttpClient and the bearer header; the API reference has the shapes.

Versioning

The API is v1 and only changes additively. SDK versions follow semantic versioning against it. A new API field never breaks an older SDK.