See answers to the most common questions about Reteno API integration.

You can find all technical documentation on the data format for calling API requests here.

How to Check API for Correct Performance and Valid Access Options

For example, you can get information about your account using the Get account info method. Follow these steps:

Generate an API key and copy it to your clipboard.
Go to the https://docs.reteno.com/reference/getaccountinfo-1 page.
Enter the username and password that is the copied API key above the example request.

Click Try it!

You should see your username, organization name, and organization ID in the response:

How to Unsubscribe a Contact Who Has Unsubscribed in the Personal Account on the Site

There are two API resources to manage unsubscribes — Add emails to unsubscribed list and Remove emails from unsubscribed list.

📘
Important
The method unsubscribes not contacts but their email addresses (other channels — SMS, Web Push — remain active). All contacts within the organization who may use these email addresses will stop receiving bulk emails from you.

The request body would look as follows:

{
  "emails": [
    "test1@mail.com",
    "test2@mail.com"
  ]
}

where emails — the email addresses that will be marked as unsubscribed.

The Remove emails from unsubscribed list request body is similar to the previous method: you enter the email addresses that will be deleted from the unsubscribed.

Let's look at working with the Remove emails from unsubscribed list method:

Go to the https://docs.reteno.com/reference/deletefromunsubscribed-1 page.
Click ADD STRING in BODY PARAMS and enter the addresses of unsubscribed contacts in the strings.

Click Try it!

If the addresses in the request have been unsubscribed from your Reteno account, they will be removed from this list.

How to Use Dynamic Content in Messages

There are two ways to implement sending an email with dynamic content:

Using a workflow
Using the Send prepared message method

Using a Workflow

Use the Generate event API method to insert the data dynamically from the request body into the message. The array params may contain a random number of parameters:

{
  "field name": "field value"
}

Use Velocity variables to insert dynamic data into a message.

For example, you call the request in the following format:

{
  "eventTypeKey": "testEvent",
  "keyValue": "example@email.com",
  "params": {
    "discount": "5%",
    "link": "https://example.site.com/items_for_sale"
  }
}

The message must use the variables $!discount and $!link, instead of which the data from the request will be substituted.

To insert the content sent by the Generate event method into the body of the message, prepare a workflow using this message, which the corresponding event will trigger. Details >

Using the Send Prepared Message Method

This method involves sending messages without using a workflow. The {id} in the link https://reteno.com/api/v1/message/{id}/smartsend is the identifier of the message into which the data will be inserted when sent to the recipient.

Minimum request body:

{
  "recipients": [
    {
      "locator": "...",
      "jsonParam": "..."
    }
  ]
}

where:

recipients are the array of the message recipients’ contact data;
locator is a recipient. For example, an email address for emails and a phone number for SMS messages;
jsonParam is data in the JSON format to insert in the message.

This method allows for generating different content for each recipient. The entered data is organized in "email + a set of parameters” pairs. The parameters are entered as a random JSON structure, and all fields are assigned $field_name.

Using this method, you can:

Set the condition for displaying a block of HTML code: #if($!field_name == '0') ... #end .
Loop through array elements: #foreach($item in $!items) ... $!item.name ... $!item.price ... #end.
Perform arithmetic operations with field values in the body of the email.

Note: the double quotes inside the JSON structure with the parameters should be modified by an escape character: "jsonParam" : "{\\"field1\\":\\"value1\\", ... }".

For more information, see the article Using the Send prepared message API method.

How to Use Events for Triggers

Triggered campaigns can be launched using the Generate event API method. This method is suitable for creating custom events.

How to Get a Sent Status for a Message via API

Single messages are sent in the asynchronous mode via the following methods:

After an API request is called, your message is scheduled for sending and is sent within seconds.

The body of the response looks as follows:

{
  "id": "0",
  "results": {
    "id": "0",
    "locator": "test@mail.com",
    "status": "OK",
    "requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"
  }
}

To get the status of the message sent via any channel, call a request of the Get single message status method. Ids — the identifiers requestId separated by a comma.

The request body looks as follows:

{
  "results": {
    "status": "DELIVERED",
    "requestId": "3ff28330-f8ef-4636-92ac-86345c16995e",
    "failed": "false",
    "delivered": "true"
  }
}

How to Integrate Subscription Form via API

Reteno offers built-in functionality for creating widgets without additional API settings.

To integrate a subscription form created using a third-party service, call the request using the Subscribe a contact method. The minimum request body looks like this:

