Elastic Email Bash 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 Bash library. You can find our whole downloadable Bash repository on GitHub here. If you need API documentation, you can find it here.

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: 

https://elasticemail.com/account#/settings/new/create-api

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

source ElasticEmail.bash-completion

sudo cp ElasticEmail.bash-completion /etc/bash-completion.d/ElasticEmail

brew install bash-completion

if [ -f $(brew --prefix)/etc/bash_completion ]; then
  . $(brew --prefix)/etc/bash_completion
fi

host=https://api.elasticemail.com
 
apiKey=YOUR_API_KEY
 
apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey
 
apiMethod=emailsPost
 
json='{
        Recipients: [
            { 
                Email: "MeowWow ", 
                Fields: {
                    name: "MeowWow"
                }
            }
        ],
        Content: {
            Body: [
                {
                    ContentType: "HTML",
                    Charset: "utf-8",
                    Content: "My test email content ;)"
                },
                {
                    ContentType: "PlainText",
                    Charset: "utf-8",
                    Content: "Hi {name}!"
                }
            ],
            From: "MyEmail ",
            Subject: "Bash EE lib test"
        }
    }'
 
echo $json | ./ElasticEmail --host $host --content-type json $apiMethod - $apiKeyHeader

$ chmod u+x ElasticEmail

#!/bin/bash

host=https://api.elasticemail.com

apiKey=YOUR_API_KEY

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

apiMethod=contactsPost

listname="New list"

json='[{
        Email: "johnsmith@domain.com",
        FirstName: "John",
        LastName: "Smith"
    }]'

echo $json | ./ElasticEmail --host $host --content-type json $apiMethod - $apiKeyHeader listnames="$listname"

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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=contactsDeletePost

Define JSON with emails to delete:

json='{ 
        Emails: ["johnsmith@domain.com2"]
    }'

And finally, you can use the lib to make an api call:

echo $json | ./ElasticEmail --host $host --content-type json $apiMethod - $apiKeyHeader

Upload Contacts

If you want to upload contacts, you will need Access Level: ModifyContacts.

Put the following code into your file.

Load library using the following line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define endpoint path:

apiMethodUrl="$host/v4/contacts/import"

Create options with a file name with its encoding. Optionally a list name to which contacts should be added, otherwise contacts will be added to all contacts.

file="@contacts.csv"
encodingName="utf-8"

And finally, you can use the lib to make an API call:

curl -F file=$file   -H "$apiKeyHeader"   -X POST "$apiMethodUrl?encodingName=$encodingName&listName=$listNameEncoded"

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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=campaignsPost

Specify options:

• 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"

fileName="exported.csv"
fileFormat="Csv"
compressionFormat="Zip"

Define emails to be exported:

emails=("johnsmith@domain.com" "karol.szczycinski@elasticemail.com")

Let's transform it to format required by the lib emails=value1 emails=value2 emails=...:

emailsParams=""
for email in "${emails[@]}"
do
    emailsParams="emails=\"$email\" $emailsParams "
done

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod $apiKeyHeader fileFormat="$fileFormat" fileName="$fileName" compressionFormat="$compressionFormat" $emailsParams

Managing Lists

In this section, we will walk you through managing your contact list on your account using the Bash 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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=listsPost

Create a JSON 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.

json='{
        ListName: "Best contacts",
        AllowUnsubscribe: true,
        Emails: ["johnsmith@domain.com"]
    }'

And finally, you can use the lib to make an api call:

echo $json | ./ElasticEmail --host $host --content-type json $apiMethod - $apiKeyHeader

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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=listsByNameGet

The only thing you need to specify is a list name

listName="test name 3[]??[]Special_characters!@#$%^&*()222"

But in case when your name contains some special URL characters you need to properly encode it first. For example you can use Bash engine and encodeURIComponent from JavaScript language for doing that or use other way of your preference:

listNameEncoded=$(node -p "encodeURIComponent('$listName')") # output: "%5B%5D%3F%3F%5B%5DSpecial_characters%21%40%23%24%25%5E%26%2A%28%29222%0A"

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$listNameEncoded" $apiKeyHeader

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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=listsByNameDelete

The only thing you need to specify is a list name

listName="test name 3[]??[]Special_characters!@#$%^&*()222"

But in case when your name contains some special URL characters you need to properly encode it first. For example you can use Bash engine and encodeURIComponent from JavaScript language for doing that or use other way of your preference:

