How to Add a Promo Code to Messages

You can add a promo code to your messages in one of the following ways:

  • Static promo code. Regular bulk and triggered campaigns with a single promo code.
  • Personalized promo code. Unique promo codes for each contact in bulk campaigns. A promo code is added to contact card and next is added to the campaign.
  • Personalized promo code. Version 2.0. Unique promo codes for each contact in bulk campaigns. Upload a promo code database, and the system will take promo codes from there and insert them into emails.
  • Promo code added via API. You can send emails via API and deliver to each recipient a unique promo code or launch bulk campaigns with a single promo code.
  • Promo code sent from a workflow. For triggered messages, upload a big list of promo codes and send them from a workflow.
  • Promo code sent via preprocessor. For bulk campaigns.
  • Promo code generated in a workflow. For advanced users.The system generates promo code at the moment of campaign launch. The promo code generated by our platform can be decoded and verified on your side.


It is the easiest way of sending message with promo code to one contact or to a group. In this case the personalization is not foreseen. You just create promo code, insert it in message and send by any way.

In out letters editor in gallery od blocks there are prepared several blocks with frames for promo codes. You can use any of them or make you own layout.

promo code blocks

Personalized Promo Code

Technically – the most simple method for substitution of personalized promo codes in messages. Promo code is written in devices of contact and from there in is substituted to the message.

Convenient for mass mailing, when it is necessary to send unique promo code to each recipient.

Mailing preparation contains next stages:

  1. Creating additional field in the system.
  2. Creating file with promo codes.
  3. Uploading file on site.
  4. Creating and sending the letter.

1. Creating additional field in the system

It is necessary to create additional field for promo codes in contact database.

For this enter SettingsAdditional fields.

Additional fields

Click Add list button and fill up opened window with data


2. Creating the file containing with promo codes

Next it is necessary to create file with contacts and respective promo codes. Inherently – it is usual excel or csv file, which has columns with email-addresses or phone numbers and respective promo codes.

3. Uploading file to site

Through contact import upload the file with contacts and promo codes. When configuring fields conformity, choose created Promo code fields for column with promo codes.

The system will update contacts and add promo codes to respective contacts.

updating contacts

As a result of import, the group of contacts will be created. The mailing needs to be done for this group.

4. Creating and sending the message

In message edit mode insert variable %PERSONAL.PROMOCODE|% in the place, where promo code needs to be located.

promo code variable

For this you can place tracking symbol in necessary place of the message, click Other, then Promo code. The system will substitute necessary variable by itself.

After completing settings, execute usual messages mailing for group of contacts. So each recipient will receive message with the promo code, assigned for him.

Personalized Promo Code. Version 2.0.

Upload the promo code database, specify the variable in the email, and the system will automatically insert the right promo code.

This type is suitable for both single and bulk campaigns.

1. Create a file with promo codes. 

Create an excel file with promo codes. To see the file example, go to your personal profile > Settings > Promo codes > File example.

Example of file with promo codes

It should include the following parameters:

  • code - promo code;
  • expirationDate - promo code expiration date in one of the formats: yyyy-MM-dd, yyyy-MM-dd'T'HH:mm:ss, yyyy-MM-dd'T'HH:mm, yyyy.MM.dd;
  • discount - discount;
  • type - promo code type (letters and numbers).


If you need to use only promo codes without other parameters, upload a file only with a code column.

2. Upload a file.

Go to your personal profile > Settings > Promo codes and click Upload file

If you upload only promo codes, tick the corresponding checkbox. A file entitled General will be uploaded in the system. All promo codes uploaded in this way will be displayed in this file.

Checkbox for promo codes

3. Create an email.

  • For promo codes only.

Insert the varibale %PC_GENERAL% where you want your promo code in the email. At the moment of the campaign launch, the system will automatically replace it with the first valid promo code in the list.

Promo code in the email 

  • For promo codes with additional parameters.

Insert the varibale %PC_TYPE_EXPARATIONDATE_DISCOUNT%, where you want your promo code in the email. It may look as follows: %PC_NewYear_1_7% where NewYear is a promo code type, 1 is the number of days after which the code expires, and 7 is the disount.

Promo code with parameters

Promo Code Added via API

One can send promo codes in trigger letter using this method.

There are 2 general methods of sending letters using API:

Using the scenario

Straight on (without using the scenario)

/v1/event method

Using this method you can create and transfer to the system some your event. The event will start up the scenario, which will executed actions programmed in it, for examples, send letter or SMS.

