Skip to content
BranchesTags

Repository files navigation

Elastic Email

Elastic Email JavaScript SDK

The official JavaScript / Node.js client library for the Elastic Email REST API v4.

npm npm downloads Node.js API OpenAPI Generator License: MIT

Latest release Last commit Open issues GitHub stars

Installation • Quick start • Examples • API reference • Models • Contributing

Features

  • Transactional and bulk email. Send single messages, bulk campaigns or CSV merge-file sends.
  • Contacts, lists and segments. Add, update, import, export and bulk-delete contacts.
  • Campaigns and automations. Create, update, pause and trigger automations for a contact.
  • Templates, files and attachments. Manage templates and uploaded files.
  • Domains. Verify sending domains and check SPF, DKIM, tracking and certificate status.
  • Webhooks and inbound routes. Receive delivery events and route incoming mail.
  • Statistics, events and suppressions. Track delivery, bounces, complaints and unsubscribes.
  • Subaccounts and security. Manage subaccounts and API keys.
  • Node.js and browsers. Built on superagent, so it runs in Node.js and in bundlers such as webpack or browserify.

Requirements

Platform Version
Node.js 7 or later (required by superagent 5); current LTS recommended
Browsers Via a bundler (webpack, browserify). See Browser and webpack

You'll also need an Elastic Email API key. You can create one in your API settings. Each endpoint's documentation lists the access level it needs.

Installation

Install the @elasticemail/elasticemail-client package from npm:

npm install @elasticemail/elasticemail-client

Or with yarn or pnpm:

yarn add @elasticemail/elasticemail-client
pnpm add @elasticemail/elasticemail-client

npm installs the runtime dependency (superagent) for you. The package ships prebuilt CommonJS in dist/, so there's nothing to compile.

Quick start

Important

Elastic Email only sends from verified domains. Before your first send, verify your sending domain and use an address on that domain as the sender.

Configure the client

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

const client = ElasticEmail.ApiClient.instance;
client.authentications['apikey'].apiKey = process.env.ELASTICEMAIL_API_KEY;

Tip

Keep your API key out of source code. Load it from an environment variable, a .env file that isn't committed, or a secrets manager.

Send a transactional email

const emails = new ElasticEmail.EmailsApi();

const message = {
  Recipients: {
    To: ['john.doe@example.com'],
  },
  Content: {
    From: 'My App <no-reply@yourdomain.com>',
    Subject: 'Welcome aboard!',
    Body: [
      { ContentType: 'HTML', Content: '<h1>Hello!</h1><p>Thanks for signing up.</p>' },
      { ContentType: 'PlainText', Content: 'Hello! Thanks for signing up.' },
    ],
  },
};

emails.emailsTransactionalPost(message, (error, data, response) => {
  if (error) {
    console.error(`Elastic Email API error ${error.status}:`, response && response.text);
    return;
  }
  console.log(`Sent. TransactionID: ${data.TransactionID}, MessageID: ${data.MessageID}`);
});

The from address must use a domain you've verified in your Elastic Email account.

Note

Request bodies are sent as JSON exactly as you pass them, so use the API's PascalCase field names (Recipients, Content, From…). Response objects use the same names (data.TransactionID).

Use promises and async/await

API methods take a Node-style callback, so they work with util.promisify:

const { promisify } = require('util');

const sendTransactional = promisify(emails.emailsTransactionalPost.bind(emails));

const result = await sendTransactional(message);
console.log(result.TransactionID);

Send from a template with merge fields

const message = {
  Recipients: { To: ['john.doe@example.com'] },
  Content: {
    From: 'My App <no-reply@yourdomain.com>',
    TemplateName: 'welcome-template',
    Merge: { firstname: 'John' },
  },
};

emails.emailsTransactionalPost(message, (error, data) => { /* ... */ });

Timeouts, proxies and HTTP agents

ApiClient exposes the underlying superagent settings:

const client = ElasticEmail.ApiClient.instance;

