API Tutorials

Learn how to use the Digital Engagement APIs by following the steps in our tutorials.

Updating Lists

Keepng your subscriptions lists up to date is essential to reaching the right audience. There are a combination of APIs that allow you to add, edit or delete subscribers. With these methods you can ensure that no one misses out on your campaigns.

Adding subscribers

Subscribers might be added one by one or in bulk by sending their basic information.

When you add or edit subscribers , the response body contains the data of the subscriber or subscribers created:

{
  "meta": {
    "timestamp": 1597166699457,
    "transactionId": "70169d77-c165-4795-9932-35b8a3af96fb",
    "explain": "a descriptive text"
  },
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "key": "12341236545, 507f1f77bcf86cd799439011, homer@example.com",
    "data": {
      "id": "5f7b1af6535f6b5151040776",
      "key": "5f7b1af6535f6b5151040776",
      "data": {
        "address": "12345",
        "member since": "2020-10-05T13:09:10.233573Z",
        "last updated": "2020-10-05T13:09:10.233573Z",
        "mobile": "unknown.5f7b1af6535f6b5151040776",
        "id": "5f7b1af6535f6b5151040776",
        "email": "The Tester"
      }
    }
  }
}

Parameter

Description

address

Subscriber address

member since

Subscriber entry date.

last update

Date of the last subscriber update.

mobile

Subscriber mobile phone

id

Subscriber identifier

email

Subscriber email address

Adding single subscribers

You have the option to add one by one subscriber to the list.

HTTP Request :POST /lists/{listId}/subscribers

Request body

{
  "additionalProp1": {},
  "additionalProp2": {},
  "additionalProp3": {}
}

Required parameter

Description

listId

You must provide the id of the list where you want to add the subscriber.

Adding multiple subscribers

There are two options to add multiple subscribers:

  1. Adding multiple subscribers by JSON

  2. Adding multiple subscribers by CSV

Adding multiple subscribers by JSON

You can add bulk subscribers in JSON format.

HTTP Request :POST /lists/{listId}/subscribers/bulk

Request body

[
  {
    "mobile": "+5841474662698",
    "email": "test@testing.com",
    "first Name": "Homer"
  },
  {
    "mobile": "+123456",
    "email": "lisa@example.com",
    "first Name": "Lisa"
  }
]

Required parameter

Description

listId

You must provide the id of the list where you want to add the subscribers.

Adding multiple subscribers by CSV

You can add bulk subscribers in CSV format.

HTTP Request :POST /lists/{listId}/subscribers

Required parameter

Description

listId

You must provide the id of the list where you want to add the subscribers.

Updating Subscribers

In order to update a subscriber PUT and PATCH method might be used. Note that PUT method is going to REPLACE the current data of the subscriber for the data sent in the request (meaning fields not sent are going to be erased from subscriber) while PATCH method ONLY edits the fields sent in the request:

Updates a subscriber with the state defined by the representation enclosed in the request:

HTTP Request :PUT /lists/{listId}/subscribers/{subscriberId}

Edits only the fields sent in the request for a subscriber, the others remain the same:

HTTP Request :PATCH /lists/{listId}/subscribers/{subscriberId}

In both cases, the following request body is presented, together with the required fields:

Request body

{
"name": "Homer",
"email": "homer@example.com"
}

Required parameter

Description

listId

You must provide the id of the list where you want to edit the subscriber.

subscriberId

The identifier of the subscriber you want to edit

Deleting Subscribers

You can delete a specific subscriber from the desired list.

HTTP Request : DELETE /lists/{listId}/subscribers/{subscriberId}

Required parameter

Description

listId

You must provide the id of the list where you want to delete the subscriber.

subscriberId

The identifier of the subscriber you want to delete.

Managing Segments

A segment can be defined as a subset of the main list given some conditions and it can be created from a CSV file or from a json body in the request.

When you create or edit segments, the response body contains the basic data of the segment created:

{
  "meta": {
    "timestamp": 1597166699457,
    "transactionId": "70169d77-c165-4795-9932-35b8a3af96fb",
    "explain": "a descriptive text"
  },
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "people who likes movies",
    "userName": "homer",
    "listId": 203,
    "queryRule": "movies[eq]=horror&age[gt]=21",
    "total": 7
  }
}

Parameter

Description

id

Segment identifier

name

Segment name

username

Segment creator username

listId

List identifier where the segment is assigned

queryRule

Conditions applied to the main list

total

Total indicating the amount of subscribers in the segment

Creating a segment from a CSV File

