Elastic Email JavaScript API Library

Introduction

When you integrate Elastic Email with your application, you can interact with your Elastic Email account directly by our API. You can easily integrate your email flow, manage your contacts and templates, send emails, and track email statistics directly from your app.

This page will help you easily integrate with Elastic Email using the Javascript library. You can find our whole downloadable Javascript repository on GitHub. You can also use our comprehensive API documentation.

Elastic Email API v4 uses REST architecture, which allows you to perform various code actions, including directly through your app.

The maximum email size of your entire message or message + attachment cannot exceed 20MB.

The attachment format is the file’s content as a byte array or a Base64 string.

The maximum number of recipients has no limit for one campaign. It depends on the pricing plan.

The API has a limit of 20 concurrent connections and a hard timeout of 600 seconds per request.

On this page, you will find how to authenticate your application and what the requirements for the integration are. You will be also provided with a quick start guide on how to start using API, followed by code samples. 

Authentication

To provide valid authentication and start using our API, you will need an API key. To generate your API key, enter settings on your Elastic Email account and go to Settings -> Manage API Keys -> Create or you can also click on the link: 

Create API key

At this point, you can set custom permissions and optional access for your API key. 

Security tip: The restriction forces the API Key to work only with an IP or IP range that will be specified in this field.

Once you create your API key, keep it safe as it will be used for every API call you make in order to identify you and confirm your account’s credentials. You can create either up to 15 or an unlimited amount of API keys based on your pricing plan. 

Your API key should be sent inside the header with the parameter name ‘x-elasticemail-apikey’ and your API key as a value.

Installation and Usage

Installation

npm install @elasticemail/elasticemail-client --save

npm run build

npm install

npm link

npm link /path/to/

npm run build

   npm install elasticemail/elasticemail-js --save

browserify main.js > bundle.js

module: {
  rules: [
    {
      parser: {
        amd: false
      }
    }
  ]
}

var ElasticEmail = require('@elasticemail/elasticemail-client');

var defaultClient = ElasticEmail.ApiClient.instance;
// Configure API key authorization: apikey
var apikey = defaultClient.authentications['apikey'];
apikey.apiKey = "YOUR API KEY"
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//apikey.apiKeyPrefix['X-ElasticEmail-ApiKey'] = "Token"

var api = new ElasticEmail.CampaignsApi()
var name = "name_example"; // {String} Name of Campaign to delete
var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully.');
  }
};
api.campaignsByNameDelete(name, callback);

let ElasticEmail = require('@elasticemail/elasticemail-client');
 
let defaultClient = ElasticEmail.ApiClient.instance;
 
let apikey = defaultClient.authentications['apikey'];
apikey.apiKey = "895A382DF3DCC13A97E72EXAMPLEKEY"
 
let api = new ElasticEmail.EmailsApi()
 
let email = ElasticEmail.EmailMessageData.constructFromObject({
  Recipients: [
    new ElasticEmail.EmailRecipient("MeowWow ")
  ],
  Content: {
    Body: [
      ElasticEmail.BodyPart.constructFromObject({
        ContentType: "HTML",
        Content: "My test email content ;)"
      })
    ],
    Subject: "JS EE lib test",
    From: "MyEmail "
  }
});
 
var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully.');
  }
};
api.emailsPost(email, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

apikey.apiKey = "YOUR_API_KEY";

Create an instance of ContactsApi that will be used to add contacts.

const contactsApi = new ElasticEmail.ContactsApi();

Create an array with new contacts.

You can pass an array with up to 1000 contacts.

The Email field is mandatory, the rest is optional.

Find out more by checking our API's documentation.

const contacts = [{
    Email: "johnsmith@domain.com",
    FirstName: "John",
    LastName: "Smith"
}];

Specify an existing list name in options, otherwise, contacts will be added to all contacts.

const options = {
    listnames: ["New list"]
};

Create a callback function that will be called when the response comes back.

In case of error it will display error details, otherwise it will display a success message.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Contacts added.');
    }
};

And finally, call contactsPost method from the API to add contacts:

contactsApi.contactsPost(contacts, options, callback);

Delete contacts