client.timeout = 30000;                      // ms, default 60000
client.defaultHeaders['X-My-Header'] = 'x';  // sent with every request

// Route requests through a proxy (npm install https-proxy-agent)
const { HttpsProxyAgent } = require('https-proxy-agent');
client.requestAgent = new HttpsProxyAgent('http://myProxyUrl:80/');

Browser and webpack

The library works in the browser through a bundler. With webpack you may see Module not found: Error: Cannot resolve module. Disable the AMD loader to fix it:

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

Important

Never ship your API key to a browser. Call the Elastic Email API from your server and expose only what your front end needs.

More examples

More complete, runnable samples are in the Elastic Email examples repository. It covers transactional email, SMTP, webhooks, inbound email, contacts and serverless platforms across 20+ languages and frameworks.

Snippets in this repository

The examples/ folder has one small script per common task. See examples/README.md for how to run them.

Function
addCampaign readme
addContacts readme
addList readme
addTemplate readme
deleteCampaign readme
deleteContact readme
deleteList readme
deleteTemplate readme
exportContacts readme
loadCampaign readme
loadCampaignsStats readme
loadChannelsStats readme
loadList readme
loadStatistics readme
loadTemplate readme
sendBulkEmails readme
sendTransactionalEmails readme
updateCampaign readme
uploadContacts readme

Authentication

Scheme Header Used for
apikey X-ElasticEmail-ApiKey All standard API calls
ApiKeyAuthCustomBranding X-Auth-Token Custom-branding (white-label) accounts

API limits

  • Up to 20 concurrent connections per account
  • A hard timeout of 600 seconds per request

API reference

All URIs are relative to https://api.elasticemail.com/v4. The SDK covers 114 endpoints across 16 API classes: CampaignsApi, ContactsApi, DomainsApi, EmailsApi, EventsApi, FilesApi, InboundRouteApi, ListsApi, SecurityApi, SegmentsApi, StatisticsApi, SubAccountsApi, SuppressionsApi, TemplatesApi, VerificationsApi and WebhookApi.

