> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryrelaybase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js

> Official Node.js SDK for the Relaybase API

Official Node.js (TypeScript) SDK for Relaybase.

<Card title="GitHub Repository" icon="github" href="https://github.com/Vusion-Labs/relaybase_node_sdk">
  Source, issues, and releases for the Relaybase Node SDK.
</Card>

## Requirements

* Node.js 18+

## Installation

```bash theme={null}
npm install @relaybase/node
```

## Authentication

Get your API key from the [Relaybase dashboard](/getting-started/create-api-key) and pass it to the constructor:

```ts theme={null}
import Relaybase from '@relaybase/node';

const client = new Relaybase('rb_key_...');
```

By default the client talks to `https://api.tryrelaybase.com/v1`.

## Quick start

```ts theme={null}
import Relaybase, { EmailMode } from '@relaybase/node';

const client = new Relaybase('rb_key_...');

const result = await client.verifySingle('jane@company.com', EmailMode.Fast);
console.log(result.data.is_valid); // true
console.log(result.data.status);   // "valid"
```

## Verifying an email

```ts theme={null}
const result = await client.verifySingle(email, EmailMode.Fast);
```

The second argument is the validation mode. If omitted, the API uses its default mode.

### Validation modes

| Constant           | Value    | Description                                           |
| ------------------ | -------- | ----------------------------------------------------- |
| `EmailMode.Fast`   | `fast`   | Fast syntax/MX-level check                            |
| `EmailMode.Medium` | `medium` | Adds deeper domain/mailbox checks                     |
| `EmailMode.Deep`   | `deep`   | Most thorough check, including full SMTP verification |

```ts theme={null}
import { EmailMode } from '@relaybase/node';

await client.verifySingle('jane@company.com', EmailMode.Deep);
```

See [Validation Results](/concepts/validation-results) for how these map to the API's `mode` field.

### Response fields

`verifySingle()` returns a `Promise<VerifyEmailResponse>`. The useful payload is in `result.data`:

| Field           | Type      | Description                                                            |
| --------------- | --------- | ---------------------------------------------------------------------- |
| `is_valid`      | `boolean` | Overall validity of the email                                          |
| `status`        | `string`  | e.g. `"valid"`, `"invalid"`, `"risky"`, `"unknown"`                    |
| `score`         | `number`  | Deliverability score (0–100)                                           |
| `reason`        | `string`  | Human-readable explanation of the result                               |
| `suggestion`    | `string`  | Suggested correction or note                                           |
| `syntax_valid`  | `boolean` | Whether the address is syntactically valid                             |
| `mx_valid`      | `boolean` | Whether the domain has valid MX records                                |
| `smtp_code`     | `number`  | SMTP response code from mailbox verification                           |
| `catch_all`     | `boolean` | Whether the domain accepts all addresses                               |
| `is_disposable` | `boolean` | Whether the address is from a disposable email provider                |
| `is_free`       | `boolean` | Whether the address is from a free email provider (Gmail, Yahoo, etc.) |
| `is_role_based` | `boolean` | Whether the address is role-based (e.g. `support@`, `admin@`)          |
| `checked_at`    | `string`  | ISO timestamp of when the check was performed                          |
| `result`        | `string`  | The normalized email address                                           |

Example:

```ts theme={null}
const result = await client.verifySingle('jane@company.com', EmailMode.Fast);

if (result.data.is_valid) {
  console.log(`${result.data.result} is deliverable (score: ${result.data.score})`);
} else {
  console.log(`Invalid: ${result.data.reason}`);
}
```

## Error handling

Errors from the API are thrown as `RelaybaseAPIError`, which carries the HTTP status code:

```ts theme={null}
import Relaybase, { RelaybaseAPIError } from '@relaybase/node';

try {
  const result = await client.verifySingle('jane@company.com');
} catch (err) {
  if (err instanceof RelaybaseAPIError) {
    console.log(err.status);  // e.g. 401
    console.log(err.message); // e.g. "invalid api key"
  }
}
```

### Common status codes

| Code  | Meaning                                       |
| ----- | --------------------------------------------- |
| `400` | Malformed request (e.g. invalid email format) |
| `401` | Invalid or missing API key                    |
| `403` | Key valid but not authorized for this action  |
| `429` | Rate limit / quota exceeded                   |
| `500` | Internal server error                         |

## TypeScript

This SDK is written in TypeScript and exports full type definitions:

```ts theme={null}
import Relaybase, { EmailMode, VerifyEmailResponse, RelaybaseAPIError } from '@relaybase/node';
```

## Roadmap

Bulk validation support for validating multiple emails in a single call is in progress and will be added in a future release.