Creates a segment from the main list given a CSV file. Note that some fields are required such as the name of the segment, the source column (column to segment from file) and the target column (column to apply segment from main list):

HTTP Request :POST /lists/{listId}/segments

Required parameter

Description

listId

You must provide the id of the list where you want to create the segment.

name

Name of the segment that you want to create.

sourceColumn

Column to segment from CSV file

targetColum

Column to apply segment from main list.

Creating a segment from a JSON body

Creates a segment from the information given in the body of the request:

HTTP Request :POST /lists/{listId}/segments

Request body

{
  "name": "females",
  "queryRule": "gender[eq]=f",
  "segmentType": "DYNAMIC"
}

Required parameter

Description

listId

You must provide the id of the list where you want to create the segment.

name

Name of the segment that you want to create.

Updating a segment

Updates a segment according to the data sent in the request:

HTTP Request :PATCH /lists/{listId}/segments/{segmentId}

Request body

{
  "name": "females",
  "queryRule": "gender[eq]=f",
  "segmentType": "DYNAMIC"
}

Required parameter

Description

listId

You must provide the id of the list where you want to edit the segment.

segmentId

You must provide the id of the segment you want to edit.

Deleting a segment

Deletes a specific segment from a list.

HTTP Request :DELETE /lists/{listId}/segments/{segmentId}

Required parameter

Description

listId

You must provide the id of the list where you want to delete the segment.

segmentId

You must provide the id of the segment you want to delete.

Managing Templates

When you plan on sending a broadcast, you will usually start with designing a template, we recommend storing this design in our template system for future reuse.

Creating Templates

To create your templates, we recommend using our GUI for easy management of these templates, but if you need to use an API, check the methods below.

SMS Template

When you create or edit SMS template, the request body contains the following data:

HTTP Request: POST /sms

Request body

{
  "_id": "5ef50d781faf550007deb1ad",
  "tags": [],
  "highlight": false,
  "global": false,
  "name": "SMSTemplate",
  "description": "sms templated",
  "text": "Hola [[name]] !!",
  "updatedAt": "2020-07-08T01:18:05.858Z",
  "createdAt": "2020-07-08T01:18:05.858Z"
}

Parameter

Description

Id

SMS Template identifier.

tags

Tags that dynamically pull through information from your account. With tags, you can personalize your messages.

highlight

Template category filter (not necessary field)

global

Global SMS Template

name

Name of the SMS Template

description

Description of the SMS Template

text

SMS message content

createdAt

Creation date of the SMS template.

updateAt

Update date of the SMS template.

Email Template

When you create or edit Email template, the request body contains the following data:

HTTP Request:  POST /templates

Request body

{
  "_id": "5efb60891faf550007deb1b5",
  "tags": [],
  "highlight": false,
  "global": false,
  "name": "TemplateOne",
  "description": "Template Number One",
  "html": " ",
  "css": " ",
  "preview": " ",
  "createdAt": "2020-06-30T15:55:53.693Z",
  "updatedAt": "2020-06-30T15:55:53.693Z",
  "assets": []
}

Parameter

Description

Id

Email Template identifier.

tags

Tags that dynamically pull through information from your account. With tags, you can personalize your messages.

highlight

Template category filter (not necessary field).

global

Global Email Template.

name

Name of the Email Template.

description

Description of the Email Template.

html

Create a message via HTML.

css

Create a message via CSS style.

preview

Preview of the Email Template.

createdAt

Creation date of the Email template.

updateAt

Update date of the Email template.

assets

HTML/CSS assets.

Push Template

When you create or edit Email template, the request body contains the following data:

HTTP Request: POST /push

Request body

{
  "_id": "5ede56211faf550007deb137",
  "tags": [],
  "type": "plain",
  "highlight": false,
  "global": false,
  "name": "push template",
  "description": "testing emojis in push template",
  "notification": {
    "title": "hey in push ",
    "body": "hi"
  },
  "createdAt": "2020-06-08T15:15:45.681Z",
  "updatedAt": "2020-06-08T15:15:45.681Z"
}

Parameter

Description

Id

Push Template identifier.

tags

Tags that dynamically pull through information from your account. With tags, you can personalize your messages.

type

Type of template to simplify searches.

highlight

Template category filter (not necessary field).

global

Global EMAIL Template.

name

Name of the Push Template.

description

Description of the Push Template.

notification

title:  Title of the Push message.

body:   Push message content.

Image: Image Push Template

createdAt

Creation date of the Push template.

updatedAt

Update date of the Push template.

Preparing templates before sending a broadcast

