Available API Methods

Mapp Connect is a simple async API with methods to:

GET

List of Mapp Engage groups, prepared email, push, and SMS messages and mobile App ID Mapp Engage API.

POST

Add or update data for:

  • User:
    • create a contact in Mapp Engage (not existing contacts require a group ID in a payload to be subscribed in the system)
    • update an existing contact (group ID is not required), unsubscribe or remove a contact
  • Email:
    • send a prepared email message to the contact with parameters
    • send a prepared email message to a group (without parameters)
  • SMS: send a prepared SMS message to the contact (mobile number or email field is required) with parameters
  • Push: send a prepared push message to the contact (mobile number or email field is required) with parameters
  • Transaction: add order details to contact and send an order message
  • Wishlist: add a Wishlist item to the contact profile
  • Abandoned Cart: add abandoned cart product to the contact profile
  • Automation: trigger whiteboard automation from a third-party app (see Set Up a Mapp Connect Automation Event)
  • Product Catalog: create and/or update a product catalog item in Mapp Engage
  • Coupon: create a coupon

GET

Here is a list of the endpoints to GET groups and prepared message IDs from integrated systems.

Connect

/{integrationId}/connect

Groups

/{integrationId}/group

List of Email prepared Messages

/{integrationId}/message

List of Mobile Apps

/{integrationId}/mobile-app

List of Push prepared Messages

/{integrationId}/message/push

List of SMS prepared Messages

/{integrationId}/message/sms

POST

Call Template

POST /integration/<INTEGRATION ID>/event{?subtype=<subtypeName>}

The request body can contain any JSON object.

Response: HTTP status code

Examples

Please note that the names used in calls need to be the same as the names used in your mapping. 

 Add a user and subscribe to the group

POST /integration/<INTEGRATION ID>/event?subtype=user

Example of sent event:

{ 
    "email":"user@mapp.com", 
    "group":"2324333335", 
    "first":"firstval",
    "second":"secondval"   
}
CODE

Response: HTTP status code

 Remove a user

POST /integration/<INTEGRATION ID>/event?subtype=user

FLAG: 'delete'

Example of sent event:

{ 
   "email":"user@mapp.com", 
   "group":"2324333335", 
   "delete":"true"          
}
CODE

Response: HTTP status code

 Send a prepared SMS message to a user with parameters

POST /integration/<INTEGRATION ID>/event?subtype=sms

MessageId is the ID of the prepared message. You can use 'email', 'recipientMobileNumber' or 'recipientId' as an identifier.

Example of sent event:

{
   "recipientMobileNumber":"+48666777888", 
   "messageId":"2324333335"
       
}
CODE

Response: HTTP status code

 Send prepared Push message to a user with parameters

POST /integration/<INTEGRATION ID>/event?subtype=push

'pushMessageId' is the ID of the push message template (not the campaign), 'mobileAppId' refers to the app that should be used, and 'email' is used as a user identifier. 

Example of sent event:

{
   "email":"john.smith@xx.xx", 
   "pushMessageId":"1234",
   "mobileAppId":"5678",
   "param1":"param 1 value"       
}
CODE

Response: HTTP status code

 Send a single message with parameters
POST /integration/<INTEGRATION ID>/event?subtype=email

MessageId is the ID of the prepared message.

Example of sent event:

{
   "email":"user@mapp.com", 
   "messageId":"2324333335", 
   "first":"firstval",
   "second":"secondval"                              
}
CODE

Response: HTTP status code

 Send a single message to a user with "externalTransactionFormula"

POST /integration/<INTEGRATION ID>/event?subtype=email

Request body can contain any JSON object. 

MessageId it's an ID of the prepared message.

Example of sent event:

{          "email":"user@mapp.com", 
           "messageId":"2324333335", 
           "externalTransactionFormula":"myUniqueValue......" 
}
CODE

Response: HTTP status code

For more information see:

 Send a group message

POST /integration/<INTEGRATION ID>/event?subtype=email

MessageId it's an ID of the prepared message.

Example of sent event:

{   
  "group":"12", 
  "messageId":"2324333335",    
}
CODE
 Send a transactional email and store transaction details in Transactional Related Data

This call sends a transactional email and stores transaction (order) details in Transactional Related Data.

POST /integration/<INTEGRATION ID>/event?subtype=transaction

MessageId is the ID of the prepared message.

Example of sent event:

{ 
   "email":"user@mapp.com",
   "messageId":"2324333335",
   "items":[{"sku":"JB-129","name":"Dungen-H","price":"15","qty_ordered":"1"}],
   "group":"1200073880",
   "orderId":"1012",
   "transaction_date": "2020-04-28T12:30:08.537Z",
   "currency":"GBP"
}
CODE
 Save transaction details in Transactional Related Data without sending transactional email

POST /integration/<INTEGRATION ID>/event?subtype=transaction

MessageId is the ID of the prepared message.

Example of sent event:

{ 
   "email":"user@mapp.com",
   "items":[{"sku":"JB-129","name":"Dungen-H","price":"15","qty_ordered":"1"}],
   "group":"1200073880",
   "orderId":"1012",
   "transaction_date": "2020-04-28T12:30:08.537Z",
   "currency":"GBP"
}
CODE
 Product Catalog

This call adds a new product to the Product Catalog.

POST /integration/<INTEGRATION ID>/event?subtype=product

Example of sent event:

{  
    "productSKU":"12345678",
    "productName":"testproduct",
	"productPrice":"10.5",
	"stockTotal":"20000",
	"productURL":"https://mapppartneruk.myvtex.com/testproduct/p",
	"imageURL":"https://mapppartneruk.vteximg.com.br/arquivos/ids/155397-55-55/mapp.png?v=637771525123470000",
	"zoomImageURL":"https://mapppartneruk.vteximg.com.br/arquivos/ids/155397-55-55/mapp.png?v=637771525123470000",
	"brand":"Brand",
	"category":"Test Category",
	"description":"Addition"
}
CODE
 Add a single coupon code

POST /integration/<INTEGRATION ID>/event?subtype=coupon

Example of sent event:

{ 
   "listName":"campaing1",  //if list does not exist, it will be created   
   "value":"summer1jaosajsoas"
}
CODE

Postman Sandbox

This Postman collection can be used to test how to authenticate and use all types of events. To use it, create a free Postman account (or download the free app) and upload the collection. The procedures described below use this collection to demonstrate how it works.

DOWNLOAD THE POSTMAN SANDBOX COLLECTION