The process looks in the following way:

  1. Transferring data to the system using /v1/event method (at that the event is created).
  2. Creating message for sending.
  3. Creating the scenario.

1. Transferring events to the system using /v1/event method

You need to configure sending /v1/event requests through API to our CDP. It is necessary to transfer at least email and phone number (for SMS) and promo code in parameters of each event. Example.

In the event you can write down the parameter, in which the promo code will be contained. In such way parameters of transferred to you event can look like:

event options

Next elements are responsible for promo code:

  • name - promocode
  • value - ABC-123 (the promo code itself)

2. Creating message for sending

It is necessary to insert in the message the name of the variable, which contains promo code.

If you named the variable promocode, $!data.get(‘promocode’) will be inserted in the letter.

message with promo code variable

3. Creating the scenario

The scenario in this case will look in the following way:

workflow example

In the parameters choose message that you want to send. Also it is necessary to indicate parameter from the event, in which email-address is contained. There is no need to configure something else. In this example block Email is used. If you want to send SMS – use block SMS and in settings indicate parameter that contain phone number.


Using this method one can send message with promo code straight on, without creating the scenario. Method allows sending promo code to one or many contacts, indicated in the request, but it doesn’t allow sending for group of contacts.

One can transfer individual promo code for each contact.

You need to configure requests transferring by /v1/message/{id}/smartsend API method. Format of the body request for this method is:

    "recipients": [{
        "locator": "",
        "jsonParam": "{\"promocode\":\"ABC-123\"}"
    "email": true

Here recipients – array with recipients. In each of its elements there is jsonParam parameter. It can be used for transferring any data (for example, promo code) in the message. In this parameter the data for message needs to be in JSON format, but transformed to the string.

For sending message by this method you need to preliminarily create it. It needs to contain variable, which will substitute promo code. For current example it is $!data.get('promocode').

In the request instead of {id} put message id, which you want to send.

message id


Using this method one can send message with promo code straight on, without creating the scenario. Method allows sending promo code for group of contacts, one or many contacts. It is convenient for mailing for group, when in one mailing you need to send one promo code. Sending unique promo code for each recipient by this method is impossible.

Description of the method is here.

    "params": [{
        "key": "promocode",
        "value": "ABC-123"
    "email": true,
    "groupId": 1111

params – array with parameters for substitution in the letter, It has one element that contains promo code.

key – name of the parameter (for example, promo code)
value – value of the parameter (for example, ABC-123)

In this example sending for a group is described. If you want to send for one or several contacts, instead of groupid transfer recipients array with recipients: "recipients": [ "", "" ].

For sending message using this method you need to preliminarily create it. The variable, which will substitute promo code, needs to be in it.
The format of substitution the variables is following: %TEMPLATE.имя_ключа_для_замены%. For current example it will be %TEMPLATE.promocode%.

Example of substitution the promo code variable.

promo code example

In the request instead of {id} insert message id, which you want to send.

request with message id

Promo Code Sent from a Workflow

There is a possibility to preliminarily upload the list of promo codes in the system for trigger messages, sent from scenario. In the moment of sending the message the scenario will obtain next promo code from the list. The system guarantees that one promo code will be used only once.
The system of promo codes is uploaded in the system using special API methods.

API methods for uploading promo codes:

  • /v1/promocodes – Uploading from CSV file
  • /v1/promocodes – Uploading from JSON

The process of configuring looks like following:

  1. Generate promo codes and transfer them to us using API.
  2. Create the message.
  3. Configure the scenario.

1. Generating promo codes and transferring them using API

You need to generate enough quantity of promo codes. It is better to do it with big reserve, for them not to run out suddenly.

Upload promo codes in our system by API using method, convenient for you. Uploading CSV-file or from JSON is possible.

Next characteristics of promo codes are transferred from CSV-file or JSON:

code – value of promo code
expirationDate – expiration date of the promo code. Date format is next: 2017-12-31T23:59
discount – discount. Indicate value from 0 up to 99.
type – promo code type. Indicate any value. For example, birthday, blackfriday, christmas etc.
inUse – flag if promo code is already used or not.

discount and type are created for segmentation promo codes in database. Technically it is not important, what discount is indicated. Real discount for the customer will be as you grant it on your site.

It is impossible to delete uploaded, but not used promo code. That is why if some promo codes are not urgent, update them by indicated true value for inUse flag.During using, the system will change statuses of using promo codes from false to true.

2. Creating the message

It is necessary to substitute variable $!data.get(‘promocode’) in the message on the place of promo code.

variable to substitute

3. Configuring the scenario

It is necessary to substitute at least 2 blocks in the scenario: Task – Obtain promo code and Email (or SMS).

Task – Obtain promo code block

The scenario can look like following:

workflow with task block

Given task has 3 parameters. All are necessary.

days – quantity of days, during which promo code needs to be active
type – type of promo code, indicated by you
discount – amount of discount

Let’s examine the principle of work on the example. In parameters we will indicate next data:

days - 10
type - birthday
discount - 20

It means that the task will pull out promo code with 20% discount, which will have type birthday and which will act not less than 10 days from the moment of block operation in the scenario. The system will pull out the promo code that corresponds to indicated conditions, transfer it to the message and mark it as the used one.

Email block

In Email block choose preliminarily created letter and indicate parameters from the event, which contains email-address.

Of course, one can execute sending SMS in a similar way using SMS block.

Promo Code Sent via Preprocessor

Preprocessor is designed for sending mass mailings, but with unique content for each subscriber. At first you need to generate file with data in certain format and upload it in our system. During mailing, the system will take data from this file and substitute in messages. Usually it is used for sending mailing with personal goods recommendations, but one can use it to transfer any data, for example, promo code, instead of set of goods.

Learn more about preprocessor here.

Mailing sending process using preprocessor looks like following:

  1. Create file for preprocessor with promo codes.
  2. Upload this file to the system.
  3. Create the letter.
  4. Execute mailing.

1. Creating file for preprocessor with promo codes

It is necessary to create file of certain format for sending messages using preprocessor. File in JSON format needs to contain keys (email-addresses or phone numbers) and array with data for each key.

Example of file contents:

    "": [{
        "promocode": "001100"
    "": [{
        "promocode": "001101"
    "": [{
        "promocode": "001102"

More information about file format is here.

2. Uploading file in the system

Files of preprocessor are uploaded in account settings in section Preprocessor. In details here.

3. Creating the message

It is necessary to substitute variable on the place of promo code. For given example the variable will be following: $!data.get('recommendations').get(0).get('promocode').

example of variable

Also it is necessary to attach to this message the preliminarily uploaded file of preprocessor.

select file

3. Mailing creating and starting up

Sending promo codes by this method is realized as usual mailing.

Promo Code Generated in a Workflow

One can generate promo codes directly in the scenario in the moment of sending the message. Promo code will be generated using our algorithm. In the promo code itself the expiration date, type and discount will be codified.

On your site using reverse algorithm you can decode promo code, entered by user, and grant him respective discount or bonuses in accordance with conditions of your sale. Promo code encoding/decoding algorithm is described in this document.

Configuring process looks like following:

  1. Create the key for encoding the promo code.
  2. Create the letter.
  3. Configure the scenario.
  4. Decode the promo code.

1. Creating encoding key

Promo codes are encoded using key, which third persons don’t need to know. Generate the key in eSSuperKeyXXXXXXXXXXXXXX, where XXXXXXXXXXXXXX - 14 any numbers. Tell us the key. We will attach it to your account.

2. Creating message for sending

It is necessary to substitute $!data.get(‘promocode’) variable in the message.

variable in message

3.Configuring the scenario

The scenario in this case will look like following:

configuring the workflow

The blocks Task – Create promo code and Email (or SMS) are used in the scenario.

Task – Create promo code block

This task has 4 parameters:

days – quantity of days until promo code expiration date is indicated. When this block triggers, the system will add indicated quantity of days to the current date and obtained expiration date will be codified in promo code.
type – type of promo code. One can indicate numbers from 0 to 9. The value will be codified in the promo code.
discount – amount of discount from 0 to 99. Value will be codified in the promo code.
key – codifying key. Leave the value by default.

Sending message block (Email or SMS)

In Email or SMS block choose preliminarily created letter and indicate variable that contains email or phone number.

4. Decoding promo code

Recipient will obtain promo code in following format CRRH-ASDF-HGVB-MNCA.

You will be able to decode this promo code on your site using algorithm and key. Successfully decoding the promo code you will, firstly, validate it; secondly, obtain following data: expiration date, discount, type of promo code. Algorithm is described in the document (only in Rus.).

Any Questions?
We’re always happy to help!
Request a Callback
Fill in the form, and our specialists will call you back as soon as possible.
Request a Callback
Chat Support
We’re waiting for your questions!
Send a Chat Message
Contact the eSputnik support team
Send an Email