@bytewise-solutions/mailverick

Official TypeScript client for the Mailverick email delivery API — focused on simplicity, robustness, and high delivery performance.

Overview

Mailverick is a high-performance email dispatching service designed for modern applications that demand:

• Fast and reliable delivery
• Simple, clean API
• Robust token handling
• Configurable HTTP: proxy, timeout, agents

This library provides a lightweight, type-safe client for sending emails through Mailverick with minimal setup.

Installation

npm install @bytewise-solutions/mailverick

or

yarn add @bytewise-solutions/mailverick

Usage

import { Mailverick, Email } from '@bytewise-solutions/mailverick';

const client = new Mailverick('your-api-key-id', 'your-api-key-secret');

const email: Email = {
  from: { email: '[email protected]', name: 'Your App' },
  to: [{ email: '[email protected]', name: 'Recipient' }],
  replyTo: { email: '[email protected]' },
  subject: 'Welcome to our platform!',
  body: {
    text: 'Thanks for signing up!',
    html: '<strong>Thanks for signing up!</strong>',
  },
};

await client.sendEmail(email);

You can also batch-send multiple emails:

await client.sendEmails([email1, email2, email3]);

Email Format

type Email = {
  from: { email: string; name?: string };
  to: { email: string; name?: string }[];
  replyTo?: { email: string; name?: string };
  subject: string;
  body: {
    text?: string;
    html?: string;
  };
  attachments?: {
    fileName: string;
    contentType: string;
    base64Content: string;
  }[];
  inlineAttachments?: {
    fileName: string;
    contentType: string;
    base64Content: string;
    contentId: string;
  }[];
  customId?: string;
  tracking?: {
    opens?: 'none' | 'last_only' | 'full';
    disabled?: boolean;
  };
};

Tracking

Each email can carry an optional tracking object:

await client.sendEmail({
  ...email,
  tracking: {
    opens: 'last_only', // 'none' | 'last_only' | 'full'
    disabled: false,
  },
});

• opens — open-tracking mode for the recipient. none never tracks opens, last_only tracks only the most recent email, full tracks every email. This is stored against the recipient's contact, so it applies to all of their opens (including past emails). Omit to keep the account/tenant default (last_only).
• disabled — when true, disables tracking for this message only (skips the open pixel and link rewriting). Defaults to false.

Email Validation

Check an address before you send to it. One address in, one verdict out.

const result = await client.validateEmail('[email protected]');

if (result.didYouMean) {
  console.log(`Did you mean ${result.didYouMean}?`);
}

type EmailValidationResult = {
  email: string;
  status: 'deliverable' | 'probably_deliverable' | 'probably_undeliverable' | 'undeliverable';
  reason: ValidationReason; // a known reason, or any other string
  didYouMean?: string;
  disposable: boolean;
  role: boolean;
};

• status — the verdict, ordered by confidence. Branch on this one. deliverable and probably_deliverable are safe to send to (expect a small bounce rate on the latter), probably_undeliverable is worth a confirmation prompt, undeliverable should be rejected. Typed as ValidationStatus, a closed union of these four, so a switch over it can be exhaustive.

• reason — why, more specific than the status. Typed as ValidationReason, which lists the known reasons for autocomplete but accepts any string: Mailverick adds new reasons within the existing statuses, so treat an unrecognized one as its status.

  | Status | Reasons | | --- | --- | | deliverable | accepted | | probably_deliverable | provider_accept_all, probe_unavailable, previously_bounced | | probably_undeliverable | gibberish, domain_typo, recently_bounced, previously_bounced | | undeliverable | invalid_syntax, does_not_exist, blocked |

  previously_bounced lands on either probably_ status depending on the address's delivery history.

• didYouMean — a corrected address when the domain looks misspelled, absent otherwise.

• disposable / role — a throwaway provider, and a shared mailbox such as info@. Both ask whether you want the address, not whether mail will arrive, so neither moves the status.

The service account needs email:validate, separate from email:send — a validate-only key can check addresses without being able to send mail.

Every verdict resolves with 200, including undeliverable: a rejected address is a result, not an exception. A non-2xx response means the request itself failed, and rejects with the underlying AxiosError — 403 for a missing permission, 429 for rate limits and quotas (honour the Retry-After header). A 200 that is not a validation verdict — a proxy sign-in page, a gateway error envelope, or a status outside the four above — rejects with a plain Error instead. Check axios.isAxiosError(err) and that err.response exists before reading it: a timeout or connection failure also rejects with an AxiosError, but one that carries no response.

Reason values and the full error table are in the validation docs.

HTTP Configuration

The third constructor argument configures the underlying axios client. Every field is optional.

| Option | Default | Purpose | | --- | --- | --- | | timeout | 0 (none) | Milliseconds before a request is aborted. | | proxy | none | HTTP(S) proxy to route requests through. | | headers | — | Extra headers, merged with Content-Type: application/json. | | httpAgent / httpsAgent | Node defaults | Custom agents, e.g. for keep-alive or a private CA. |

Other axios options are not supported and are ignored.

import * as https from 'https';

const client = new Mailverick('your-api-key-id', 'your-api-key-secret', {
  timeout: 10_000,
  httpsAgent: new https.Agent({ keepAlive: true }),
  headers: { 'X-Request-Source': 'billing' },
});

Proxy

const client = new Mailverick('your-api-key-id', 'your-api-key-secret', {
  proxy: {
    host: '127.0.0.1',
    port: 8080,
    protocol: 'http',
    auth: {
      username: 'proxyuser',
      password: 'proxypass',
    },
  },
});

• Without proxy, requests go direct: axios does not read the HTTP_PROXY/HTTPS_PROXY environment variables.
• The proxy's protocol decides which agent is used. With protocol: 'http', axios uses httpAgent, not httpsAgent, even though the Mailverick API is served over HTTPS.