mailjet apiv3 nodejs

[API v3] Official Mailjet API v3 NodeJS wrapper

236

TypeScript

alt text

Mailjet JS

Overview

Welcome to the Mailjet official JavaScript SDK built with webpack, babel & es5.
This can be used in node or in the browser.

Check out all the resources and JS code examples in the official Mailjet Documentation.

NOTE:
If used in the browser, at the moment a proxy is required to communicate with the Mailjet API due to CORS limitations.
Also, do not publish your private api key in frontend code.

Documentation
Development

Documentation

Compatibility

This library officially supports the following Node.JS versions:

>= v12.x

Install

Install the SDK use the following code:

npm install node-mailjet

Setup Client

Authentication

The Mailjet Email API uses your public and secret keys for authentication.

export MJ_APIKEY_PUBLIC='your API key'
export MJ_APIKEY_PRIVATE='your API secret'

export MJ_API_TOKEN='your API token'

Note:
For the SMS API the authorization is based on a Bearer token.
See information about it in the SMS API section of the readme.

Basic setup

Next, require the module and initialize your Mailjet client:

const Mailjet = require('node-mailjet');

For EMAIL API and SEND API:

const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC || 'your-api-key',
  apiSecret: process.env.MJ_APIKEY_PRIVATE || 'your-api-secret'
});

For SMS API:

const mailjet = new Mailjet({
  apiToken: process.env.MJ_API_TOKEN || 'your-api-token'
});

API Setup

For EMAIL API and SEND API you can use static method apiConnect:

const mailjet = Mailjet.apiConnect(
    process.env.MJ_APIKEY_PUBLIC,
    process.env.MJ_APIKEY_PRIVATE,
    {
      config: {},
      options: {}
    } 
);

SMS Setup

For SMS API you can use static method smsConnect:

const mailjet = Mailjet.smsConnect(
    process.env.MJ_API_TOKEN,
    {
      config: {},
      options: {}
    } 
);

Make your first call

Here’s an example on how to send an email:

const Mailjet = require('node-mailjet');
const mailjet = Mailjet.apiConnect(
    process.env.MJ_APIKEY_PUBLIC,
    process.env.MJ_APIKEY_PRIVATE,
);

const request = mailjet
        .post('send', { version: 'v3.1' })
        .request({
          Messages: [
            {
              From: {
                Email: "[email protected]",
                Name: "Mailjet Pilot"
              },
              To: [
                {
                  Email: "[email protected]",
                  Name: "passenger 1"
                }
              ],
              Subject: "Your email flight plan!",
              TextPart: "Dear passenger 1, welcome to Mailjet! May the delivery force be with you!",
              HTMLPart: "<h3>Dear passenger 1, welcome to <a href=\"https://www.mailjet.com/\">Mailjet</a>!</h3><br />May the delivery force be with you!"
            }
          ]
        })

request
    .then((result) => {
        console.log(result.body)
    })
    .catch((err) => {
        console.log(err.statusCode)
    })

Configuration

To instantiate the library you can use the following constructor:

const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE,
  config: CONFIG,
  options: OPTIONS
});

const request = mailjet
    .METHOD(RESOURCE, CONFIG)
    .request(DATA, PARAMS, PERFORM_API_CALL)

METHOD: the method you want to use for this call (one of: post, put, get, delete)
RESOURCE: the API endpoint you want to call
OPTIONS: associative array describing the connection options (see Options bellow for full list)
CONFIG: associative array describing the connection config (see Config bellow for full list)
DATA: is the data to be sent as the request body (only for post, put, delete methods)
PARAMS: are the URL parameters to be sent with the request
PERFORM_API_CALL: is the Boolean parameter that determine need make local or real request

Options

options have this structure:

headers - associative array describing additional header fields which you can pass to the request
timeout - specifies the number of milliseconds before the request times out
proxy - defines the hostname, port, and protocol of the proxy server to redirect all requests (Node only option)
maxBodyLength - defines the max size of the http request content in bytes allowed (Node only option)
maxContentLength - defines the max size of the http response content in bytes allowed (Node only option)

You can pass options on init client and this options will use for each request:

