Skip to content

API Reference: Emails

TypeScript SDK reference for email: waiting for mail, codes and links, parsed fields and attachments, sending test emails and the email entry point.

Updated Nov 2026

Part of the TypeScript SDK API reference. The constructor, endpoints and direct delivery are on the first page.

Emails

Every endpoint on an account receives email at <slug>@mailhooks.cc, and at <slug>+<tag>@mailhooks.cc for any tag. Guest endpoints receive none. A captured email is a request with kind: "email", method: "EMAIL", the recipient address as path, the raw message as body, and the parsed message as email; the SDK types it as EmailRequest. Each email counts as one request against your quota. See Email capture for what is stored.

Use a fresh tag per test run, so each run finds its own email:

import { extractCode } from "@webhooks-cc/sdk";
 
const runId = `signup-${Date.now()}`;
await signUp(client.emails.address(slug, runId)); // your app sends the email
 
const email = await client.emails.waitFor(slug, { tag: runId });
const code = extractCode(email); // "482913"

list, latest, waitFor and waitForAll filter by the same criteria. Every criterion you pass must match:

CriterionTypeMatches
tagstring | nullThe address's +tag, exactly (tags are case-sensitive). null matches untagged mail only
subjectstring | RegExpA string matches when the subject contains it; a RegExp is tested against the subject
fromstring | RegExpAny From address. A string must equal the address (case-insensitive); a RegExp is tested against Name <address>
tostring | RegExpAny To or Cc address, or the address the email was delivered to, with the same rules as from
GET(local)

client.emails.address

The address an endpoint receives email at, with an optional tag. Pass the endpoint object (from endpoints.create() or endpoints.get()) to use the address the server reports; a slug builds the address with the client's emailDomain. Throws on an invalid slug or tag. A tag is printable ASCII without spaces, quotes, brackets, @, ,, ; or :, and the slug, the + and the tag together are at most 64 characters.

address(endpoint: string | Pick<Endpoint, "slug" | "emailAddress">, tag?: string): string
client.emails.address("my-app"); // "my-app@mailhooks.cc"
client.emails.address("my-app", "run-42"); // "my-app+run-42@mailhooks.cc"
GET/endpoints/:slug/requests?kind=email

client.emails.list

Emails an endpoint captured, newest first, filtered by the criteria above.

list(endpointSlug: string, options?: ListEmailsOptions): Promise<EmailRequest[]>
ParamTypeRequiredDescription
endpointSlugstringyesEndpoint slug
tag, subject, from, tocriterianoSee the criteria table
limitnumbernoHow many of the newest emails to fetch before filtering (default: 50)
sincenumbernoOnly emails received after this timestamp (ms)
GET/requests/:id

client.emails.get

One captured email by request ID, with the endpoint's named fields as emailFields and the reply text as replyText. Throws NotFoundError when the request is not an email.

get(requestId: string): Promise<EmailRequest>
GET/endpoints/:slug/requests?kind=email

client.emails.latest

The newest email matching the criteria, or null. Looks at the 100 newest emails.

latest(endpointSlug: string, criteria?: EmailCriteria): Promise<EmailRequest | null>
GET/endpoints/:slug/requests?kind=email

client.emails.waitFor

Poll until an email matching the criteria arrives. Throws TimeoutError when none does.

waitFor(endpointSlug: string, options?: WaitForEmailOptions): Promise<EmailRequest>
ParamTypeRequiredDescription
endpointSlugstringyesEndpoint slug
tag, subject, from, tocriterianoSee the criteria table
timeoutnumber | stringnoMax wait time, ms or a duration like "30s" (default: 60000)
pollIntervalnumber | stringnoInterval between polls (default: 1000)
sincenumbernoOnly emails received after this timestamp in ms (default: 5 minutes ago)
match(email: EmailRequest) => booleannoExtra filter on top of the criteria

The five-minute lookback finds an email that arrived just before the call. Use a fresh tag, or pass since: Date.now() before triggering the email, so an older email cannot match.