{
  "contact": {
    "channels": [
      {
        "type": "email",
        "value": "test@mail.com"
      }
    ]
  }
}

A contact with an email address will appear in the system.

To set the contact name, add the firstName field in the contact object to the request body:

{
  "contact": {
    "firstName": "...",
    "channels": [
      {
        "type": "email",
        "value": "test@mail.com"
      }
    ]
  }
}

To specify which segments the subscribed contact should be in, add the groups field to the request — an array of string values for segment names. If any segments do not exist in the system, they will be created automatically:

{
  "contact": {
    "firstName": "...",
    "channels": [
      {
        "type": "email",
        "value": "test@mail.com"
      }
    ]
  },
  "groups": [
    "Subscribers"
  ]
}

Two event types are automatically generated in the system after the call:

subscribeFromAPI – in case of creating a new contact;
subscribeUpdateFromAPI – if such a contact already exists.

You can see these events in the Triggers → Event history section.

Any type of event can be associated with a workflow launched when the event is generated. We recommend sending an email to confirm a new contact subscription.

To ensure a new contact has been created, go to Contacts → All contacts section and enter the contact ID in the search field.

You will see that the contact's email is grayed out, meaning it is inactive and requires confirmation from the owner.

It is impossible to send newsletters to such addresses; they can only receive subscription confirmation emails and other trigger messages.

How to Pass Additional Field Values via API

Let's look at updating additional fields using the Add/update contacts method. The standard request body looks as follows:

{
  "contacts": [
    {
      "channels": [
        {
          "type": "email",
          "value": "test@mail.com"
        }
      ],
      "fields": [
        {
          "id": 12345,
          "value": "..."
        }
      ]
    }
  ],
  "customFieldsIDs": [
    12345
  ]
}

where

channels is a list of the contact’s media channels (in the example, one media channel — email address — is passed);
fields is a list of additional fields passed in pairs: field ID + value.

There are two ways to get all the IDs available in your account.

The first is to view the identifiers in the account menu → Settings → Additional fields.

The second is to call the Get the list of catalogs method. This parameterless method will return you a structure like this:

{
  "addressBook": {
    "addressBookId": "7200",
    "name": "Main",
    "fieldGroups": {
      "name": "Personal",
      "fields": [
        {
          "id": "15867",
          "name": "Birthday",
          "description": {
            "type": "date",
            "required": "false",
            "readonly": "false"
          }
        },
        {
          "id": "15868",
          "name": "Gender",
          "description": {
            "type": "combobox",
            "allowedValues": {
              "possibleValues": [
                "M",
                "F"
              ]
            },
            "required": "false",
            "readonly": "false"
          }
        }
      ]
    }
  }
}

The fields list is a collection of all your additional fields. In addition to other information, each object in this list contains a field identifier that must be used when passing its value.

How to Test API Using Postman

Postman is a popular API testing tool. It provides a user-friendly interface for creating, sending, and tracking requests.

To get started with Postman, download and install it on your computer.

Testing the Get Account Info Method

Select Basic Auth in the parameters, Authorization tab, Type line:

Log in:
- enter any value in the Username field,
- enter the value of your API key in the Password field.

Select the GET method and enter the https://reteno.com/api/v1/account/info link.

Click the Send button.

You should see your username and your organization name in the response:

{
  "userEmail": "api-user162065",
  "organisationName": "ExamleName"
}

Testing the Remove Emails from Unsubscribed List Method

Select the POST request method and enter the https://reteno.com/api/v1/emails/unsubscribed/delete link.

Select raw and JSON data transfer format in the Body section.

Specify the request body in the following format:

{
  "emails": [
    "...",
    "..."
  ]
}

Click Send.

If the addresses in the request have been unsubscribed from your Reteno account, they will be removed from this list.

Testing the Generate Event v3 Method

Select the POST request method and enter the https://reteno.com/api/v3/event link.
Select raw and JSON data transfer format in the Body section.
Specify the request body in the following format:

{
  "eventTypeKey": "create_contact",
  "keyValue": "site@com.net",
  "params": {
    "email": "site@ukr.net",
    "phone": "380501234567",
    "externalCustomerId": "AV13760",
    "json": {
      "profileInputs": [
        {
          "profileInputId": 10001,
          "value": "2020-11-23"
        }
      ]
    }
  }
}

Click Send.

A successfully submitted request will appear in the event history in your Reteno account.