Mailinator API Client

Common errors

• Error: MAILINATOR_API_KEY environment variable is not set. Please provide your API key.

  cause The Mailinator API Key, essential for authentication, was not found in the environment variables when the application attempted to initialize the client.
  fix Set the `MAILINATOR_API_KEY` environment variable with your valid Mailinator API key. For local development, use a `.env` file or export it in your shell. For production, use secure secret management systems.

• Failed to retrieve messages: Invalid API Key

  cause The provided Mailinator API Key is either incorrect, expired, or does not have sufficient permissions for the requested operation.
  fix Verify that your `MAILINATOR_API_KEY` is correct by logging into your Mailinator account and checking your API key settings. Ensure it has the necessary permissions for the operations you are performing (e.g., fetching inbox messages).

• TypeError: Cannot read properties of undefined (reading 'getInboxMessages') OR TypeError: mailinatorClient.inbox.getInboxMessages is not a function

  cause The assumed structure of the client object or the method name for accessing specific API endpoints (e.g., `inbox.getInboxMessages`) is incorrect, or the method simply doesn't exist.
  fix Consult the official `REFERENCE.md` document or the Mailinator API documentation to confirm the exact client structure and method names. The client might expose methods directly, under a different namespace, or require different parameters.

Warnings

• deprecated Some 'Request classes' within the SDK are explicitly marked as deprecated and are slated for removal in future versions. Developers should consult the `ROADMAP.md` and `REFERENCE.md` files for details and plan for migration.
  Fix: Review the official documentation (REFERENCE.md, ROADMAP.md) for alternatives to deprecated Request classes. Adapt your code to use newer, supported methods.
• gotcha Hardcoding your Mailinator API Key directly into source code is a significant security risk. API keys should be treated as sensitive credentials.
  Fix: Always use environment variables (e.g., `process.env.MAILINATOR_API_KEY`), a secret management system, or secure configuration files to store and retrieve your API key. Never commit API keys to version control.
• gotcha Mailinator, like many external APIs, has rate limits. Exceeding these limits can lead to temporary blocks or throttled requests.
  Fix: Implement proper error handling for rate limit responses (e.g., HTTP 429 Too Many Requests). Consider adding retry logic with exponential backoff and implement request throttling in your application to stay within limits.

Install

• npm install mailinator-client npm
• yarn add mailinator-client yarn
• pnpm add mailinator-client pnpm

Imports

• MailinatorClient
  wrong:

  const MailinatorClient = require('mailinator-client');

  correct:

  import { MailinatorClient } from 'mailinator-client';

  The primary client class for interacting with the Mailinator API. ESM preferred.
• Mailinator API Response Types

  import type { InboxMessage, Inbox } from 'mailinator-client';

  Import specific types for API responses to leverage TypeScript's type checking. Refer to `REFERENCE.md` for available types.
• CommonJS Import
  wrong:

  import MailinatorClient from 'mailinator-client';

  correct:

  const { MailinatorClient } = require('mailinator-client');

  For CommonJS environments, use named `require`. The package does not use default exports.

Quickstart

Initializes the Mailinator client with an API key from environment variables and fetches messages from a specified inbox, logging basic details.

import { MailinatorClient } from 'mailinator-client';
import type { InboxMessage } from 'mailinator-client';

async function fetchInboxMessages() {
  // Ensure your Mailinator API Key is set in your environment variables (e.g., .env file)
  // Get an API key from https://www.mailinator.com/docs/api
  const apiKey = process.env.MAILINATOR_API_KEY ?? '';
  if (!apiKey) {
    console.error('Error: MAILINATOR_API_KEY environment variable is not set. Please provide your API key.');
    process.exit(1);
  }

  const mailinatorClient = new MailinatorClient(apiKey);
  const inboxName = 'my-test-inbox-123'; // Replace with an inbox you can control or create

  try {
    console.log(`Attempting to fetch messages for inbox: ${inboxName}@mailinator.com`);
    // The exact path to 'getInboxMessages' may vary; check Mailinator's API docs/SDK reference.
    const response = await mailinatorClient.inbox.getInboxMessages({ inbox: inboxName });

    if (response.result && response.result.msgs && response.result.msgs.length > 0) {
      console.log(`Successfully found ${response.result.msgs.length} messages.`);
      response.result.msgs.forEach((msg: InboxMessage) => {
        console.log(`  - ID: ${msg.id}, Subject: ${msg.subject || 'No Subject'}, From: ${msg.fromfull || 'Unknown'}`);
      });
    } else {
      console.log(`No messages found in inbox: ${inboxName}@mailinator.com.`);
    }
  } catch (error) {
    console.error('Failed to retrieve messages:', error instanceof Error ? error.message : String(error));
    if (error instanceof Error && error.message.includes('Invalid API Key')) {
      console.error('Please verify your MAILINATOR_API_KEY is correct.');
    }
  }
}

fetchInboxMessages();