Show all endpoints
Class Method HTTP request Description
ElasticEmail.CampaignsApi campaignsAutomationByNameTriggerPost POST /campaigns/automation/{name}/trigger Trigger Automation for Contact
ElasticEmail.CampaignsApi campaignsByNameDelete DELETE /campaigns/{name} Delete Campaign
ElasticEmail.CampaignsApi campaignsByNameGet GET /campaigns/{name} Load Campaign
ElasticEmail.CampaignsApi campaignsByNamePausePut PUT /campaigns/{name}/pause Pause Campaign
ElasticEmail.CampaignsApi campaignsByNamePut PUT /campaigns/{name} Update Campaign
ElasticEmail.CampaignsApi campaignsGet GET /campaigns Load Campaigns
ElasticEmail.CampaignsApi campaignsPost POST /campaigns Add Campaign
ElasticEmail.ContactsApi contactsByEmailDelete DELETE /contacts/{email} Delete Contact
ElasticEmail.ContactsApi contactsByEmailGet GET /contacts/{email} Load Contact
ElasticEmail.ContactsApi contactsByEmailPut PUT /contacts/{email} Update Contact
ElasticEmail.ContactsApi contactsDeletePost POST /contacts/delete Delete Contacts Bulk
ElasticEmail.ContactsApi contactsExportByIdStatusGet GET /contacts/export/{id}/status Check Export Status
ElasticEmail.ContactsApi contactsExportPost POST /contacts/export Export Contacts
ElasticEmail.ContactsApi contactsGet GET /contacts Load Contacts
ElasticEmail.ContactsApi contactsImportPost POST /contacts/import Upload Contacts
ElasticEmail.ContactsApi contactsPost POST /contacts Add Contact
ElasticEmail.DomainsApi domainsByDomainDelete DELETE /domains/{domain} Delete Domain
ElasticEmail.DomainsApi domainsByDomainGet GET /domains/{domain} Load Domain
ElasticEmail.DomainsApi domainsByDomainPut PUT /domains/{domain} Update Domain
ElasticEmail.DomainsApi domainsByDomainRestrictedGet GET /domains/{domain}/restricted Check for domain restriction
ElasticEmail.DomainsApi domainsByDomainVerificationPut PUT /domains/{domain}/verification Verify Domain
ElasticEmail.DomainsApi domainsByEmailDefaultPatch PATCH /domains/{email}/default Set Default
ElasticEmail.DomainsApi domainsGet GET /domains Load Domains
ElasticEmail.DomainsApi domainsPost POST /domains Add Domain
ElasticEmail.EmailsApi emailsByMsgidViewGet GET /emails/{msgid}/view View Email
ElasticEmail.EmailsApi emailsByTransactionidStatusGet GET /emails/{transactionid}/status Get Status
ElasticEmail.EmailsApi emailsMergefilePost POST /emails/mergefile Send Bulk Emails CSV
ElasticEmail.EmailsApi emailsPost POST /emails Send Bulk Emails
ElasticEmail.EmailsApi emailsTransactionalPost POST /emails/transactional Send Transactional Email
ElasticEmail.EventsApi eventsByTransactionidGet GET /events/{transactionid} Load Email Events
ElasticEmail.EventsApi eventsChannelsByNameExportPost POST /events/channels/{name}/export Export Channel Events
ElasticEmail.EventsApi eventsChannelsByNameGet GET /events/channels/{name} Load Channel Events
ElasticEmail.EventsApi eventsChannelsExportByIdStatusGet GET /events/channels/export/{id}/status Check Channel Export Status
ElasticEmail.EventsApi eventsExportByIdStatusGet GET /events/export/{id}/status Check Export Status
ElasticEmail.EventsApi eventsExportPost POST /events/export Export Events
ElasticEmail.EventsApi eventsGet GET /events Load Events
ElasticEmail.FilesApi filesByNameDelete DELETE /files/{name} Delete File
ElasticEmail.FilesApi filesByNameGet GET /files/{name} Download File
ElasticEmail.FilesApi filesByNameInfoGet GET /files/{name}/info Load File Details
ElasticEmail.FilesApi filesGet GET /files List Files
ElasticEmail.FilesApi filesPost POST /files Upload File
ElasticEmail.InboundRouteApi inboundrouteByIdDelete DELETE /inboundroute/{id} Delete Route
ElasticEmail.InboundRouteApi inboundrouteByIdGet GET /inboundroute/{id} Get Route
ElasticEmail.InboundRouteApi inboundrouteByIdPut PUT /inboundroute/{id} Update Route
ElasticEmail.InboundRouteApi inboundrouteGet GET /inboundroute Get Routes
ElasticEmail.InboundRouteApi inboundrouteOrderPut PUT /inboundroute/order Update Sorting
ElasticEmail.InboundRouteApi inboundroutePost POST /inboundroute Create Route
ElasticEmail.ListsApi listsByListnameContactsGet GET /lists/{listname}/contacts Load Contacts in List
ElasticEmail.ListsApi listsByNameContactsPost POST /lists/{name}/contacts Add Contacts to List
ElasticEmail.ListsApi listsByNameContactsRemovePost POST /lists/{name}/contacts/remove Remove Contacts from List
ElasticEmail.ListsApi listsByNameDelete DELETE /lists/{name} Delete List
ElasticEmail.ListsApi listsByNameGet GET /lists/{name} Load List
ElasticEmail.ListsApi listsByNamePut PUT /lists/{name} Update List
ElasticEmail.ListsApi listsGet GET /lists Load Lists
ElasticEmail.ListsApi listsPost POST /lists Add List
ElasticEmail.SecurityApi securityApikeysByNameDelete DELETE /security/apikeys/{name} Delete ApiKey
ElasticEmail.SecurityApi securityApikeysByNameGet GET /security/apikeys/{name} Load ApiKey
ElasticEmail.SecurityApi securityApikeysByNamePut PUT /security/apikeys/{name} Update ApiKey
ElasticEmail.SecurityApi securityApikeysGet GET /security/apikeys List ApiKeys
ElasticEmail.SecurityApi securityApikeysPost POST /security/apikeys Add ApiKey
ElasticEmail.SecurityApi securitySmtpByNameDelete DELETE /security/smtp/{name} Delete SMTP Credential
ElasticEmail.SecurityApi securitySmtpByNameGet GET /security/smtp/{name} Load SMTP Credential
ElasticEmail.SecurityApi securitySmtpByNamePut PUT /security/smtp/{name} Update SMTP Credential
ElasticEmail.SecurityApi securitySmtpGet GET /security/smtp List SMTP Credentials
ElasticEmail.SecurityApi securitySmtpPost POST /security/smtp Add SMTP Credential
ElasticEmail.SegmentsApi segmentsByNameDelete DELETE /segments/{name} Delete Segment
ElasticEmail.SegmentsApi segmentsByNameGet GET /segments/{name} Load Segment
ElasticEmail.SegmentsApi segmentsByNamePut PUT /segments/{name} Update Segment
ElasticEmail.SegmentsApi segmentsGet GET /segments Load Segments
ElasticEmail.SegmentsApi segmentsPost POST /segments Add Segment
ElasticEmail.StatisticsApi statisticsCampaignsByNameGet GET /statistics/campaigns/{name} Load Campaign Stats
ElasticEmail.StatisticsApi statisticsCampaignsGet GET /statistics/campaigns Load Campaigns Stats
ElasticEmail.StatisticsApi statisticsChannelsByNameGet GET /statistics/channels/{name} Load Channel Stats
ElasticEmail.StatisticsApi statisticsChannelsGet GET /statistics/channels Load Channels Stats
ElasticEmail.StatisticsApi statisticsGet GET /statistics Load Statistics
ElasticEmail.SubAccountsApi subaccountsByEmailApikeyGet GET /subaccounts/{email}/apikey Get SubAccount ApiKey
ElasticEmail.SubAccountsApi subaccountsByEmailCreditsPatch PATCH /subaccounts/{email}/credits Add, Subtract Email Credits
ElasticEmail.SubAccountsApi subaccountsByEmailDelete DELETE /subaccounts/{email} Delete SubAccount
ElasticEmail.SubAccountsApi subaccountsByEmailGet GET /subaccounts/{email} Load SubAccount
ElasticEmail.SubAccountsApi subaccountsByEmailSettingsEmailPut PUT /subaccounts/{email}/settings/email Update SubAccount Email Settings
ElasticEmail.SubAccountsApi subaccountsGet GET /subaccounts Load SubAccounts
ElasticEmail.SubAccountsApi subaccountsPost POST /subaccounts Add SubAccount
ElasticEmail.SuppressionsApi suppressionsBouncesGet GET /suppressions/bounces Get Bounce List
ElasticEmail.SuppressionsApi suppressionsBouncesImportPost POST /suppressions/bounces/import Add Bounces Async
ElasticEmail.SuppressionsApi suppressionsBouncesPost POST /suppressions/bounces Add Bounces
ElasticEmail.SuppressionsApi suppressionsByEmailDelete DELETE /suppressions/{email} Delete Suppression
ElasticEmail.SuppressionsApi suppressionsByEmailGet GET /suppressions/{email} Get Suppression
ElasticEmail.SuppressionsApi suppressionsComplaintsGet GET /suppressions/complaints Get Complaints List
ElasticEmail.SuppressionsApi suppressionsComplaintsImportPost POST /suppressions/complaints/import Add Complaints Async
ElasticEmail.SuppressionsApi suppressionsComplaintsPost POST /suppressions/complaints Add Complaints
ElasticEmail.SuppressionsApi suppressionsGet GET /suppressions Get Suppressions
ElasticEmail.SuppressionsApi suppressionsUnsubscribesGet GET /suppressions/unsubscribes Get Unsubscribes List
ElasticEmail.SuppressionsApi suppressionsUnsubscribesImportPost POST /suppressions/unsubscribes/import Add Unsubscribes Async
ElasticEmail.SuppressionsApi suppressionsUnsubscribesPost POST /suppressions/unsubscribes Add Unsubscribes
ElasticEmail.TemplatesApi templatesByNameDelete DELETE /templates/{name} Delete Template
ElasticEmail.TemplatesApi templatesByNameGet GET /templates/{name} Load Template
ElasticEmail.TemplatesApi templatesByNamePut PUT /templates/{name} Update Template
ElasticEmail.TemplatesApi templatesGet GET /templates Load Templates
ElasticEmail.TemplatesApi templatesPost POST /templates Add Template
ElasticEmail.VerificationsApi verificationsByEmailDelete DELETE /verifications/{email} Delete Email Verification Result
ElasticEmail.VerificationsApi verificationsByEmailGet GET /verifications/{email} Get Email Verification Result
ElasticEmail.VerificationsApi verificationsByEmailPost POST /verifications/{email} Verify Email
ElasticEmail.VerificationsApi verificationsFilesByIdDelete DELETE /verifications/files/{id} Delete File Verification Result
ElasticEmail.VerificationsApi verificationsFilesByIdResultDownloadGet GET /verifications/files/{id}/result/download Download File Verification Result
ElasticEmail.VerificationsApi verificationsFilesByIdResultGet GET /verifications/files/{id}/result Get Detailed File Verification Result
ElasticEmail.VerificationsApi verificationsFilesByIdVerificationPost POST /verifications/files/{id}/verification Start verification
ElasticEmail.VerificationsApi verificationsFilesPost POST /verifications/files Upload File with Emails
ElasticEmail.VerificationsApi verificationsFilesResultGet GET /verifications/files/result Get Files Verification Results
ElasticEmail.VerificationsApi verificationsGet GET /verifications Get Emails Verification Results
ElasticEmail.WebhookApi webhookByPublicidDelete DELETE /webhook/{publicid} Delete Webhook
ElasticEmail.WebhookApi webhookByPublicidGet GET /webhook/{publicid} Load Webhook
ElasticEmail.WebhookApi webhookByPublicidPut PUT /webhook/{publicid} Update Webhook
ElasticEmail.WebhookApi webhookGet GET /webhook Load Webhooks
ElasticEmail.WebhookApi webhookPost POST /webhook Add Webhook

