API Endpoints
    • 3 Minutes to read
    • Dark
      Light

    API Endpoints

    • Dark
      Light

    Article summary

    Available API Methods

    Mapp Connect is a simple async API with methods to:

    GET

    List Mapp Engage groups, prepared emails, push and SMS messages, and mobile App ID.

    POST

    Add or update data for:

    • User:

      • Create a contact in Mapp Engage (non-existing contacts require a group ID in the 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 or delete order details to contact and send an order message.

    • Wishlist: Add or delete a Wishlist item from the contact profile.

    • Abandoned Cart: Add or delete abandoned cart products from the contact profile.

    • Automation: Trigger whiteboard automation from a third-party app (see Set Up a Mapp Connect Automation Event).

    • Product Catalog: Create, update, and/or delete a product catalog item in Mapp Engage.

    • Coupon: Create a coupon.

    • Batch import: Send up to 1000 requests at once.

    GET

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

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

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

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

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

    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......" 
    }

    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",    
    }

    Save transaction details in the Transactions eCommerce table

    This call stores transaction (order) details in the Transactions eCommerce table and, optionally, sends a transactional email.

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

    MessageId is the ID of the prepared message.

    Example of sent event:

    {
      "email": "test.example@mapp.com",
      "messageId": "9634",
      "items": [
     {
      "sku": "JB-129",
      "name": "George-H",
      "price": "15",
      "qty_ordered": "1"
     }
     ],
      "group": "8262",
      "orderId": "06032023",
      "transaction_date": "2020-04-28T12:30:08.537Z",
      "currency": "GBP"
    }

    The "messageId" parameter is optional

    • If provided, the transaction is saved/updated, and a message with the provided messageId is sent to the given email address.

    • If not provided, only the transaction is saved/updated.

    Remove a transaction from the Transactions eCommerce table

    This call removes the transaction from the eCommerce table.

    {
       "orderId": "12345",
       "email": "test@test.com",
       "delete": "true"
    }

    Product Catalog

    This call adds/deletes a new product to/from the Product Catalog.

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

    Example of sent event:

    Add

    {
    "productSKU": "aaa-bbb-ccc",
    "productName": "someName",
    "productPrice": "123",
    "productURL": "http://somedomain.com"
    }

    Delete

    {
    "productSKU": "aaa-bbb-ccc",
    "delete": "true"
    }

    Abandoned Cart / Wishlist

    Example "default" json payloads for "Generic" integration type:

    Add

    {
       "email": "test.example@mapp.com",
       "sku": "0602-2023-123",
       "createdAt": "2022-05-14T17:25:43.511Z",
       "price": "25",
       "size": "M"
    }

    If the contact doesn't exist in Mapp Engage, the data will not be saved.

    Delete

    { 
       "sku": "0602-2023-123", 
       "email": "test@mapp.com",  
       "delete": "true"
    }

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

    Batch import: send multiple requests at once

    POST /integration/<integrationID>/event/batch?subtype=<subtype>

    The maximum payload of a batch request is 1000 events. If the payload exceeds 1000, the entire payload is discarded and throws an exception (400).

    The body needs to be sent as an array, for example:

    [
      {
        "email":john@mapp.com,
        "group":"10144",
        "nosto_segments":"High Value Customers area New York"
      },
      {
        "email":mary@gmail.com,
        "group":"10144",
        "nosto_segments":"High Value Customers area New York"
      }
    ]

    Postman Sandbox

    This Postman collection can be used to test your authentication credentials and all endpoints. To use it, create a free Postman account online or in their free app and upload the collection.


    Was this article helpful?