{"id":19755001,"url":"https://github.com/mailjet/mailjet-apiv3-nodejs","last_synced_at":"2025-05-16T00:09:10.953Z","repository":{"id":36731202,"uuid":"41037785","full_name":"mailjet/mailjet-apiv3-nodejs","owner":"mailjet","description":"[API v3] Official Mailjet API v3 NodeJS wrapper","archived":false,"fork":false,"pushed_at":"2024-09-02T12:41:57.000Z","size":9772,"stargazers_count":236,"open_issues_count":24,"forks_count":69,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-10-29T21:51:57.514Z","etag":null,"topics":["api","email","mailjet","mailjet-api","nodejs","nodejs-wrapper","transactional-emails","wrapper"],"latest_commit_sha":null,"homepage":"https://dev.mailjet.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mailjet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-19T14:01:14.000Z","updated_at":"2024-10-29T08:12:07.000Z","dependencies_parsed_at":"2024-06-18T12:28:49.337Z","dependency_job_id":"cdb1291c-6472-4d31-aebf-f273b8dc5aa6","html_url":"https://github.com/mailjet/mailjet-apiv3-nodejs","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailjet%2Fmailjet-apiv3-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailjet%2Fmailjet-apiv3-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailjet%2Fmailjet-apiv3-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mailjet%2Fmailjet-apiv3-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mailjet","download_url":"https://codeload.github.com/mailjet/mailjet-apiv3-nodejs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254442856,"owners_count":22071878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","email","mailjet","mailjet-api","nodejs","nodejs-wrapper","transactional-emails","wrapper"],"created_at":"2024-11-12T03:07:35.278Z","updated_at":"2025-05-16T00:09:05.942Z","avatar_url":"https://github.com/mailjet.png","language":"TypeScript","readme":"[mailjet]: http://www.mailjet.com\n[doc]: http://dev.mailjet.com/guides/?javascript#\n[eventemitter]: https://nodejs.org/api/events.html\n[api_token]: https://app.mailjet.com/sms\n[api_credential]: https://app.mailjet.com/account/api_keys\n[api_doc_repo]: https://github.com/mailjet/api-documentation\n\n![alt text](https://www.mailjet.com/images/email/transac/logo_header.png \"Mailjet\")\n\n# Mailjet JS\n\n[![Build Status](https://travis-ci.org/mailjet/mailjet-apiv3-nodejs.svg?branch=master)](https://travis-ci.org/mailjet/mailjet-apiv3-nodejs)\n![Current Version](https://img.shields.io/badge/version-6.0.8-green.svg)\n\n## Overview\n\nWelcome to the [Mailjet][mailjet] official JavaScript SDK built with `webpack`, `babel` \u0026 `es5`. \\\nThis can be used in **node** or in the **browser**.\n\nCheck out all the resources and JS code examples in the official [Mailjet Documentation][doc].\n\n\u003e **NOTE:** \\\n\u003e If used in the **browser**, at the moment a **proxy is required** to communicate with the Mailjet API due to **CORS** limitations.\\\n\u003e Also, do not publish your private api key in frontend code.\n\n## Table of contents\n\n- [Documentation](#documentation)\n  - [Compatibility](#compatibility)\n  - [Install](#install)\n  - [Setup Client](#setup-client)\n    - [Authentication](#authentication)\n    - [API Setup](#api-setup)\n    - [SMS Setup](#sms-setup)\n    - [Make your first call](#make-your-first-call)\n  - [Configuration](#configuration)\n    - [Options](#options)\n      - [Request timeout](#request-timeout)\n      - [Request headers](#request-headers)\n      - [Request max body length](#request-max-body-length)\n      - [Response max content length](#response-max-content-length)\n      - [Use proxy](#use-proxy)\n    - [Config](#config)\n      - [API Versioning](#api-versioning)\n      - [Host URL](#host-url)\n      - [Response output](#response-output)\n    - [Disable API call](#disable-api-call)\n  - [TypeScript](#typescript)\n    - [Send Email example](#send-email-example)\n    - [Send Message example](#send-message-example)\n    - [Get Contact example](#get-contact-example)\n    - [Our external Typings](#our-external-typings)\n  - [Browser Demo](#browser-demo)\n  - [App examples](#app-examples)\n  - [Request examples](#request-examples)\n    - [Basic API](#basic-api)\n      - [POST Request](#post-request)\n        - [Simple POST request](#simple-post-request)\n        - [Using actions](#using-actions)\n      - [GET Request](#get-request)\n        - [Retrieve all objects](#retrieve-all-objects)\n        - [Use filtering](#use-filtering)\n        - [Retrieve a single object](#retrieve-a-single-object)\n      - [PUT Request](#put-request)\n      - [DELETE Request](#delete-request)\n    - [SMS API](#sms-api)\n      - [Token authentication](#token-authentication)\n      - [Example request](#example-request)\n- [Development](#development)\n  - [Requirements](#requirements)\n  - [Build](#build)\n  - [Tests](#tests)\n  - [Release Process](#release-process)\n\n# Documentation\n\n## Compatibility\n\nThis library officially supports the following `Node.JS` versions:\n- \\\u003e= `v12.x`\n\n---\n\n## Install\n\nInstall the SDK use the following code:\n\n```sh\nnpm install node-mailjet\n```\n\n---\n\n## Setup Client\n\n### Authentication\n\nThe Mailjet `Email API` uses your `public` and `secret` keys for authentication.\n\n```bash\nexport MJ_APIKEY_PUBLIC='your API key'\nexport MJ_APIKEY_PRIVATE='your API secret'\n\nexport MJ_API_TOKEN='your API token'\n```\n\n\u003e **Note:** \\\n\u003e For the `SMS API` the authorization is based on a **Bearer token**. \\\n\u003e See information about it in the [SMS API](#sms-api) section of the readme.\n\n### Basic setup\n\nNext, require the module and initialize your [Mailjet][mailjet] client:\n\n```javascript\nconst Mailjet = require('node-mailjet');\n```\n\nFor `EMAIL API` and `SEND API`:\n```js\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC || 'your-api-key',\n  apiSecret: process.env.MJ_APIKEY_PRIVATE || 'your-api-secret'\n});\n```\n\nFor `SMS API`:\n```js\nconst mailjet = new Mailjet({\n  apiToken: process.env.MJ_API_TOKEN || 'your-api-token'\n});\n```\n\n### API Setup\n\nFor `EMAIL API` and `SEND API` you can use static method `apiConnect`:\n```js\nconst mailjet = Mailjet.apiConnect(\n    process.env.MJ_APIKEY_PUBLIC,\n    process.env.MJ_APIKEY_PRIVATE,\n    {\n      config: {},\n      options: {}\n    } \n);\n```\n\n### SMS Setup\n\nFor `SMS API` you can use static method `smsConnect`:\n```js\nconst mailjet = Mailjet.smsConnect(\n    process.env.MJ_API_TOKEN,\n    {\n      config: {},\n      options: {}\n    } \n);\n```\n\n### Make your first call\n\nHere's an example on how to send an email:\n```javascript\nconst Mailjet = require('node-mailjet');\nconst mailjet = Mailjet.apiConnect(\n    process.env.MJ_APIKEY_PUBLIC,\n    process.env.MJ_APIKEY_PRIVATE,\n);\n\nconst request = mailjet\n        .post('send', { version: 'v3.1' })\n        .request({\n          Messages: [\n            {\n              From: {\n                Email: \"pilot@mailjet.com\",\n                Name: \"Mailjet Pilot\"\n              },\n              To: [\n                {\n                  Email: \"passenger1@mailjet.com\",\n                  Name: \"passenger 1\"\n                }\n              ],\n              Subject: \"Your email flight plan!\",\n              TextPart: \"Dear passenger 1, welcome to Mailjet! May the delivery force be with you!\",\n              HTMLPart: \"\u003ch3\u003eDear passenger 1, welcome to \u003ca href=\\\"https://www.mailjet.com/\\\"\u003eMailjet\u003c/a\u003e!\u003c/h3\u003e\u003cbr /\u003eMay the delivery force be with you!\"\n            }\n          ]\n        })\n\nrequest\n    .then((result) =\u003e {\n        console.log(result.body)\n    })\n    .catch((err) =\u003e {\n        console.log(err.statusCode)\n    })\n```\n\n---\n\n## Configuration\n\nTo instantiate the library you can use the following constructor:\n```javascript\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE,\n  config: CONFIG,\n  options: OPTIONS\n});\n\nconst request = mailjet\n    .METHOD(RESOURCE, CONFIG)\n    .request(DATA, PARAMS, PERFORM_API_CALL)\n```\n\n- `METHOD`: the method you want to use for this call _(one of: `post`, `put`, `get`, `delete`)_\n- `RESOURCE`: the API endpoint you want to call\n- `OPTIONS`: associative array describing the connection options (see [Options](#options) bellow for full list)\n- `CONFIG`: associative array describing the connection config (see [Config](#config) bellow for full list)\n- `DATA`: is the data to be sent as the request body _(only for `post`, `put`, `delete` methods)_\n- `PARAMS`: are the URL parameters to be sent with the request\n- `PERFORM_API_CALL`: is the Boolean parameter that determine need make local or real request \n\n### Options\n\n`options` have this structure:\n- `headers` - associative array describing additional header fields which you can pass to the request\n- `timeout` -  specifies the number of milliseconds before the request times out\n- `proxy` - defines the hostname, port, and protocol of the proxy server to redirect all requests _(Node only option)_\n- `maxBodyLength` - defines the max size of the http request content in bytes allowed _(Node only option)_\n- `maxContentLength` - defines the max size of the http response content in bytes allowed _(Node only option)_\n\nYou can pass `options` on init `client` and this `options` will use for each `request`:\n```javascript\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE,\n  options: {\n    timeout: 1000,\n    maxBodyLength: 1500,\n    maxContentLength: 100,\n    headers: {\n      'X-API-Key': 'foobar',\n    },\n    proxy: {\n      protocol: 'http',\n      host: 'www.test-proxy.com',\n      port: 3100,\n    }\n  }\n});\n```\n\n\u003e For more detailed information visit [this doc](https://github.com/axios/axios#request-config).\n\n#### Request timeout\n\nYou are able to set a timeout for your request using the `timeout` parameter.\n\nThe `timeout` parameter describe the number of **milliseconds** before the request times out.\\\nIf the request takes longer than `timeout`, the request will be aborted.\n\n```javascript\nconst mailjet = new Mailjet({\n    apiKey: process.env.MJ_APIKEY_PUBLIC,\n    apiSecret: process.env.MJ_APIKEY_PRIVATE,\n    options: {\n        timeout: 100\n    }\n});\n\nconst request = mailjet\n    .post('send', { version: 'v3.1' })\n```\n\n#### Request headers\n\nYou are able to set an additional headers for your request using the `headers` parameter.\n\n```javascript\nconst mailjet = new Mailjet({\n    apiKey: process.env.MJ_APIKEY_PUBLIC,\n    apiSecret: process.env.MJ_APIKEY_PRIVATE,\n    options: {\n      headers: {\n        Accept: 'application/json',\n        'API-Key': 'foobar', \n        'Content-Type': 'application/json'\n      }\n    }\n});\n\nconst request = mailjet\n    .post('send', { version: 'v3.1' })\n```\n\n#### Request max body length\n\nYou are able to set the max allowed size of the **http request content** in bytes for your request using the `maxBodyLength` parameter.\n\n```javascript\nconst mailjet = new Mailjet({\n    apiKey: process.env.MJ_APIKEY_PUBLIC,\n    apiSecret: process.env.MJ_APIKEY_PRIVATE,\n    options: {\n      maxBodyLength: 100\n    }\n});\n\nconst request = mailjet\n    .post('send', { version: 'v3.1' })\n```\n\n\u003e **NOTE:** \\\n\u003e This parameter worked only on the `NodeJS` side\n\n#### Response max content length\n\nYou are able to set the max allowed size of the **http response content** in bytes using the `maxContentLength` parameter.\n\n```javascript\nconst mailjet = new Mailjet({\n    apiKey: process.env.MJ_APIKEY_PUBLIC,\n    apiSecret: process.env.MJ_APIKEY_PRIVATE,\n    options: {\n      maxContentLength: 50\n    }\n});\n\nconst request = mailjet\n    .post('send', { version: 'v3.1' })\n```\n\n\u003e **NOTE:** \\\n\u003e This parameter worked only on the `NodeJS` side\n\n#### Use proxy\n\nThe `proxy` parameter allows you to define the **hostname**, **port**, **auth**, and **protocol** of the proxy server for send the API requests through it:\n\n```javascript\nconst mailjet = new Mailjet({\n    apiKey: process.env.MJ_APIKEY_PUBLIC,\n    apiSecret: process.env.MJ_APIKEY_PRIVATE,\n    options: {\n      proxy: {\n        protocol: 'https',\n        host: '127.0.0.1',\n        port: 8080,\n        auth: {\n          username: 'test',\n          password: 'password'\n        }\n      }\n    }\n});\n\nconst request = mailjet\n    .post('send', { version: 'v3.1' })\n```\n\n\u003e **NOTE:** \\\n\u003e This parameter worked only on the `NodeJS` side\n\n### Config\n\n`config` have this structure:\n- `host` - sets custom host URL\n- `version` - sets required version of API for determinate endpoint _(set of `v3`, `v3.1`, `v4`)_\n- `output` - indicates the type of data that the server will respond with\n\nYou can pass `config` on init `client` and this `config` will use for each `request`:\n```javascript\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE,\n  config: {\n      host: 'api.mailjet.com',\n      version: 'v3',\n      output: 'text',\n  }\n});\n```\n\nAnd for each `request` manually _(this `config` will have **more precedence** than passed in `client`)_:\n```javascript\nconst request = mailjet\n    .post('send', {\n        host: 'api.mailjet.com',\n        version: 'v3.1',\n        output: 'json',\n    })\n```\n\n#### API Versioning\n\nThe Mailjet API is spread among three distinct versions:\n- `v3` - The `Email API`\n- `v3.1` - The `Email Send API v3.1`, which is the latest version of our `Send API`\n- `v4` - The `SMS API`\n\nSince 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.\\\nFor the others you need to specify the version using `version` parameter.\n\nFor example, if using `Send API` `v3.1`:\n\n```javascript\nconst request = mailjet\n    .post('send', { version: 'v3.1' })\n```\n\nFor additional information refer to our [API Reference](https://dev.mailjet.com/reference/overview/versioning/).\n\n#### Host URL\n\nThe default **base host name** for the Mailjet API is `api.mailjet.com`. \\\nYou can modify this **host URL** by setting a value for `host` in your call:\n\n```javascript\nconst request = mailjet\n    .post('send', { version: 'v3.1', host: 'api.us.mailjet.com' })\n```\n\n\u003e If your account has been moved to Mailjet's `US` architecture, the `host` value you need to set is `api.us.mailjet.com`.\n\n#### Response output\n\nThe default **response output** for the Mailjet API is `json`. \\\nYou can modify this **response output data** by setting a value for `output` in your call:\n\n```javascript\nconst request = mailjet\n    .post('send', { version: 'v3.1', output: 'arraybuffer' })\n```\n\nThe `output` parameter allowing you to specify the type of response data: \n- `arraybuffer`\n- `document`\n- `json` _(Default)_\n- `text`\n- `stream`\n- `blob` _(Browser only option)_\n\n### Disable API call\n\nBy default, the API call parameter is always enabled. \\\nHowever, you may want to disable it during testing to prevent unnecessary calls to the Mailjet API.\n\nThis is done by passing the `performAPICall` argument with value `false` to `.request(data, params, performAPICall)` method:\n\n```javascript\nconst request = mailjet\n    .post('send', { version: 'v3.1' })\n    .request({}, {}, false)\n```\n\n---\n\n## TypeScript\n\nCurrent library based on `TypeScript` and provide **full cover** for **Mailjet types**. \\\nAll **types** can be exported from main entrypoint `'node-mailjet'`:\n```typescript\nimport { \n  Contact,\n  SendEmailV3, \n  SendEmailV3_1,\n  Message,\n  Segmentation,\n  Template,\n  SendMessage,\n  Webhook\n} from 'node-mailjet';\n```\n\nAs well library has a **generic** method `Request.request\u003cTResult\u003e(data, params, performAPICall)` that could use with these **types**.\n\n### Send Email example\n\n```typescript\nimport { Client, SendEmailV3_1, LibraryResponse } from 'node-mailjet';\n\nconst mailjet = new Client({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\n(async () =\u003e {\n  const data: SendEmailV3_1.Body = {\n    Messages: [\n      {\n        From: {\n          Email: 'pilot@test.com',\n        },\n        To: [\n          {\n            Email: 'passenger@test.com',\n          },\n        ],\n        TemplateErrorReporting: {\n          Email: 'reporter@test.com',\n          Name: 'Reporter',\n        },\n        Subject: 'Your email flight plan!',\n        HTMLPart: '\u003ch3\u003eDear passenger, welcome to Mailjet!\u003c/h3\u003e\u003cbr /\u003eMay the delivery force be with you!',\n        TextPart: 'Dear passenger, welcome to Mailjet! May the delivery force be with you!',\n      },\n    ],\n  };\n\n  const result: LibraryResponse\u003cSendEmailV3_1.Response\u003e = await mailjet\n          .post('send', { version: 'v3.1' })\n          .request(data);\n\n  const { Status } = result.body.Messages[0];\n})();\n```\n\nAnd `response` will have this shape:\n```typescript\n{\n    response: Response;\n    body: {\n      Messages: Array\u003c{\n        Status: string;\n        Errors: Array\u003cRecord\u003cstring, string\u003e\u003e;\n        CustomID: string;\n        ...\n      }\u003e;\n    }\n}\n```\n### Send Message Example\n```typescript\nimport * as Mailjet from 'node-mailjet'; // another possible importing option\n\nconst mailjet = new Mailjet.Client({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\n(async () =\u003e {\n\n    const body: Mailjet.SendMessage.Body = {\n        From: 'some@email.com',\n        To: 'some2@email.com',\n        Text: 'Test'\n    };\n\n    const result: Mailjet.LibraryResponse\u003cMailjet.SendMessage.Response\u003e = await mailjet\n        .post('contact', { version: 'v3' })\n        .request(body);\n    \n\n    const { Status } = result.body;\n})();\n```\nAnd `response` will have this shape:\n```typescript\n{\n    response: Response;\n    body: {\n      From: string;\n      To: string;\n      Text: string;\n      MessageID: string | number;\n      SMSCount: number;\n      CreationTS: number;\n      SentTS: number;\n      Cost: {\n        Value: number;\n        Currency: string;\n      };\n      Status: {\n        Code: number;\n        Name: string;\n        Description: string;\n      };\n    }\n}\n```\n\n### Get Contact Example\n\n```typescript\nimport { Client, Contact, LibraryResponse } from 'node-mailjet'\n\nconst mailjet = new Client({\n    apiKey: process.env.MJ_APIKEY_PUBLIC,\n    apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\n(async () =\u003e {\n  const queryData: Contact.GetContactQueryParams = {\n    IsExcludedFromCampaigns: false,\n    Campaign: 2234234,\n  };\n\n  const result: LibraryResponse\u003cContact.GetContactResponse\u003e = await mailjet\n    .get('contact', { version: 'v3' })\n    .request({}, queryData);\n\n  const ContactID = result.body.Data[0].ID;\n})();\n```\n\nAnd `response` will have this shape:\n```typescript\n{\n    response: Response;\n    body: {\n      Count: number;\n      Total: number;\n      Data: Array\u003c{\n        ID: number;\n        IsExcludedFromCampaigns: boolean;\n        Name: string;\n        CreatedAt: string;\n        DeliveredCount: number;\n        Email: string;\n        ...\n      }\u003e;\n    }\n}\n```\n\n### Our external Typings\n\nFor earlier versions _(`3.*.*` and low)_ of library you can use `@types/node-mailjet` dependency.\n\nThe `types` are published in `npm` and ready for use. \\\n[Here](https://www.npmjs.com/package/@types/node-mailjet) is the `npm` page.\n\nFeel free to request changes if there is something missing, or you just suggest an improvement.\n\nThe main repository is [here](https://github.com/DefinitelyTyped/DefinitelyTyped). \\\nAnd [here](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node-mailjet/index.d.ts) is the file with our types.\n\n---\n\n## Browser Demo\n\nFor demo to work, you'll need to install and run `http-proxy` locally.\n\nInstall it with:\n```sh\nnpm install -g http-proxy\n```\n\nThen run the following command from the `mailjet-apiv3-nodejs` directory:\n```sh\nhttp-server -p 4001 --proxy=\"https://api.mailjet.com\"\n```\n\nDemo should be up and running at http://0.0.0.0:4001/examples/\n\n---\n\n## App examples\n\nList of basic applications that was built in different environments:\n1. [Browser](https://github.com/mailjet/mailjet-apiv3-nodejs/tree/master/examples/browser) - Basic app that using `RequireJS` and provide page where you can make some requests\n2. [Node](https://github.com/mailjet/mailjet-apiv3-nodejs/tree/master/examples/node) - Basic app that contain simple scripts with some requests\n3. [Sendmail](https://github.com/mailjet/mailjet-apiv3-nodejs/tree/master/examples/sendmail) - `ExpressJS` based app that allows to retrieve list of **contacts** and send email to some person\n4. [ReactJS](https://github.com/mailjet/mailjet-apiv3-nodejs/tree/master/examples/react) - `ReactJS` based app that provides page where you can make some requests\n5. [Firebase](https://github.com/mailjet/mailjet-apiv3-nodejs/tree/master/examples/firebase) - `Firebase` based app that provides `Firebase Functions` for sending _hello world email_ and sending _email_ based on dynamic query string data\n\n\u003e **NOTE:**\n\u003e For `browser` side examples at the moment a **proxy is required** to communicate with the Mailjet API due to **CORS** limitations.\n\n---\n\n## Request examples\n\n### Basic API\n\n#### `POST` Request\n\nUse the `post` method of the Mailjet client:\n\n```javascript\nconst request = mailjet\n  .post($RESOURCE, $CONFIG)\n  .id($ID)\n  .request($DATA, $PARAMS, $PERFORM_API_CALL)\n```\n\n`.request` parameter `$DATA` will contain the body of the `POST` request. \\\nYou need to define `.id` if you want to perform an action on a specific object and need to identify it.\n\n##### Simple `POST` request\n\nCreate a new **contact**:\n\n```javascript\nconst Mailjet = require('node-mailjet')\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\nconst request = mailjet\n        .post('contact')\n        .request({\n          Email: \"passenger@mailjet.com\",\n          IsExcludedFromCampaigns: true,\n          Name: \"New Contact\"\n        })\n\nrequest\n        .then((result) =\u003e {\n          console.log(result.body)\n        })\n        .catch((err) =\u003e {\n          console.log(err.statusCode)\n        })\n```\n\n##### Using `actions`\n\nManage the **subscription status** of a **contact** to multiple **lists**:\n\n```javascript\nconst { Client } = require('node-mailjet') // another importing option using destructuring\nconst mailjet = new Client({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\nconst request = mailjet\n        .post('contact')\n        .id($contactID)\n        .action('managecontactslists')\n        .request({\n          ContactsLists: [\n            {\n              ListID: $listID,\n              Action: \"addnoforce\"\n            }\n          ]\n        })\n\nrequest\n        .then((result) =\u003e {\n          console.log(result.body)\n        })\n        .catch((err) =\u003e {\n          console.log(err.statusCode)\n        })\n```\n\n#### `GET` Request\n\nUse the `get` method of the Mailjet client:\n\n```javascript\nconst request = mailjet\n .get($RESOURCE, $CONFIG)\n .id($ID)\n .request($DATA, $PARAMS, $PERFORM_API_CALL)\n```\n\n`.request` parameter `$PARAMS` will contain any query parameters applied to the request. \\\nYou need to define `.id` if you want to retrieve a specific object.\n\n##### Retrieve all objects\n\nRetrieve all **contacts**:\n\n```javascript\nconst Mailjet = require('node-mailjet')\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\nconst request = mailjet\n        .get('contact')\n        .request()\n\nrequest\n        .then((result) =\u003e {\n          console.log(result.body)\n        })\n        .catch((err) =\u003e {\n          console.log(err.statusCode)\n        })\n```\n\n##### Use filtering\n\nRetrieve all **contacts** that are not in the **campaign exclusion list**:\n\n```javascript\nconst Mailjet = require('node-mailjet')\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\nconst request = mailjet\n        .get('contact')\n        .request({}, { IsExcludedFromCampaigns: false })\n\nrequest\n        .then((result) =\u003e {\n          console.log(result.body)\n        })\n        .catch((err) =\u003e {\n          console.log(err.statusCode)\n        })\n```\n\n##### Retrieve a single object\n\nRetrieve a specific **contact** by `ID`:\n\n```javascript\nconst Mailjet = require('node-mailjet')\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\nconst request = mailjet\n        .get('contact')\n        .id($contactID)\n        .request()\n\nrequest\n        .then((result) =\u003e {\n          console.log(result.body)\n        })\n        .catch((err) =\u003e {\n          console.log(err.statusCode)\n        })\n```\n\n#### `PUT` Request\n\nUse the `put` method of the Mailjet client:\n\n```javascript\nconst request = mailjet\n    .put($RESOURCE, $CONFIG)\n    .id($ID)\n    .request($DATA, $PARAMS, $PERFORM_API_CALL)\n```\n\nYou need to define `.id` to specify the object that you need to edit. \\\n`.request` parameter `$DATA` will contain the body of the `PUT` request.\n\nA `PUT` request in the Mailjet API will work as a `PATCH` request - the update will affect only the specified properties. \\\nThe other properties of an existing resource will neither be modified, nor deleted. \\\nIt also means that all non-mandatory properties can be omitted from your payload.\n\nUpdate the **contact properties** for a **contact**:\n\n```javascript\nconst Mailjet = require('node-mailjet')\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\nconst request = mailjet\n        .put('contactdata')\n        .id($contactID)\n        .request({\n          Data: [\n            {\n              first_name: \"John\",\n              last_name: \"Smith\"\n            }\n          ]\n        })\n\nrequest\n        .then((result) =\u003e {\n          console.log(result.body)\n        })\n        .catch((err) =\u003e {\n          console.log(err.statusCode)\n        })\n```\n\n#### `DELETE` Request\n\nUse the `delete` method of the Mailjet client:\n\n```javascript\nconst request = mailjet\n .delete($RESOURCE, $CONFIG)\n .id($ID)\n .request($DATA, $PARAMS, $PERFORM_API_CALL)\n```\n\nYou need to define `.id` to specify the object you want to delete. \\\n`.request` parameter `$DATA` should be empty.\n\nUpon a successful `DELETE` request the response will not include a response body, but only a `204 No Content` response code.\n\nDelete an email **template**:\n\n```javascript\nconst Mailjet = require('node-mailjet')\nconst mailjet = new Mailjet({\n  apiKey: process.env.MJ_APIKEY_PUBLIC,\n  apiSecret: process.env.MJ_APIKEY_PRIVATE\n});\n\nconst request = mailjet\n        .delete('template')\n        .id($templateID)\n        .request()\n\nrequest\n        .then((result) =\u003e {\n          console.log(result.body)\n        })\n        .catch((err) =\u003e {\n          console.log(err.statusCode)\n        })\n```\n\n### SMS API\n\n#### Token authentication\n\nAuthentication for the `SMS API` endpoints is done using a `Bearer token`.  \nThe `Bearer token` is generated in the [SMS section](https://app.mailjet.com/sms) of your Mailjet account.\n\n```javascript\nconst Mailjet = require('node-mailjet');\nconst mailjet = Mailjet.smsConnect(process.env.MJ_API_TOKEN);\n```\n\n#### Example request\n\nHere's an example `SMS API` request:\n\n```javascript\nconst Mailjet = require('node-mailjet');\nconst mailjet = Mailjet.smsConnect(process.env.MJ_API_TOKEN, {\n  config: {\n    version: 'v4'\n  }\n});\n\nconst request = mailjet\n        .post('sms-send')\n        .request({\n          Text: \"Have a nice SMS flight with Mailjet !\",\n          To: \"+33600000000\",\n          From: \"MJPilot\"\n        })\n\nrequest\n        .then((result) =\u003e {\n          console.log(result.body)\n        })\n        .catch((err) =\u003e {\n          console.log(err.statusCode)\n        })\n```\n\n---\n\n# Development\n\nMailjet loves developers. You can be part of this project! \\\nThis SDK is a great introduction to the open source world, check out the code!\n\nFeel free to ask anything, and contribute:\n- Fork the project.\n- Create a new branch.\n- Implement your feature or bug fix.\n- Add documentation to it.\n- Commit, push, open a pull request and voila.\n\nIf you have suggestions on how to improve the guides, please submit an issue in our [Official API Documentation repo](https://github.com/mailjet/api-documentation).\n\n## Requirements\n\n- Requires `Node.JS` \u003e= 4.x\n\nInit package with:\n\n```sh\nnpm run init\n```\n\nWhere the `init` script contain all essential init steps:\n1. `npm install` - install all dependencies\n2. `npm run ts:patch` - patch `TS` compiler for correct building `TypeScript` declaration files\n3. `npm run pkg:prepare` - `husky` install for `git hooks`\n\n## Build\n\nBuild for release purposes (include minimizing):\n```sh\nnpm run build\n```\n\nBuild for dev purposes (without minimizing):\n```sh\nnpm run build:dev \u0026\u0026 npm run build:prepublish\n```\n\nBuild for watching and hot-reload:\n```sh\nnpm run build:watch\n```\n\n## Tests\n\nExecute all tests:\n```sh\nnpm run test\n```\n\nWatch tests with:\n```sh\nnpm run test:watch\n```\n\nReceive coverage of tests with:\n```sh\nnpm run cover\n```\n\nTo test new functionality locally using ```npm link``` please use npm script ```npm run pkg:link```. \\\nThis is needed for correct exporting `d.ts` files.\n\n## Merging changes\n\nBefore **PR merge** check that commits info will be correctly added to the `CHANGELOG.md` file:\n```sh\nnpm run release:dry\n```\n\nAs well that allow to see that package version was correct increased for `SemVer` convention.\n\nAnd then run:\n```sh\nnpm run release\n```\n\n**IMPORTANT:** if package version was increased incorrect you should manually use this scripts:\n- `npm run release:patch`\n- `npm run release:minor`\n- `npm run release:major`\n\n\u003e CI process isn't working currently, so please manually run ```npm run test```\n\n## Release Process\n\nReleases occur after `feature` branches have been tested and merged into `master`.\n\nFirst, checkout `master` and `pull` the latest commits.\n\n```sh\ngit checkout master\ngit pull\n```\n\nNext, run ```npm run release```.\n\nAfter that, `cd ./dist` and then run ```npm login``` and ```npm publish``` to publish changes on npm.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailjet%2Fmailjet-apiv3-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmailjet%2Fmailjet-apiv3-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmailjet%2Fmailjet-apiv3-nodejs/lists"}