const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE,
  options: {
    timeout: 1000,
    maxBodyLength: 1500,
    maxContentLength: 100,
    headers: {
      'X-API-Key': 'foobar',
    },
    proxy: {
      protocol: 'http',
      host: 'www.test-proxy.com',
      port: 3100,
    }
  }
});

For more detailed information visit this doc.

Request timeout

You are able to set a timeout for your request using the timeout parameter.

The timeout parameter describe the number of milliseconds before the request times out.
If the request takes longer than timeout, the request will be aborted.

const mailjet = new Mailjet({
    apiKey: process.env.MJ_APIKEY_PUBLIC,
    apiSecret: process.env.MJ_APIKEY_PRIVATE,
    options: {
        timeout: 100
    }
});

const request = mailjet
    .post('send', { version: 'v3.1' })

Request headers

You are able to set an additional headers for your request using the headers parameter.

const mailjet = new Mailjet({
    apiKey: process.env.MJ_APIKEY_PUBLIC,
    apiSecret: process.env.MJ_APIKEY_PRIVATE,
    options: {
      headers: {
        Accept: 'application/json',
        'API-Key': 'foobar', 
        'Content-Type': 'application/json'
      }
    }
});

const request = mailjet
    .post('send', { version: 'v3.1' })

Request max body length

You are able to set the max allowed size of the http request content in bytes for your request using the maxBodyLength parameter.

const mailjet = new Mailjet({
    apiKey: process.env.MJ_APIKEY_PUBLIC,
    apiSecret: process.env.MJ_APIKEY_PRIVATE,
    options: {
      maxBodyLength: 100
    }
});

const request = mailjet
    .post('send', { version: 'v3.1' })

NOTE:
This parameter worked only on the NodeJS side

Response max content length

You are able to set the max allowed size of the http response content in bytes using the maxContentLength parameter.

const mailjet = new Mailjet({
    apiKey: process.env.MJ_APIKEY_PUBLIC,
    apiSecret: process.env.MJ_APIKEY_PRIVATE,
    options: {
      maxContentLength: 50
    }
});

const request = mailjet
    .post('send', { version: 'v3.1' })

NOTE:
This parameter worked only on the NodeJS side

Use proxy

The proxy parameter allows you to define the hostname, port, auth, and protocol of the proxy server for send the API requests through it:

const mailjet = new Mailjet({
    apiKey: process.env.MJ_APIKEY_PUBLIC,
    apiSecret: process.env.MJ_APIKEY_PRIVATE,
    options: {
      proxy: {
        protocol: 'https',
        host: '127.0.0.1',
        port: 8080,
        auth: {
          username: 'test',
          password: 'password'
        }
      }
    }
});

const request = mailjet
    .post('send', { version: 'v3.1' })

NOTE:
This parameter worked only on the NodeJS side

Config

config have this structure:

host - sets custom host URL
version - sets required version of API for determinate endpoint (set of v3, v3.1, v4)
output - indicates the type of data that the server will respond with

You can pass config on init client and this config will use for each request:

const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE,
  config: {
      host: 'api.mailjet.com',
      version: 'v3',
      output: 'text',
  }
});

And for each request manually (this config will have more precedence than passed in client):

const request = mailjet
    .post('send', {
        host: 'api.mailjet.com',
        version: 'v3.1',
        output: 'json',
    })

API Versioning

The Mailjet API is spread among three distinct versions:

v3 - The Email API
v3.1 - The Email Send API v3.1, which is the latest version of our Send API
v4 - The SMS API

Since most Email API endpoints are located under v3, it sets as the default one and does not need to be specified when making your request.
For the others you need to specify the version using version parameter.

For example, if using Send API v3.1:

const request = mailjet
    .post('send', { version: 'v3.1' })

For additional information refer to our API Reference.

Host URL

The default base host name for the Mailjet API is api.mailjet.com.
You can modify this host URL by setting a value for host in your call:

const request = mailjet
    .post('send', { version: 'v3.1', host: 'api.us.mailjet.com' })

If your account has been moved to Mailjet’s US architecture, the host value you need to set is api.us.mailjet.com.

Response output

The default response output for the Mailjet API is json.
You can modify this response output data by setting a value for output in your call:

