Orevail Node.js / TypeScript SDK

The official, zero-dependency Node.js and TypeScript client library for interacting with the Orevail Developer Mail Network.

Orevail is a developer-first transactional and temporary email network. By designing routes on high-reputation domains and validating them with 2048-bit DKIM keys, Orevail allows you to test inbound mail parsing loops, run transactional flows, and mock sandbox accounts easily without getting flagged by spam-reputation checkers.

Key Features

• Zero Dependencies: Leverages standard Node.js global fetch (available in Node 18+). No massive node module weight or dependency vulnerabilities.
• TypeScript First: Coded entirely in TypeScript with strong type safety, autocomplete, and inline documentation out-of-the-box.
• Serverless Ready: Lightweight construction makes it fully compatible with Serverless and Edge runtimes (Vercel Edge, Cloudflare Workers, Netlify Edge).

Installation

Install the package via npm (or yarn/pnpm):

npm install orevail

Quickstart Guide

1. Create a Sandbox Mailbox Address

Create an instantaneous virtual sandbox address. The API key is returned exactly once in this payload.

import { Orevail } from 'orevail';

async function setupSandbox() {
  // Static helper since you don't have an API key yet
  const account = await Orevail.createUser('[email protected]');
  
  console.log('Allocated Email:', account.email);
  console.log('Sandbox API Key:', account.api_key);
}

setupSandbox();

2. Initialize the Authenticated Client

Initialize the Orevail client using your sandbox key:

import { Orevail } from 'orevail';

const orevail = new Orevail({
  apiKey: 'your_orevail_api_key_here'
});

3. Send Outbound Transactions

Enqueue outbound emails into the delivery queue. Our egress workers sign your packets with 2048-bit DKIM signatures on-the-fly and route them instantly.

async function sendAlert() {
  const result = await orevail.sendEmail({
    sender: '[email protected]',
    recipient: '[email protected]',
    subject: 'Verification Alert',
    bodyText: 'Your verification key is 4458-AB',
    bodyHtml: '<p>Your verification key is <strong>4458-AB</strong></p>'
  });

  console.log(`Outbox job accepted. Job ID: ${result.jobId}`);
}

sendAlert();

4. Query & Parse Incoming Emails

Read incoming emails from your sandbox inbox (e.g. validating verification links, testing inbound webhooks, or checking template formatting).

async function fetchLatest() {
  const inbox = await orevail.getEmails('[email protected]', {
    direction: 'incoming',
    limit: 10
  });

  console.log(`Fetched ${inbox.count} messages:`);
  for (const mail of inbox.emails) {
    console.log('----------------------------------------');
    console.log('From:', mail.sender);
    console.log('Subject:', mail.subject);
    console.log('Text Content:', mail.body_text);
    
    // Check for attachments metadata
    if (mail.attachments && mail.attachments.length > 0) {
      console.log('Attachments:', mail.attachments.map(a => a.filename));
    }
  }
}

fetchLatest();

5. Download Email Attachments

Download raw file binary byte buffers associated with any received email:

import * as fs from 'fs/promises';

async function downloadInvoice(attachmentId: number) {
  const arrayBuffer = await orevail.downloadAttachment(attachmentId);
  const nodeBuffer = Buffer.from(arrayBuffer);
  
  await fs.writeFile('invoice.pdf', nodeBuffer);
  console.log('Attachment saved successfully!');
}

Error Handling

Orevail maps HTTP errors to descriptive JS classes, making testing and debugging intuitive:

import { Orevail, OrevailAuthError, OrevailAPIError } from 'orevail';

async function safeFetch() {
  try {
    const orevail = new Orevail({ apiKey: 'invalid_key' });
    await orevail.getEmails('[email protected]');
  } catch (err) {
    if (err instanceof OrevailAuthError) {
      console.error('Invalid API Key provided:', err.message);
    } else if (err instanceof OrevailAPIError) {
      console.error(`Orevail API returned ${err.statusCode}:`, err.message);
    } else {
      console.error('Network or system error:', err);
    }
  }
}

License

MIT License. Created by the Orevail Core Team.