If you want to delete a contact, you will need Access Level: ModifyContacts.

To delete a contact, put the following code into your file.

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

Create an instance of ContactsApi that will be used to delete contacts.

const contactsApi = new ElasticEmail.ContactsApi();

Create an object with an array of contacts to delete.

Find out more by checking our API's documentation.

const contacts = {
    Emails: ["johnsmith@domain.com"]
};

Create a callback function that will be called when the response comes back.

In case of error it will display error details, otherwise it will display a success message.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Contacts deleted.');
    }
};

And finally, call contactsDeletePost method from the API to delete contacts:

contactsApi.contactsDeletePost(contacts, callback);

Upload Contacts

If you want to import contacts to your account using the Javascript library, you will need Access Level: ModifyContacts.

To import contacts, put the following code into your file.

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

In this example we will load a CSV file that contains a list of contacts.

We will use built-in fs api for handling files in NodeJS.

const fs = require('fs');

Create an instance of ContactsApi that will be used to upload contacts.

const contactsApi = new ElasticEmail.ContactsApi();

Create a stream to read data from a file.

const readStream = fs.createReadStream('./files/contacts.csv');

The simplest CSV file requires only one column Email, eg.:

Email
john@johnsmith.com

Find out more by checking our API's documentation.

Create an options object where we will pass a file data, its encoding and optionaly a list name to which contacts should be added, otherwise contacts will be added to all contacts.

const options = {
    listName: "New list",
    encodingName: 'utf-8',
    file: readStream,
};

Create a callback function that will be called when the response comes back.

In case of error it will display error details, otherwise it will display a success message.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Contacts added.');
    }
};

And finally, call contactsImportPost method from the API to upload contacts:

contactsApi.contactsImportPost(options, callback);

Export Contacts

If you want to export the selected contact to a downloadable file, you will need Access Level: Export.

Put the following code into your file.

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

In this example we will export contacts to a CSV file.

Create an instance of ContactsApi that will be used to export contacts.

const contactsApi = new ElasticEmail.ContactsApi();

Create an options object:

• fileFormat - specify format in which file should be created, options are: "Csv" "Xml" "Json".
• emails - select contacts to export by providing array of emails
• fileName - you can specify file name of your choice

Other options:

• rule - eg. rule=Status%20=%20Engaged – Query used for filtering
• compressionFormat - "None" "Zip"

Find out more by checking our API's documentation.

const options = {
    fileFormat: 'Csv',
    emails: ["johnsmith@domain.com"],
    fileName: 'exported.csv'
};

Create a callback function that will be called when the response comes back.

In case of error it will display error details, otherwise it will display a success message and link to a file.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Contacts exported');
        console.log('Link', data.Link);
    }
};

And finally, call contactsExportPost method from the API to export contacts:

contactsApi.contactsExportPost(options, callback);

Managing Lists

In this section, we will walk you through managing your contact list on your account using the Javascript library.

Add List

To add a list, you will need Access Level: ModifyContacts.

Put the following code into your file. 

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

Create an instance of ListsApi that will be used to create a new list.

const listsApi = new ElasticEmail.ListsApi();

Create an object with details about the new list. Only ListName is required.

You can also define if to allow unsubscription from the list and pass an email array of existing contacts on your account to add them to the list during list creation.

Find out more by checking our API's documentation.

const listData = {
    ListName: "Best contacts",
    AllowUnsubscribe: true,
    Emails: ["johnsmith@domain.com"]
};

Create a callback function that will be called when response comes back.

In case of error it will display error details, otherwise it will displaya success message.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('List added.');
    }
};

And finally, call listsPost method from the API to create a list:

listsApi.listsPost(listData, callback);

Load List

To load a list, you will need Access Level: ViewContacts.

Put the following code into your file. 

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

Create an instance of ListsApi that will be used to load a list.

const listsApi = new ElasticEmail.ListsApi();

The only thing needed is a list name.

Find out more by checking our API's documentation.

const listName = 'Best contacts';

Create a callback function that will be called when the response comes back.

In case of error it will display error details, otherwise it will display a success message and ListName and PublicListID. Other fields returned are: DateAdded and AllowUnsubscribe.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('List loaded', data.ListName);
        console.log('PublicListID', data.PublicListID);
    }
};