GET/endpoints/:slug/requests?kind=email

client.emails.waitForAll

Poll until count matching emails have arrived. Returns them oldest first. Takes the same options as waitFor, plus count.

waitForAll(endpointSlug: string, options: WaitForEmailsOptions): Promise<EmailRequest[]>
POST/send-test-email

client.emails.sendTest

Deliver a sample email with a six-digit code and a link to an endpoint, optionally to a tagged address. It is captured and counted like any other email, but it does not travel over SMTP, so no sender checks run on it and email.smtp.test is true. Rate limited to 10 per minute.

sendTest(endpointSlug: string, options?: { tag?: string }): Promise<SendTestEmailResult>
// Returns: { status: "captured", requestId: string | null }
GET(local)

client.emails.toJson

The email.received JSON that forwarding would post for an email: an EmailReceivedEvent. No API call is made. Pass endpoint to fill in data.endpoint.name; without it the slug is read from the address and the name is null. Set includeExtracts: false to leave out codes and links, as forwarding does when the endpoint turned them off.

toJson(
  email: EmailRequest,
  options?: {
    endpoint?: { slug: string; name?: string | null };
    includeExtracts?: boolean;
    fields?: Record<string, string | null> | null; // default: email.emailFields
  }
): EmailReceivedEvent
GET(local)

client.emails.toInbound

The email in the shape an inbound mail service posts it, to test the handler you wrote for that service: postmark, sendgrid (a multipart form), mailgun (a form, signed when you pass your Mailgun signing key) or cloudmailin. No API call is made. Post body with contentType to your handler. See In a mail provider's shape.

toInbound(
  email: EmailRequest,
  format: "postmark" | "sendgrid" | "mailgun" | "cloudmailin",
  options?: { mailgunSigningKey?: string }
): Promise<{ contentType: string; body: string }>
POST/requests/:id/render

client.emails.render

The same, rendered by webhooks.cc (what whk tunnel and the Python and Go SDKs use), or the email.received JSON with format: "json". The body is text, so SendGrid and Mailgun forms leave binary attachments out; with bodyEncoding: "base64" it is the exact bytes in base64, every file included. Decode it with Buffer.from(rendered.body, "base64") before posting.

render(
  requestId: string,
  options: {
    format: "json" | "postmark" | "sendgrid" | "mailgun" | "cloudmailin";
    mailgunSigningKey?: string;
    bodyEncoding?: "base64";
  }
): Promise<{
  format: string;
  method: "POST";
  headers: Record<string, string>;
  body: string;
  bodyEncoding?: "base64";
}>

extractCode, extractLink and extractFromEmail run the same finder as the dashboard's "Found in this email" strip and the codes and links of forwarded JSON. extractCode and extractLink take an EmailRequest, any Request (they return null for HTTP requests), or the parsed email; extractFromEmail takes the parsed email. None of them makes an API call.

import { extractCode, extractLink, extractFromEmail } from "@webhooks-cc/sdk";
 
extractCode(email); // "482913", or null
extractLink(email); // the confirm, verify, reset or sign-in link, else the first link worth keeping
extractLink(email, { actionOnly: true }); // only an action link, or null
extractFromEmail(email.email); // { codes: string[], links: { url, label, action }[] }

A code is only taken when a word like "code", "verification" or "sign in" sits next to it, so order numbers, prices and years stay out. See Matchers & Helpers for the rules.

The email entry point

@webhooks-cc/sdk/email exports the email types, the code and link finder (extractCode, extractLink, extractFromEmail, htmlToText), buildEmailJson, emailAddress and isValidEmailTag. It has no network code and imports no other SDK module, so it is small enough for a browser bundle.

import { emailAddress, extractCode, type EmailReceivedEvent } from "@webhooks-cc/sdk/email";
 
emailAddress("my-app", "run-42"); // "my-app+run-42@mailhooks.cc"