Skip to content

Latest commit

 

History

251 Commits

Folders and files

Repository files navigation

Emailable Node Library

Version Build Status Downloads

This is the official node wrapper for the Emailable API.

Documentation

See the Node API docs.

Installation

Install the package with:

npm install emailable --save
# or
pnpm add emailable
# or
yarn add emailable

Usage

Authentication

The Emailable API requires either an API key or an access token for authentication. API keys can be created and managed in the Emailable Dashboard.

An API key can be set globally for the Emailable client:

// Global: CommonJS import
const emailable = require('emailable')('YOUR_API_KEY');

// Global: ES6 import
import Emailable from 'emailable';
const emailable = Emailable('YOUR_API_KEY');

Or, you can specify an apiKey or an accessToken with each request:

// set api_key at request time
emailable.verify({ apiKey: 'YOUR_API_KEY' })

// set access_token at request time
emailable.verify({ accessToken: 'YOUR_API_KEY' })

Verification

// verify an email address
emailable.verify('jarrett@emailable.com')
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  });

Additional options

You can also pass any of the additional options as a second parameter to verify.

emailable.verify('jarrett@emailable.com', { timeout: 10 })
  .then((response) => {
    console.log(response);
  })
  .catch((error) => {
    console.log(error);
  });

Slow Email Server Handling

Some email servers are slow to respond. As a result the timeout may be reached before we are able to complete the verification process. If this happens, the verification will continue in the background on our servers. We recommend sleeping for at least one second and trying your request again. Re-requesting the same verification with the same options will not impact your credit allocation within a 5 minute window.

{
  message: 'Your request is taking longer than normal. Please send your request again.'
}

Batch Verification

Start a batch

const emails = ['jarrett@emailable.com', 'support@emailable.com', ...];

emailable.batches.verify(emails)
  .then((response) => {
    console.log(response.id);
  });
Additional options

You can also pass any of the additional options as a second parameter to verify.

emailable.batches.verify(emails, { url: 'https://emailable.com/' })
  .then((response) => {
    console.log(response.id);
  });

Get the status / results of a batch

Calling batches.status with the batch id will return the batch's status. This will also return the results once the batch is complete.

const id = '5cfcbfdeede34200693c4319';

emailable.batches.status(id)
  .then((response) => {
    console.log(response);
  });

Development

Run all tests:

$ pnpm install
$ pnpm test

Run a single test suite without a coverage report:

$ pnpm test test/verify.spec.js

Cutting a Release

Run pnpm version x.y.z (or patch, minor, major) on an up to date master with a clean tree, then git push --follow-tags. It runs the tests and linter, bumps package.json, commits, and tags x.y.z. Pushing the tag triggers the release workflow, which publishes to npm and creates the GitHub release.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/emailable/emailable-node.