And finally, call listsByNameGet method from the API to load list details:

listsApi.listsByNameGet(listName, callback);

Delete List

To remove a contact list from your account, you will need Access Level: ModifyContacts.

Put the following code into your file.

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check the required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

Create an instance of ListsApi that will be used to delete the list.

const listsApi = new ElasticEmail.ListsApi();

The only thing needed is a list name.

Find out more by checking our API's documentation.

const listName = 'Best contacts';

Create a callback function that will be called when response comes back.

In case of error it will display error details, otherwise it will display a success message.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('List deleted');
    }
};

And finally, call listsByNameDelete method from the API to delete a list:

listsApi.listsByNameDelete(listName, callback);

Creating Templates

An email template is a body of email prepared and saved under a given name. In this section, you will get to know how to add and load email templates.

Add Template

To add a template, you will need Access Level: ModifyTemplates.

Put the following code into your file.

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check the required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

Create an instance of TemplatesApi that will be used to create a new template.

const templatesApi = new ElasticEmail.TemplatesApi();

Create an object with details about the new template:

• Name – the name of your template by which it can be identified and used
• Subject – specify the default subject for this template
• Body – specify actual body content eg. in HTML, PlainText or both
• TemplateScope – specify scope, "Personal" template won't be shared, "Global" template can be shared with your sub accounts.

Find out more by checking our API's documentation.

const template = {
    Name: 'My new template',
    Subject: 'Default subject',
    Body: [{
        ContentType: 'HTML',
        Charset: 'utf-8',
        Content: 'My template'
    }],
    TemplateScope: 'Personal',
};

Create a callback function that will be called when the response comes back.

In case of error it will display error details, otherwise it will display a success message and name and template type of newly created template.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Template name', data.Name);
        console.log('Template type', data.TemplateType);
    }
};

And finally, call templates_post method from the API to create a template:

templatesApi.templatesPost(template, callback);

Load Template

To load existing template details, you will need Access Level: ViewTemplates.

Put the following code into your file.

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

Create an instance of TemplatesApi that will be used to load a template.

const templatesApi = new ElasticEmail.TemplatesApi();

To load a template, you need to specify its name:

Find out more by checking our API's documentation.

const templateName = "hello_template";

Create a callback function that will be called when response comes back.

In case of error it will display error details, otherwise it will display a success message and name and template type of a template.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Template name', data.Name);
        console.log('Template type', data.TemplateType);
    }
};

And finally, call templatesByNameGet method from the API to load a template:

templatesApi.templatesByNameGet(templateName, callback);

Delete Template

To delete a template, you will need Access Level: ModifyTemplates.

Put the following code into your file.

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

Create an instance of TemplatesApi that will be used to delete a template.

const templatesApi = new ElasticEmail.TemplatesApi();

To delete a template, you need to specify its name:

Find out more by checking our API's documentation.

const templateName = "hello_template";

Create a callback function that will be called when the response comes back.

In case of error it will display error details, otherwise it will display a success message and name and template type of a template.

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Template deleted.');
    }
};

And finally, call templatesByNameDelete method from the API to delete a template:

templatesApi.templatesByNameDelete(templateName, callback);

Sending Emails

In this section, we will tell you how you can start sending emails using the Javascript library. You will get to know how to send bulk and transactional emails.

Send Transactional Emails

To send transactional emails, you will need Access Level: SendHttp.

Put the following code into your file.

Load library using the following line:

const ElasticEmail = require('@elasticemail/elasticemail-client');

Get client instance:

const client = ElasticEmail.ApiClient.instance;

Generate and use your API key (remember to check a required access level):

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

Create an instance of EmailsApi that will be used to send a transactional email.

const templatesApi = new ElasticEmail.TemplatesApi();

First, you need to specify email details:

email recipients:

this example demonstrates merge fields usage, for each recipient {name} will be changed to the recipient's name

email content:

body parts – in HTML, PlainText or in both from email – it needs to be your validated email address email subject

Find out more by checking our API's documentation.