listNameEncoded=$(node -p "encodeURIComponent('$listName')") # output: "%5B%5D%3F%3F%5B%5DSpecial_characters%21%40%23%24%25%5E%26%2A%28%29222%0A"

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$listNameEncoded" $apiKeyHeader

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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=templatesPost

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.

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

And finally, you can use the lib to make an api call:

echo $json | ./ElasticEmail --host $host --content-type json $apiMethod - $apiKeyHeader

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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=templatesByNameGet

The only thing you need to specify is a template name

templateName="test name 3[]??[]Special_characters!@#$%^&*()222"

But in case when your name contains some special URL characters you need to properly encode it first. For example you can use Bash engine and encodeURIComponent from JavaScript language for doing that or use other way of your preference:

templateNameEncoded=$(node -p "encodeURIComponent('$templateName')") # output: "%5B%5D%3F%3F%5B%5DSpecial_characters%21%40%23%24%25%5E%26%2A%28%29222%0A"

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$templateNameEncoded" $apiKeyHeader

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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=templatesByNameDelete

The only thing you need to specify is a template name

templateName="test name 3[]??[]Special_characters!@#$%^&*()222"

But in case when your name contains some special URL characters you need to properly encode it first. For example you can use Bash engine and encodeURIComponent from JavaScript language for doing that or use other way of your preference:

templateNameEncoded=$(node -p "encodeURIComponent('$templateName')") # output: "%5B%5D%3F%3F%5B%5DSpecial_characters%21%40%23%24%25%5E%26%2A%28%29222%0A"

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$templateNameEncoded" $apiKeyHeader

Sending Emails

In this section, we will tell you how you can start sending emails using the Bash 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:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=emailsTransactionalPost

First, you need to specify email details:

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

json='{
        Recipients: {
            To: ["johnsmith@domain.com"]
        },
        Content: {
            Body: [
                {
                    ContentType: "HTML",
                    Charset: "utf-8",
                    Content: "<strong>Mail content.<strong>"
                },
                {
                    ContentType: "PlainText",
                    Charset: "utf-8",
                    Content: "Mail content."
                }
            ],
            From: "myemail@domain.com",
            Subject: "Example transactional email"
        }
    }'

And finally, you can use the lib to make an API call:

echo $json | ./ElasticEmail --host $host --content-type json $apiMethod - $apiKeyHeader

Send Bulk Emails

Put the following code to your file to send a bulk email, meaning a single email sent to a large group at once.

You will need Access Level: SendHttp.

Load library using the following line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=emailsPost

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

json='{
        Recipients: [
            { 
                Email: "johnsmith@domain.com", 
                Fields: {
                    name: "John"
                }
            }
        ],
        Content: {
            Body: [
                {
                    ContentType: "HTML",
                    Charset: "utf-8",
                    Content: "<strong>Hi {name}!<strong>"
                },
                {
                    ContentType: "PlainText",
                    Charset: "utf-8",
                    Content: "Hi {name}!"
                }
            ],
            From: "myemail@domain.com",
            Subject: "Example transactional email"
        }
    }'

And finally, you can use the lib to make an API call:

echo $json | ./ElasticEmail --host $host --content-type json $apiMethod - $apiKeyHeader

Managing Campaigns

Add Campaign

To add your first campaign using the Bash library, you will need Access Level: ModifyCampaigns. Mind that when using Elastic Email, when you send an email to any group of contacts, we call it a “campaign”.

To add a campaign, put the following code into your file.

Load library using the following line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=contactsExportPost

Create an example campaign object:

• Name: defines campaign name by which you can identify it later
• Recipients: define your audience
• Content: define your message details
• Status: define the status in which the campaign should be created

Send will be triggered immediately or postponed, depending on the given options. Because we define Status as Draft, in this case, it will be postponed and the campaign will be added to drafts.

json='{ 
    Name: "my new campaign2", 
    Status: "Draft", 
    Recipients: { 
        ListNames: ["my list name"]
    },
    Content: [{
            From: "myemail@domain.com",
            ReplyTo: "myemail@domain.com",
            TemplateName: "hello_template",
            Subject: "Hello"
        }]
    }'

And finally, you can use the lib to make an api call:

echo $json | ./ElasticEmail --host $host --content-type json $apiMethod - $apiKeyHeader

Load Campaign

To load details about a campaign list in your account using the Bash library, you will need Access Level: ViewCampaigns. Mind that when using Elastic Email, when you send an email to any group of contacts, we call it a “campaign”.