To prepare the broadcast, the first step is to obtain the text that will be sent. The text can be added directly in the broadcast but we recommend storing the messages in the templates to facilitate future reuse.

Get SMS Template

SMS Template just stores a simple text message.

HTTP Request : GET /sms/{id}

Required parameter

Description

Id

You must provide the id of the SMS Template to get the details of a single instance of a SMS Template.

Get Email Template

Emails have an additional resource called Draft, this resource is the final representation of the message that will be sent to subscribers, it can be generated from a template or from scratch, it is always advisable to store the draft before any email delivery since through draft we provide the functionality of inline your css and make images compatible with most email clients.

For preparing a Email Broadcast we recommend follow this steps:

  1.  

    Get Email Template

    Get the details of a single instance of a EMAIL Template.

    HTTP Request : GET /templates/{id}

    Required Parameter

    Description

    Id

    You must provide the id of the Email Template to get the details of a single instance of an Email Template.

  2. Create Draft from template (or from scratch)

    Creates a new instance of an Email Draft.

    HTTP Request : POST /drafts

    {
      "_id": "5f3401761faf550007deb1f3",
      "template": "5efb60891faf550007deb1b5",
      "html": " ",
      "css": " ",
      "updatedAt": "2020-08-12T14:49:26.643Z",
      "createdAt": "2020-08-12T14:49:26.643Z",
      "assets": []
    }

    Parameter

    Description

    Id

    Email draft identifier.

    html

    Message draft  via HTML.

    css

    Message draft  via CSS style.

    assets

    HTML/CSS assets.

    updatedAt

    Update date of the Email draft.

    createdAt

    Creation date of the Email draft.

  3. Get HTML from Draft

    HTTP Request : GET /drafts/{id}

    Required Parameter

    Description

    Id

    You must provide the id of the Email draft to get the details of a single instance of an Email draft.

Get Push Template

Push Template returns a notification object with title and body, also you can add a data object with extra payload to send.

HTTP Request : GET /push/{id}

Required parameter

Description

Id

You must provide the id of the Push Template to get the details of a single instance of a Push Template.

Sending a Broadcast

You can send three types of Broadcast:

  • SMS

  • Email

  • Push notification

Main identifier for the broadcast

The status of the delivery channel SMS, EMAIL, PUSH:

SMS

Description

"Microsession NW - SMS now"

Send SMS message Now

"Microsession NW - SMS scheduled"

Send SMS message Scheduled

"Microsession NW - SMS later"

Send SMS message Pending

EMAIL

Description

"Microsession NW - EMAIL now"

Send EMAIL message Now

"Microsession NW - EMAIL scheduled"

Send EMAIL message Scheduled

"Microsession NW - EMAIL later"

Send EMAIL message Pending

PUSH

Description

"Microsession NW - PUSH now"

Send PUSH message Now

"Microsession NW - PUSH scheduled"

Send PUSH message Scheduled

"Microsession NW - PUSH later"

Send PUSH message Pending

Sending a SMS Broadcast

When you create SMS Broadcast, the response body contains the basic data of the broadcast created:

HTTP Request : POST /broadcasts

SMS Response body

{  
   "deliveryMethod": "SMS",
   "campaignName": "Microsession NW - SMS now",  
   "description": "Microsession NW - SMS now",  
   "listId": 829,  
   "listField": "mobile",  
   "filters": "mobile%5Blike%5D=+",  
   "filterName": "only mobile numbers",  
   "message": "Hola [[name]]. Hasta luego",  
   "origin": "14155824559",  
   "scheduleWithoutDate": false,  
   "throttle": 250,  
   "emailField": "email",  
   "requestDR": true
}

Parameter

Description

deliveryMethod

Define The Delivery Channel. Available delivery channels are SMS, EMAIL or PUSH. In this case the delivery channel is SMS.

campaignName

Define a Broadcast Name. Name of the campaign, used as the main identifier for the broadcast.

description

Define the Description of the delivery channel.

listId

Define the List identifier and the Recipients of your Broadcast. The id of the list that you want to send the message.

The recipients can be:

  • All subscribers on list.

  • A segment previously created in the corresponding API (use the field segmentId).

listField

Define the List Field. Type of delivery channel.

filters

Define the Filters.  Filter that you want to apply on the message.

filterName

Define the Filter Name. The content is the name of the filter that you want to apply on the message.

message

Define the Content of Broadcast.  Delivery Channel SMS is a plain text.

origin

Define the origin of Broadcast. Delivery Channel SMS is a valid code.

scheduleWithoutDate

