Skip to content
VaultSandbox

Client Installation

The @vaultsandbox/client SDK provides a developer-friendly interface for integrating email testing into your Node.js applications and test suites.

Requirements

Section titled “Requirements”
  • Node.js: 20.0.0 or higher
  • Platform: Node.js only (not supported in browsers or edge runtimes)
  • VaultSandbox Gateway: Running instance with API access

Installation

Section titled “Installation”

npm

Section titled “npm”
Terminal window
npm install @vaultsandbox/client

yarn

Section titled “yarn”
Terminal window
yarn add @vaultsandbox/client

pnpm

Section titled “pnpm”
Terminal window
pnpm add @vaultsandbox/client

Quick Start

Section titled “Quick Start”

Basic Usage

Section titled “Basic Usage”
import { VaultSandboxClient } from '@vaultsandbox/client';


const client = new VaultSandboxClient({
  url: 'https://mail.example.com',
  apiKey: 'your-api-key',
});


const inbox = await client.createInbox();
console.log(`Send email to: ${inbox.emailAddress}`);


const email = await inbox.waitForEmail({ timeout: 30000 });
console.log('Received:', email.subject);


await inbox.delete();

Verifying Installation

Section titled “Verifying Installation”

Create a test file test-vaultsandbox.js:

import { VaultSandboxClient } from '@vaultsandbox/client';


async function test() {
  const client = new VaultSandboxClient({
    url: process.env.VAULTSANDBOX_URL,
    apiKey: process.env.VAULTSANDBOX_API_KEY,
  });


  try {
    const serverInfo = await client.getServerInfo();
    console.log('✅ Connected to VaultSandbox');
    console.log('Allowed domains:', serverInfo.allowedDomains);


    const inbox = await client.createInbox();
    console.log('✅ Created inbox:', inbox.emailAddress);


    await inbox.delete();
    console.log('✅ Cleanup successful');


    console.log('\n🎉 Installation verified!');
  } catch (error) {
    console.error('❌ Error:', error.message);
    process.exit(1);
  }
}


test();

Run it:

Terminal window
export VAULTSANDBOX_URL=https://mail.example.com
export VAULTSANDBOX_API_KEY=your-api-key
node test-vaultsandbox.js

TypeScript Support

Section titled “TypeScript Support”

The SDK is written in TypeScript and includes full type definitions.

TypeScript Configuration

Section titled “TypeScript Configuration”

Ensure your tsconfig.json has:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}

TypeScript Example

Section titled “TypeScript Example”
import { VaultSandboxClient, Email, Inbox } from '@vaultsandbox/client';


const client: VaultSandboxClient = new VaultSandboxClient({
  url: 'https://mail.example.com',
  apiKey: process.env.VAULTSANDBOX_API_KEY!,
});


const inbox: Inbox = await client.createInbox();
const email: Email = await inbox.waitForEmail({ timeout: 30000 });


console.log(email.subject); // TypeScript knows this is a string

ESM vs CommonJS

Section titled “ESM vs CommonJS”

The VaultSandbox client is distributed as ESM (ES Modules) only.

Section titled “ESM (Recommended)”
import { VaultSandboxClient } from '@vaultsandbox/client';

package.json:

{
  "type": "module"
}

CommonJS (Requires Workaround)

Section titled “CommonJS (Requires Workaround)”

If you must use CommonJS, use dynamic import:

async function loadClient() {
  const { VaultSandboxClient } = await import('@vaultsandbox/client');
  return VaultSandboxClient;
}


const VaultSandboxClient = await loadClient();
const client = new VaultSandboxClient({ url, apiKey });

Next Steps

Section titled “Next Steps”