const emailData = {
    Recipients: {
        To: ["johnsmith@domain.com"]
    },
    Content: {
        Body: [
            {
                ContentType: "HTML",
                Charset: "utf-8",
                Content: "Mail content."
            },
            {
                ContentType: "PlainText",
                Charset: "utf-8",
                Content: "Mail content."
            }
        ],
        From: "myemail@domain.com",
        Subject: "Example transactional email"
    }
};) 

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Email sent.');
    }
};

emailsApi.emailsTransactionalPost(emailData, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const emailsApi = new ElasticEmail.EmailsApi();

const emailData = {
    Recipients: [
        {
            Email: "johnsmith@domain.com",
            Fields: {
                name: "John"
            }
        }
    ],
    Content: {
        Body: [
            {
                ContentType: "HTML",
                Charset: "utf-8",
                Content: "Hi {name}!"
            },
            {
                ContentType: "PlainText",
                Charset: "utf-8",
                Content: "Hi {name}!"
            }
        ],
        From: "myemail@domain.com",
        Subject: "Example email"
    }
};

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Email sent.');
    }
};

emailsApi.emailsPost(emailData, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const campaignsApi = new ElasticEmail.CampaignsApi()

const campaign = {
    Name: 'hello campaign',
    Recipients: {
        ListNames: ["my list name"],
        SegmentNames: null,
    },
    Content: [{
        From: 'myemail@domain.com',
        ReplyTo: 'myemail@domain.com',
        TemplateName: "hello_template",
        Subject: 'Hello'
    }],
    Status: "Draft"
};

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Campaign name', data.Name);
        console.log('Campaign status', data.Status);
    }
};

campaignsApi.campaignsPost(campaign, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const campaignsApi = new ElasticEmail.CampaignsApi()

const campaignName = "example";

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Campaign deleted.');
    }
};

campaignsApi.campaignsByNameDelete(campaignName, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const campaignsApi = new ElasticEmail.CampaignsApi()

const campaignName = "example";

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Campaign name', data.Name);
        console.log('Campaign status', data.Status);
    }
};

campaignsApi.campaignsByNameGet(campaignName, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

configuration = ElasticEmail.Configuration()
configuration.api_key['apikey'] = 'YOUR_API_KEY'

const campaignsApi = new ElasticEmail.CampaignsApi()

const campaign = {
    Name: 'hello campaign updated',
    Recipients: {
        ListNames: ["my list name"],
        SegmentNames: null,
    },
    Content: [{
        From: 'myemail@domain.com',
        ReplyTo: 'myemail@domain.com',
        TemplateName: "hello_template",
        Subject: 'Thanks for Subscribing'
    }],
    Status: "Draft"
};

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log('Campaign name', data.Name);
        console.log('Campaign status', data.Status);
    }
};

campaignsApi.campaignsByNamePut(campaignName, campaign, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const statisticsApi = new ElasticEmail.StatisticsApi();

const fromDate = new Date('2022-01-17').toJSON();
const toDate = new Date('2022-04-17').toJSON();
const options = {
    to: toDate
};

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        console.log(JSON.stringify(data));
    }
};

statisticsApi.statisticsGet(fromDate, options, callback); 

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const statisticsApi = new ElasticEmail.StatisticsApi();

    limit = 20
    offset = 20

{
    limit: 20,
    offset: 0,
};

const pageinationOptions = {
    limit: 0,
    offset: 0,
};

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        data.forEach((channel) => {
            console.log(JSON.stringify(channel));
        });
    }
};

statisticsApi.statisticsChannelsGet(pageinationOptions, callback);

const ElasticEmail = require('@elasticemail/elasticemail-client');

const client = ElasticEmail.ApiClient.instance;

const apikey = client.authentications['apikey'];
apikey.apiKey = "YOUR_API_KEY";

const statisticsApi = new ElasticEmail.StatisticsApi();

{
    limit: 20,
    offset: 0,
};

const pageinationOptions = {
    limit: 0,
    offset: 0,
};

const callback = (error, data, response) => {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully.');
        data.forEach((campaign) => {
            console.log(JSON.stringify(campaign));
        });
    }
};

statisticsApi.statisticsCampaignsGet(pageinationOptions, callback);