@temp-mail-io/sdk

Official Node.js SDK for the temp-mail.io API.

• TypeScript-first, ships with .d.ts
• Zero runtime dependencies — uses the built-in fetch
• Works on Node.js 18+, Deno, Bun, and any other fetch-capable runtime

Install

npm install @temp-mail-io/sdk

Usage

import { TempMailClient } from '@temp-mail-io/sdk'

const client = new TempMailClient('YOUR_API_KEY')

const email = await client.createEmail()
console.log(`Your temporary email: ${email.email}`)

const messages = await client.listEmailMessages(email.email)
for (const message of messages) {
  console.log(`From: ${message.from}`)
  console.log(`Subject: ${message.subject}`)
}

Grab an API key at https://temp-mail.io/profile/api.

API

new TempMailClient(apiKey | options)

new TempMailClient('YOUR_API_KEY')

new TempMailClient({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.temp-mail.io', // override for staging/testing
  timeoutMs: 30_000, // per-request timeout
  fetch: globalThis.fetch, // custom fetch implementation
  userAgent: 'my-app/1.0' // custom User-Agent header
})

Methods

Method	Description
listDomains()	List available domains (public / premium / custom)
createEmail(options?)	Create a temporary email address
deleteEmail(email)	Delete a temporary email
listEmailMessages(email)	List messages received on an address
getMessage(id)	Get a single message by id
deleteMessage(id)	Delete a single message
getMessageSourceCode(id)	Get the raw .eml source for a message
downloadAttachment(id)	Download an attachment as Uint8Array
getRateLimit()	Current rate-limit counters

All methods return a promise and throw on non-2xx responses (see Errors below).

Rate limits

Every successful response carries X-Ratelimit-* headers. The client caches the last-seen values on client.lastRateLimit, so you can check remaining quota without spending another request:

await client.listDomains()
console.log(client.lastRateLimit) // { limit, remaining, used, reset }

Errors

All errors extend TempMailError, which carries statusCode, code, type, detail, and requestId fields (the last one is the API's meta.request_id for support tickets).

import {
  TempMailError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NotFoundError
} from '@temp-mail-io/sdk'

try {
  await client.createEmail({ domain: 'does-not-exist.com' })
} catch (err) {
  if (err instanceof RateLimitError) {
    // back off until err.statusCode 429 resets
  } else if (err instanceof ValidationError) {
    console.error(err.detail, err.requestId)
  } else {
    throw err
  }
}

Class	Triggered by
AuthenticationError	api_key_invalid, api_key_empty, 401, 403
RateLimitError	rate_limited, 429
ValidationError	validation_error, 400, 422
NotFoundError	not_found, 404
TempMailError	Everything else (network failures, timeouts, 5xx)

License

MIT