To load a campaign, put the following code into your file.

Load library using the following line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=campaignsByNameGet

The only thing you need to specify is a campaign name

campaignName="example";

But in the case when your name contains some special URL characters you need to properly encode it first. For example, you can use Bash engine and encodeURIComponent from JavaScript language for doing that or use another way of your preference:

campaignName="[]??[]Special_characters!@#$%^&*()222"
campaignNameEncoded=$(node -p "encodeURIComponent('$campaignName')") # output: "%5B%5D%3F%3F%5B%5DSpecial_characters%21%40%23%24%25%5E%26%2A%28%29222%0A"

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$campaignNameEncoded" $apiKeyHeader

Update Campaign

To update existing campaigns in your account using the Bash library, you will need Access Level: ModifyCampaigns. Mind that when using Elastic Email, when you send an email to any group of contacts, we call it a “campaign”.

To update a campaign, put the following code into your file.

Load library using the following line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=campaignsByNamePut

Define what campaign to update:

campaignName="my new campaign"

Create an example campaign object:

• Name: defines campaign name by which you can identify it later
• Recipients: define your audience
• Content: define your message details
• Status: define the status in which the campaign should be created

Send will be triggered immediately or postponed, depending on the given options. Because we define Status as Draft, in this case, it will be postponed and the campaign will be added to drafts.

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

And finally, you can use the lib to make an API call:

echo $json | ./ElasticEmail --host $host --content-type json $apiMethod name="$campaignNameEncoded" - $apiKeyHeader

Delete Campaign

To delete an existing campaign, you will need Access Level: ModifyCampaigns. Mind that when using Elastic Email, when you send an email to any group of contacts, we call it a “campaign”.

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

Load library using the following line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=campaignsByNameDelete

The only thing you need to specify is a campaign name

campaignName="[]??[]Special_characters!@#$%^&*()222"

But in case when your name contains some special URL characters you need to properly encode it first. For example you can use Bash engine and encodeURIComponent from JavaScript language for doing that or use other way of your preference:

campaignNameEncoded=$(node -p "encodeURIComponent('$campaignName')") # output: "%5B%5D%3F%3F%5B%5DSpecial_characters%21%40%23%24%25%5E%26%2A%28%29222%0A"

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$campaignNameEncoded" $apiKeyHeader

Tracking

In this section, we will walk you through the steps of managing actions related to email tracking. You will get to know how to load delivery and campaign statistics from your account using the Bash library.

Load Statistics

To load delivery statistics from your account, you will need Access Level: ViewReports.

Put the following code into your file.

Load library using the line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=apiMethod=statisticsGet

First you need to specify a date range:

• from date
• to date – optional

fromDate="2022-01-17T00:00:00"
toDate="2023-01-17T00:00:00"

Single date format: YYYY-MM-DDThh:mm:ss

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$listNameEncoded" $apiKeyHeader

Load Channels Statistics

To load statistics for each channel from your account, you will need Access Level: ViewChannels.

Put the following code into your file.

Load library using the following line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=apiMethod=statisticsChannelsGet

Campaigns statistics response is paginated you need to specify pagination options:

• limit – maximum returned items, limit = 0 means to return everything till the end of the list
• offset – how many items should be skipped from begging

Eg. to return the first 20 elements specify pagination options as follows

{
    limit: 20,
    offset: 0,
};

Let's fetch everything:

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

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$listNameEncoded" $apiKeyHeader

Load Campaigns Stats

To load statistics for each email campaign from your account, you will need Access Level: ViewChannels.

Put the following code into your file.

Load library using the following line:

#!/bin/bash

Variable for host value:

host=https://api.elasticemail.com

Use your API key (remember to check a required access level):

apiKey=YOUR_API_KEY

and create header variables for api key:

apiKeyHeaderName=X-ElasticEmail-ApiKey
apiKeyHeader=$apiKeyHeaderName:$apiKey

Define a method that will be used:

apiMethod=apiMethod=statisticsCampaignsGet

Campaigns statistics response is paginated you need to specify pagination options:

• limit – maximum returned items, limit = 0 means to return everything till the end of the list
• offset – how many items should be skipped from begging

Eg. to return the first 20 elements specify pagination options as follows

{
    limit: 20,
    offset: 0,
};

Let's fetch everything:

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

And finally, you can use the lib to make an api call:

./ElasticEmail --host $host $apiMethod name="$listNameEncoded" $apiKeyHeader