Models

Show all 98 models

Tests

The generated test suite uses Mocha and lives in test/:

npm install
npm test

Versioning

The SDK follows the Elastic Email API v4. Package versions are listed on npm and release notes in GitHub Releases.

Build details
  • API version: 4.0.0
  • SDK version: 4.2.1
  • Generator version: 7.11.0
  • Build package: org.openapitools.codegen.languages.JavascriptClientCodegen

Contributing

Contributions are welcome! Most of this SDK is generated from the Elastic Email OpenAPI specification, so please read CONTRIBUTING.md before opening a pull request.

This project follows the Contributor Covenant Code of Conduct.

Support

Important

The fastest way to get help is the chat widget on elasticemail.com. Our support team can help with your account, sending, deliverability and API questions.

License

Released under the MIT License. Copyright © 2021–2026 Elastic Email.

About

Official JavaScript / Node.js SDK for the Elastic Email REST API v4. Send transactional and marketing emails, and manage contacts, lists, templates, campaigns, domains and webhooks. Available on npm.

elasticemail.com/email-api

Topics

elasticemailemailemail-apiemail-marketingjavascriptnodejsrest-apisdksmtptransactional-email

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

8 stars

Watchers

2 watching

Forks

1 fork
Report repository

Releases

Used by

Contributors

Languages