Define the Date & Time. Time of your Broadcast.

To define broadcast date you have two main options:

  • Send now: Add the field scheduleWithoutDate to false when sending the broadcast.

  • Scheduled: Add the field broadcastDate with date in UTC Zulu format. (yyyy-mm-dd-Thh:mm:ss.ssZ) when sending the broadcast.

throttle

Message delivery speedometer. For example, 250 messages are sent per second.

emailField

Define Additional user information.

Optionally, you can include these fields:

  • emailField with the name of the column that stores the emails in the main list.

  • smsField with the name of the column that stores the mobile number in the main list.

  • clientId with the name of the column that stores the main identifier in the main list.

These additional fields help connect the information for your reports.

requestDR

Request delivery receipt ( Yes “True” or “False “No” )

Sending an Email Broadcast

When you create Email Broadcast, the response body contains the basic data of the broadcast created:

HTTP Request : POST /broadcasts

Email Response body

{  "deliveryMethod": "EMAIL",
   "campaignName": "Microsession NW - EMAIL now",
   "description": "Microsession NW - EMAIL now",
   "listId": 829, 
  "listField": "email",  
  "filters": "email%5Blike%5D=@", 
  "filterName": "only emails", 
  "message": " ", 
  "origin": "noreply-staging@messangi.me", 
  "scheduleWithoutDate": false, 
  "throttle": 160,
  "smsField": "mobile",  
  "subject": "Microsession NW - EMAIL now"
}

Parameter

Description

deliveryMethod

Define The Delivery Channel. Available delivery channels are SMS, EMAIL or PUSH.  In this case the delivery channel is EMAIL.

campaignName

Define a Broadcast Name. Name of the campaign, used as the main identifier for the broadcast.

description

Define the Description of the delivery channel.

listId

Define the List identifier and the Recipients of your Broadcast. The id of the list that you want to send the message.

The recipients can be:

  • All subscribers on list.

  • A segment previously created in the corresponding API (use the field segmentId).

listField

Define the List Field. Type of delivery channel.

filters

Define the Filters.  Filter that you want to apply on the message.

filterName

Define the Filter Name. The content is the name of the filter that you want to apply on the message.

message

Define the Content of Broadcast.  Delivery Channel EMAIL it is an HTML code and has an additional field subject.

origin

Define the origin of Broadcast. Delivery Channel EMAIL is a valid from (email sender).

scheduleWithoutDate

Define the Date & Time of your Broadcast.

To define broadcast date you have two main options:

  • Send now: Add the field scheduleWithoutDate to false when sending the broadcast.

  • Scheduled: Add the field broadcastDate with date in UTC Zulu format. (yyyy-mm-dd-Thh:mm:ss.ssZ) when sending the broadcast.

throttle

Message delivery speedometer. For example, 250 messages are sent per second.

emailField

Define Additional user information.

Optionally, you can include these fields:

  • emailField with the name of the column that stores the emails in the main list.

  • smsField with the name of the column that stores the mobile number in the main list.

  • clientId with the name of the column that stores the main identifier in the main list.

These additional fields help connect the information for your reports.

subject

Define the Subject of the Broadcast. Add subject field of the delivery channel, used as the main identifier for the broadcast.

Sending a Push Broadcast

When you create Push notification Broadcast, the response body contains the basic data of the broadcast created:

HTTP Request : POST /broadcasts

Push Response body

{  
  "deliveryMethod": "PUSH",  
  "campaignName": "Microsession NW - PUSH now",  
  "description": "Microsession NW - PUSH now",  
  "listId": 829,  "listField": "devices",  
  "filters": "devices%5Blike%5D=pushToken", 
  "filterName": "only users with devices", 
  "message": "Hola [[name]]. Hasta luego ", 
  "scheduleWithoutDate": false, 
  "throttle": 1200, 
  "smsField": "mobile",  
  "emailField": "email",  
  "appName": "application Name", 
  "title": "Hola [[name]]. Hasta luego ",  
  "android": {    
  "credentialId": "5f8d92cc2b39611dbd528646"  
  }
}

Parameter

Description

deliveryMethod

Define The Delivery Channel. Available delivery channels are SMS, EMAIL or PUSH. In this case the delivery channel is PUSH.

campaignName

Define a Broadcast Name. Name of the campaign, used as the main identifier for the broadcast.

description

Define the Description of the delivery channel.

listId

Define the List identifier and the Recipients of your Broadcast. The id of the list that you want to send the message.

The recipients can be:

  • All subscribers on list.

  • A segment previously created in the corresponding API (use the field segmentId).

