@exiby/sdk

Exiby Mail SDK for QA testing. Strongly typed with full TypeScript support.

Installation

npm install @exiby/sdk

Quick Start

import { createClient, createTestInbox } from '@exiby/sdk';

const client = createClient({ apiKey: 'exiby_your_key_here' });

// Create inbox
const inbox = await client.createInbox();
console.log(inbox.address); // [email protected]

// Wait for email
const email = await client.waitForEmail(inbox.id, { timeout: 30 });
console.log(email.subject);

Playwright Integration

import { createTestInbox } from '@exiby/sdk';

test('user registration sends verification email', async ({ page }) => {
  const inbox = await createTestInbox('exiby_your_key_here');

  await page.fill('#email', inbox.email);
  await page.click('#register-button');

  const email = await inbox.wait(30);
  expect(email?.subject).toContain('Verify');

  await inbox.cleanup();
});

Types

Inbox

interface Inbox {
  id: string;
  address: string;
  createdAt: string;
  expiresAt: string;
  emailCount?: number;
}

Email

interface Email {
  id: string;
  from: string;
  subject: string;
  html?: string;
  text?: string;
  size: number;
  createdAt: string;
}

EmailWithHeaders

interface EmailWithHeaders extends Email {
  headers: Record<string, any>;
  attachments: Attachment[];
}

EmailAnalysis

interface EmailAnalysis {
  emailId: string;
  analysis: {
    spf: { pass: boolean; domain: string | null; ip: string | null; error: string | null };
    dkim: { pass: boolean; domain: string | null; selector: string | null; error: string | null };
    dmarc: { pass: boolean; policy: string | null; error: string | null };
    origin: { ip: string | null; hostname: string | null; country: string | null };
    spamScore: number;
    threats: Threat[];
    safe: boolean;
  };
}

StructuredEmailData

interface StructuredEmailData {
  emailId: string;
  structured: {
    otp: string | null;
    verificationCode: string | null;
    links: LinkInfo[];
    buttons: ButtonInfo[];
    tokens: TokenInfo[];
    dates: DateInfo[];
    phoneNumbers: string[];
    amounts: string[];
    unsubscribeLink: string | null;
  };
}

TestInbox

interface TestInbox extends Inbox {
  email: string;
  wait: (timeout?: number) => Promise<Email | null>;
  sendTest: (options?: SendTestEmailOptions) => Promise<void>;
  getEmails: () => Promise<Email[]>;
  cleanup: () => Promise<void>;
}

ExibyApiError

class ExibyApiError extends Error {
  statusCode: number;
  error: string;
  details?: any;
}

API Reference

| Method | Returns | Description | |--------|---------|-------------| | createClient(config) | ExibyClient | Create client instance | | createTestInbox(apiKey, opts?) | TestInbox | Create test inbox with helpers | | client.createInbox(opts?) | Inbox | Create a new inbox | | client.listInboxes(opts?) | Inbox[] | List all inboxes | | client.getInbox(id) | InboxWithEmails | Get inbox with emails | | client.deleteInbox(id) | void | Delete an inbox | | client.waitForEmail(id, opts?) | Email \| null | Wait for email | | client.getEmail(id) | EmailWithHeaders | Get email details | | client.getEmailAnalysis(id) | EmailAnalysis | Get SPF/DKIM/DMARC analysis | | client.getStructuredData(id) | StructuredEmailData | Extract OTP, links, tokens | | client.sendTestEmail(id, opts?) | void | Send test email | | client.me() | User | Get user info |

License

MIT