const request = mailjet
    .post('send', { version: 'v3.1', output: 'arraybuffer' })

The output parameter allowing you to specify the type of response data:

arraybuffer
document
json (Default)
text
stream
blob (Browser only option)

Disable API call

By default, the API call parameter is always enabled.
However, you may want to disable it during testing to prevent unnecessary calls to the Mailjet API.

This is done by passing the performAPICall argument with value false to .request(data, params, performAPICall) method:

const request = mailjet
    .post('send', { version: 'v3.1' })
    .request({}, {}, false)

TypeScript

Current library based on TypeScript and provide full cover for Mailjet types.
All types can be exported from main entrypoint 'node-mailjet':

import { 
  Contact,
  SendEmailV3, 
  SendEmailV3_1,
  Message,
  Segmentation,
  Template,
  SendMessage,
  Webhook
} from 'node-mailjet';

As well library has a generic method Request.request<TResult>(data, params, performAPICall) that could use with these types.

Send Email example

import { Client, SendEmailV3_1, LibraryResponse } from 'node-mailjet';

const mailjet = new Client({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

(async () => {
  const data: SendEmailV3_1.Body = {
    Messages: [
      {
        From: {
          Email: '[email protected]',
        },
        To: [
          {
            Email: '[email protected]',
          },
        ],
        TemplateErrorReporting: {
          Email: '[email protected]',
          Name: 'Reporter',
        },
        Subject: 'Your email flight plan!',
        HTMLPart: '<h3>Dear passenger, welcome to Mailjet!</h3><br />May the delivery force be with you!',
        TextPart: 'Dear passenger, welcome to Mailjet! May the delivery force be with you!',
      },
    ],
  };

  const result: LibraryResponse<SendEmailV3_1.Response> = await mailjet
          .post('send', { version: 'v3.1' })
          .request(data);

  const { Status } = result.body.Messages[0];
})();

And response will have this shape:

{
    response: Response;
    body: {
      Messages: Array<{
        Status: string;
        Errors: Array<Record<string, string>>;
        CustomID: string;
        ...
      }>;
    }
}

Send Message Example

import * as Mailjet from 'node-mailjet'; // another possible importing option

const mailjet = new Mailjet.Client({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

(async () => {

    const body: Mailjet.SendMessage.Body = {
        From: '[email protected]',
        To: '[email protected]',
        Text: 'Test'
    };

    const result: Mailjet.LibraryResponse<Mailjet.SendMessage.Response> = await mailjet
        .post('contact', { version: 'v3' })
        .request(body);
    

    const { Status } = result.body;
})();

And response will have this shape:

{
    response: Response;
    body: {
      From: string;
      To: string;
      Text: string;
      MessageID: string | number;
      SMSCount: number;
      CreationTS: number;
      SentTS: number;
      Cost: {
        Value: number;
        Currency: string;
      };
      Status: {
        Code: number;
        Name: string;
        Description: string;
      };
    }
}

Get Contact Example

import { Client, Contact, LibraryResponse } from 'node-mailjet'

const mailjet = new Client({
    apiKey: process.env.MJ_APIKEY_PUBLIC,
    apiSecret: process.env.MJ_APIKEY_PRIVATE
});

(async () => {
  const queryData: Contact.GetContactQueryParams = {
    IsExcludedFromCampaigns: false,
    Campaign: 2234234,
  };

  const result: LibraryResponse<Contact.GetContactResponse> = await mailjet
    .get('contact', { version: 'v3' })
    .request({}, queryData);

  const ContactID = result.body.Data[0].ID;
})();

And response will have this shape:

{
    response: Response;
    body: {
      Count: number;
      Total: number;
      Data: Array<{
        ID: number;
        IsExcludedFromCampaigns: boolean;
        Name: string;
        CreatedAt: string;
        DeliveredCount: number;
        Email: string;
        ...
      }>;
    }
}

Our external Typings

For earlier versions (3.*.* and low) of library you can use @types/node-mailjet dependency.

The types are published in npm and ready for use.
Here is the npm page.

Feel free to request changes if there is something missing, or you just suggest an improvement.

The main repository is here.
And here is the file with our types.

Browser Demo

For demo to work, you’ll need to install and run http-proxy locally.

Install it with:

npm install -g http-proxy

Then run the following command from the mailjet-apiv3-nodejs directory:

http-server -p 4001 --proxy="https://api.mailjet.com"

Demo should be up and running at http://0.0.0.0:4001/examples/

App examples

List of basic applications that was built in different environments:

Browser - Basic app that using RequireJS and provide page where you can make some requests
Node - Basic app that contain simple scripts with some requests
Sendmail - ExpressJS based app that allows to retrieve list of contacts and send email to some person
ReactJS - ReactJS based app that provides page where you can make some requests
Firebase - Firebase based app that provides Firebase Functions for sending hello world email and sending email based on dynamic query string data

NOTE:
For browser side examples at the moment a proxy is required to communicate with the Mailjet API due to CORS limitations.

Request examples

Basic API

`POST` Request

Use the post method of the Mailjet client:

const request = mailjet
  .post($RESOURCE, $CONFIG)
  .id($ID)
  .request($DATA, $PARAMS, $PERFORM_API_CALL)

.request parameter $DATA will contain the body of the POST request.
You need to define .id if you want to perform an action on a specific object and need to identify it.

Simple `POST` request

Create a new contact:

const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

const request = mailjet
        .post('contact')
        .request({
          Email: "[email protected]",
          IsExcludedFromCampaigns: true,
          Name: "New Contact"
        })

request
        .then((result) => {
          console.log(result.body)
        })
        .catch((err) => {
          console.log(err.statusCode)
        })

Using `actions`

Manage the subscription status of a contact to multiple lists:

const { Client } = require('node-mailjet') // another importing option using destructuring
const mailjet = new Client({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

const request = mailjet
        .post('contact')
        .id($contactID)
        .action('managecontactslists')
        .request({
          ContactsLists: [
            {
              ListID: $listID,
              Action: "addnoforce"
            }
          ]
        })

request
        .then((result) => {
          console.log(result.body)
        })
        .catch((err) => {
          console.log(err.statusCode)
        })

`GET` Request

Use the get method of the Mailjet client:

const request = mailjet
 .get($RESOURCE, $CONFIG)
 .id($ID)
 .request($DATA, $PARAMS, $PERFORM_API_CALL)

.request parameter $PARAMS will contain any query parameters applied to the request.
You need to define .id if you want to retrieve a specific object.

Retrieve all objects

Retrieve all contacts:

const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

const request = mailjet
        .get('contact')
        .request()

request
        .then((result) => {
          console.log(result.body)
        })
        .catch((err) => {
          console.log(err.statusCode)
        })

Use filtering

Retrieve all contacts that are not in the campaign exclusion list:

const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

const request = mailjet
        .get('contact')
        .request({}, { IsExcludedFromCampaigns: false })

request
        .then((result) => {
          console.log(result.body)
        })
        .catch((err) => {
          console.log(err.statusCode)
        })

Retrieve a single object

Retrieve a specific contact by ID:

const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

const request = mailjet
        .get('contact')
        .id($contactID)
        .request()

request
        .then((result) => {
          console.log(result.body)
        })
        .catch((err) => {
          console.log(err.statusCode)
        })

`PUT` Request

Use the put method of the Mailjet client:

const request = mailjet
    .put($RESOURCE, $CONFIG)
    .id($ID)
    .request($DATA, $PARAMS, $PERFORM_API_CALL)

You need to define .id to specify the object that you need to edit.
.request parameter $DATA will contain the body of the PUT request.

A PUT request in the Mailjet API will work as a PATCH request - the update will affect only the specified properties.
The other properties of an existing resource will neither be modified, nor deleted.
It also means that all non-mandatory properties can be omitted from your payload.

Update the contact properties for a contact:

const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

const request = mailjet
        .put('contactdata')
        .id($contactID)
        .request({
          Data: [
            {
              first_name: "John",
              last_name: "Smith"
            }
          ]
        })

request
        .then((result) => {
          console.log(result.body)
        })
        .catch((err) => {
          console.log(err.statusCode)
        })

`DELETE` Request

Use the delete method of the Mailjet client:

const request = mailjet
 .delete($RESOURCE, $CONFIG)
 .id($ID)
 .request($DATA, $PARAMS, $PERFORM_API_CALL)

You need to define .id to specify the object you want to delete.
.request parameter $DATA should be empty.

Upon a successful DELETE request the response will not include a response body, but only a 204 No Content response code.

Delete an email template:

const Mailjet = require('node-mailjet')
const mailjet = new Mailjet({
  apiKey: process.env.MJ_APIKEY_PUBLIC,
  apiSecret: process.env.MJ_APIKEY_PRIVATE
});

const request = mailjet
        .delete('template')
        .id($templateID)
        .request()

request
        .then((result) => {
          console.log(result.body)
        })
        .catch((err) => {
          console.log(err.statusCode)
        })

SMS API

Token authentication

Authentication for the SMS API endpoints is done using a Bearer token.
The Bearer token is generated in the SMS section of your Mailjet account.

const Mailjet = require('node-mailjet');
const mailjet = Mailjet.smsConnect(process.env.MJ_API_TOKEN);

Example request

Here’s an example SMS API request:

const Mailjet = require('node-mailjet');
const mailjet = Mailjet.smsConnect(process.env.MJ_API_TOKEN, {
  config: {
    version: 'v4'
  }
});

const request = mailjet
        .post('sms-send')
        .request({
          Text: "Have a nice SMS flight with Mailjet !",
          To: "+33600000000",
          From: "MJPilot"
        })

request
        .then((result) => {
          console.log(result.body)
        })
        .catch((err) => {
          console.log(err.statusCode)
        })

Development

Mailjet loves developers. You can be part of this project!
This SDK is a great introduction to the open source world, check out the code!

Feel free to ask anything, and contribute:

Fork the project.
Create a new branch.
Implement your feature or bug fix.
Add documentation to it.
Commit, push, open a pull request and voila.

If you have suggestions on how to improve the guides, please submit an issue in our Official API Documentation repo.

Requirements

Requires Node.JS >= 4.x

Init package with:

npm run init

Where the init script contain all essential init steps:

npm install - install all dependencies
npm run ts:patch - patch TS compiler for correct building TypeScript declaration files
npm run pkg:prepare - husky install for git hooks

Build

Build for release purposes (include minimizing):

npm run build

Build for dev purposes (without minimizing):

npm run build:dev && npm run build:prepublish

Build for watching and hot-reload:

npm run build:watch

Tests

Execute all tests:

npm run test

Watch tests with:

npm run test:watch

Receive coverage of tests with:

npm run cover

To test new functionality locally using npm link please use npm script npm run pkg:link.
This is needed for correct exporting d.ts files.

Merging changes

Before PR merge check that commits info will be correctly added to the CHANGELOG.md file:

npm run release:dry

As well that allow to see that package version was correct increased for SemVer convention.

And then run:

npm run release

IMPORTANT: if package version was increased incorrect you should manually use this scripts:

npm run release:patch
npm run release:minor
npm run release:major

CI process isn’t working currently, so please manually run npm run test

Release Process

Releases occur after feature branches have been tested and merged into master.

First, checkout master and pull the latest commits.

git checkout master
git pull

Next, run npm run release.

After that, cd ./dist and then run npm login and npm publish to publish changes on npm.

mailjet apiv3 nodejs

Mailjet JS

Overview

Table of contents

Documentation

Compatibility

Install

Setup Client

Authentication

Basic setup

API Setup

SMS Setup

Make your first call

Configuration

Options

Request timeout

Request headers

Request max body length

Response max content length

Use proxy

Config

API Versioning

Host URL

Response output

Disable API call

TypeScript

Send Email example

Send Message Example

Get Contact Example

Our external Typings

Browser Demo

App examples

Request examples

Basic API

POST Request

Simple POST request

Using actions

GET Request

Retrieve all objects

Use filtering

Retrieve a single object

PUT Request

DELETE Request

SMS API

Token authentication

Example request

Development

Requirements

Build

Tests

Merging changes

Release Process

`POST` Request

Simple `POST` request

Using `actions`

`GET` Request

`PUT` Request

`DELETE` Request