listField

Define the List Field. Type of delivery channel.

filters

Define the Filters.  Filter that you want to apply on the message.

filterName

Define the Filter Name. The content is the name of the filter that you want to apply on the message.

message

Define the Content of Broadcast.  Delivery Channel PUSH it is a Notification object that includes title and text, it can also include additional data

origin

Define the origin of Broadcast. Delivery Channel PUSH is an ApplicationID registered on our system.

scheduleWithoutDate

Define the Date & Time of your Broadcast.

To define broadcast date you have two main options:

  • Send now: Add the field scheduleWithoutDate to false when sending the broadcast.

  • Scheduled: Add the field broadcastDate with date in UTC Zulu format. (yyyy-mm-dd-Thh:mm:ss.ssZ) when sending the broadcast.

throttle

Message delivery speedometer. For example, 250 messages are sent per second.

smsField / emailField

Define Additional user information.

Optionally, you can include these fields:

  • emailField with the name of the column that stores the emails in the main list.

  • smsField with the name of the column that stores the mobile number in the main list.

  • clientId with the name of the column that stores the main identifier in the main list.

These additional fields help connect the information for your reports.

appName

Application name

Title

Title of the Push notification Broadcast

Sending a SMS

These instructions describe how you can send your first SMS message! Using cURL calls.

Before you can start using the SMS API, you need to complete the following steps:

  1. Get access credentials (API Key).

  2. Have cURL installed in your machine.

Build you API call

Your API call must have the following components:

  • A host -> The host requests are always https://staging-aws.messangi.me/

  • An Authorization header -> Your API Key must be included in the Authorization header.

  • A request -> When submitting data to a resource via POST or PUT, you must submit your payload in JSON.

Note

Every time the total number of characters is exceeded (160 characters), the SMS counter will be incremented.

Send your SMS using the API

The steps to send an SMS message using the SMS API are the following:

Request body

curl -X POST "https://staging-aws.messangi.me/raven/v2/messages" -H  "accept: application/json" -H  "Authorization: Bearer <YOUR_API_KEY>" -H  "Content-Type: application/json" -d "{\"from\":\"12345\",\"text\":\"text demo\",\"to\":\"+580000000005\",\"type\":\"MT\"}"
  1. Copy the curl example above.

  2. Paste the curl call into your favorite text editor.

  3. Copy your API key and paste it in the "Authorization" header.

  4. In the data section, specify the "from" (virtual code), "text" (text message), "to" (mobile number of the recipient) and “type” (MT or MO messaging).

  5. Copy the code and paste it in your terminal command.

  6. Press Enter.

  7. Check the response body and verify the SMS message sent “to” your recipient.

All responses are returned in JSON format. We specify this by sending the Content-Type header.

Sending an Email

These instructions describe how you can send your first email message! Using cURL calls.

Before you can start using the Email API, you need to complete the following steps:

  1. Get access credentials (API Key).

  2. Have cURL installed in your machine.

  3. If you want to send bulk emails, a sender email is required. You need to contact your account manager to verify an email address.

  4. Amazon sends you an email providing the authorization to send bulk messages through your email address

  5. Click on the URL link on the email to verify your email

  6. Congratulations you can now start sending emails using your verified email address as the sender.

Build your API call

Your API call must have the following components:

  • A host -> The host requests are always {base url}

  • An Authorization header -> Your API Key must be included in the Authorization header.

  • A request -> When submitting data to a resource via POST or PUT, you must submit your payload in JSON.

Send your Email using the API

The steps to send an email message using the Email API are the following:

Request body

curl -X POST "https://staging-aws.messangi.me/crowsnest/v2/emails" -H  "accept: application/json" -H  "Authorization: Bearer <YOUR_API_KEY>" -H  "Content-Type: application/json" -d "{\"to\":\"email@service.com\",\"from\":\"service@service.com\",\"text\":\"example text\",\"subject\":\"Email Subject\",\"externalId\":\"123456789abcde\",\"clientId\":\"48118112\",\"callbacks\":[\"string\"]}"
  1. Copy the curl example above.

  2. Paste the curl call into your favorite text editor.

  3. Copy your API key and paste it in the "Authorization" header.

  4. In the data section, specify the "to" (email recipient), "from" (who sent the email), "text" (email message) and “EmailSubject”.

  5. Copy the code and paste it in your terminal command.

  6. Press Enter.

  7. Check the inbox of the address you specified as the "to" email and see your message!

All responses are returned in JSON format. We specify this by sending the Content-Type header.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.