Mapp Connect is a data layer for Mapp Engage. It uses add-ons and asynchronous API connections to allow you to exchange data between third-party marketing applications and Mapp Engage.
Use of Mapp Connect
Access all your third-party integrations from one central location
Import contact and eCommerce data from your own or third-party applications into Mapp Engage
Unify source data into the required format during the import
Send Emails, SMS, and Push Messages using the imported data
Create Whiteboard automations triggered by external events
Here, you will find a description of the API Endpoints.
Authentication
Mapp Connect calls authenticate using a JSON Web-Based Token (JWT) created from your integration number and secret key. You can find this information in the Mapp Connect UI and re-generate the secret there. To generate the JWT, you can follow one of these code samples:
var Property = require('postman-collection').Property;
function encodeParams(object) {
let buff = Buffer.from(JSON.stringify(object));
let base64data = normalizeBase64string(buff.toString('base64')); return base64data;
}
function normalizeBase64string(base64string) {
return base64string.replace('+', '-').replace('/', '_').replace(/=+$/, '');
}
let request_body = pm.request.body.raw;
let request_uri = [...pm.request.url.path];
request_uri.shift();
request_uri = '/' + request_uri.join('/')
request_uri = Property.replaceSubstitutions(request_uri, pm.collectionVariables.toObject());
let query_string = pm.request.url.getQueryString();
let key = "............."; // add the secret key of the integration here - can be (re-)generated in Mapp Connect UI
let request_data = request_uri.toString();
if (request_body) {
request_data += '|' + request_body;
}
if (query_string) {
request_data += '|' + query_string.toString();
}
console.log(request_data);
let request_hash = CryptoJS.SHA1(request_data).toString(CryptoJS.digest);
const jwtHeader = {
alg: 'HS256'
};
const jwtBody = {
'request-hash': request_hash,
exp: Date.now() + 600000
};
const encodedBody = encodeParams(jwtBody);
const encodedHeader = encodeParams(jwtHeader);
const signature = CryptoJS.HmacSHA256(encodedHeader + '.' + encodedBody, key).toString(CryptoJS.enc.Base64)
let jwt = `${encodedHeader}.${encodedBody}.${signature}`;
console.log(jwt);
pm.request.headers.add({key: "auth-token", value: jwt});/*
* MappConnectHmacAuth
*
* This is a sample Java client demonstrating authentication with Mapp Connect using HMAC JWT.
*
* Usage Instructions:
* 1. Set your integration ID and secret in the constants below.
* 2. Use the verbose flag to enable detailed debug output if needed.
* 3. Run the program to send a GET request to the /ping endpoint and print the response.
*
* This sample demonstrates:
* - How to construct the request hash and JWT for Mapp Connect authentication.
* - How to send authenticated HTTP requests using Java.
* - How to control output verbosity for easier debugging and integration testing.
*/
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import java.io.BufferedReader;
import java.io.InputStreamReader;
public class MappConnectHmacAuth {
// Cluster URL for Mapp Connect API
private static final String CLUSTER_URL = "https://jamie.g.shortest-route.com";
// Your integration ID
private static final String INTEGRATION_ID = "xxx";
// Your integration secret
private static final String SECRET = "xxx";
// Token expiry in milliseconds (10 minutes)
private static final long TOKEN_EXPIRY_MS = 600_000L;
public static void main(String[] args) throws Exception {
// Example usage for GET request
String getResponse = callApiWithHmacAuth(
"GET", // HTTP method
"/api/v1/integration/" + INTEGRATION_ID + "/ping", // endpoint
"", // body (empty for GET)
"", // query string (empty for GET)
false // verbose output
);
System.out.println("GET response: " + getResponse);
// Example usage for POST request
// For simple JSON bodies, string concatenation is sufficient.
// For more complex or production use cases, it is recommended to utilize a JSON library such as Gson or Jackson for safer and more maintainable code.
// String newEmail = "user@example.com";
// String postBody = "{" +
// "\"email\":\"" + newEmail + "\"," +
// "\"group\":0," +
// "\"firstname\":\"testName\"}";
//
// String postResponse = callApiWithHmacAuth(
// "POST",
// "/api/v1/integration/" + INTEGRATION_ID + "/event",
// postBody,
// "subtype=user",
// true // verbose output
// );
// System.out.println("POST response: " + postResponse);
}
/**
* Calls Mapp Connect API with HMAC JWT authentication.
* Supports GET and POST requests.
*
* @param method "GET" or "POST"
* @param endpoint API endpoint (e.g. "/api/v1/integration/.../ping")
* @param body Request body for POST, empty for GET
* @param query Query string, e.g. "param=value", or empty
* @param verbose true for debug output, false for only response
* @return API response as String
* @throws Exception on network or crypto errors
*/
public static String callApiWithHmacAuth(String method, String endpoint, String body, String query, boolean verbose) throws Exception {
// Null checks for parameters
if (method == null) throw new IllegalArgumentException("HTTP method cannot be null");
if (endpoint == null) throw new IllegalArgumentException("Endpoint cannot be null");
// Build full request path for Mapp Connect
String fullRequestPath = "/charon" + endpoint;
// Build request-data string for hashing
StringBuilder requestData = new StringBuilder(endpoint);
if (body != null && !body.isEmpty()) requestData.append("|").append(body);
if (query != null && !query.isEmpty()) requestData.append("|").append(query);
// Compute SHA1 hash of request-data
String requestHash = sha1Hex(requestData.toString());
// Build JWT header and payload
String jwtHeader = "{\"alg\":\"HS256\"}";
long exp = System.currentTimeMillis() + TOKEN_EXPIRY_MS; // Use constant for expiry
String jwtPayload = "{\"request-hash\":\"" + requestHash + "\",\"exp\":" + exp + "}";
// Encode header and payload in base64url
String encodedHeader = normalizeBase64(Base64.getEncoder().encodeToString(jwtHeader.getBytes(StandardCharsets.UTF_8)));
String encodedBody = normalizeBase64(Base64.getEncoder().encodeToString(jwtPayload.getBytes(StandardCharsets.UTF_8)));
String unsignedToken = encodedHeader + "." + encodedBody;
// Sign the token with your secret
String signature = normalizeBase64(hmacSha256(unsignedToken, SECRET));
String jwt = unsignedToken + "." + signature;
// Print request info if verbose
if (verbose) {
System.out.println("========= Outgoing Request =========");
System.out.println("URL: " + CLUSTER_URL + fullRequestPath + (query.isEmpty() ? "" : ("?" + query)));
System.out.println("Method: " + method);
System.out.println("Headers:");
System.out.println(" Content-Type: application/json");
System.out.println(" auth-token: " + jwt);
System.out.println("Body:");
System.out.println(body.isEmpty() ? " [No body for GET request]" : " " + body);
System.out.println("=== Debugging Hash Input ===");
System.out.println("request-data: " + requestData);
System.out.println("request-hash: " + requestHash);
System.out.println("====================================\n");
}
// Build URI (add query string if present)
URI uri = new URI(CLUSTER_URL + fullRequestPath + (query.isEmpty() ? "" : ("?" + query)));
URL url = uri.toURL();
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setConnectTimeout(10_000); // 10 seconds connect timeout
conn.setReadTimeout(10_000); // 10 seconds read timeout
conn.setRequestMethod(method);
conn.setRequestProperty("Content-Type", "application/json");
conn.setRequestProperty("auth-token", jwt);
// For POST, send body
if (method.equals("POST")) {
conn.setDoOutput(true);
conn.getOutputStream().write(body.getBytes(StandardCharsets.UTF_8));
}
int responseCode = conn.getResponseCode();
// Use try-with-resources for BufferedReader
try (BufferedReader reader = new BufferedReader(new InputStreamReader(
(responseCode >= 200 && responseCode < 300) ? conn.getInputStream() : conn.getErrorStream()))) {
StringBuilder response = new StringBuilder();
String line;
while ((line = reader.readLine()) != null) response.append(line);
// Print response based on verbosity
if (verbose) {
System.out.println("Response Code: " + responseCode);
System.out.println("Response Body: " + response);
}
return response.toString();
}
}
// Helper: SHA1 hex digest
private static String sha1Hex(String input) throws Exception {
MessageDigest md = MessageDigest.getInstance("SHA-1");
byte[] digest = md.digest(input.getBytes(StandardCharsets.UTF_8));
StringBuilder sb = new StringBuilder();
for (byte b : digest) sb.append(String.format("%02x", b));
return sb.toString();
}
// Helper: HMAC SHA256 signature, base64 encoded
private static String hmacSha256(String data, String secret) throws Exception {
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec keySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
sha256_HMAC.init(keySpec);
byte[] rawHmac = sha256_HMAC.doFinal(data.getBytes(StandardCharsets.UTF_8));
return Base64.getEncoder().encodeToString(rawHmac);
}
// Helper: Convert base64 to base64url (RFC 4648)
private static String normalizeBase64(String b64) {
return b64.replace('+', '-').replace('/', '_').replaceAll("=+$", "");
}
}<?php
/*
* MappConnectHmacAuth
*
* This is a sample PHP client demonstrating authentication with Mapp Connect using HMAC JWT.
*
* Usage Instructions:
* 1. Set your integration ID and secret in the constants below.
* 2. Use the $verbose flag to enable detailed debug output if needed.
* 3. Run the script to send a GET request to the /ping endpoint and print the response.
*
* This sample demonstrates:
* - How to construct the request hash and JWT for Mapp Connect authentication.
* - How to send authenticated HTTP requests using PHP and cURL.
* - How to control output verbosity for easier debugging and integration testing.
*/
// Define your integration ID and secret here
$INTEGRATION_ID = "xxx";
$SECRET = "xxx";
$CLUSTER_URL = "https://jamie.g.shortest-route.com";
function base64UrlEncode($data) {
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
function hmacSha256($data, $secret) {
return base64UrlEncode(hash_hmac('sha256', $data, $secret, true));
}
function sha1Hex($data) {
return strtolower(sha1($data));
}
function buildJwt($requestHash, $secret) {
$header = ['alg' => 'HS256'];
$exp = time() * 1000 + 600000; // 10 minutes into the future
$payload = [
'request-hash' => $requestHash,
'exp' => $exp
];
$encodedHeader = base64UrlEncode(json_encode($header));
$encodedPayload = base64UrlEncode(json_encode($payload));
$unsignedToken = $encodedHeader . '.' . $encodedPayload;
$signature = hmacSha256($unsignedToken, $secret);
return $unsignedToken . '.' . $signature;
}
/**
* Calls Mapp Connect API with HMAC JWT authentication.
* Supports GET and POST requests.
*
* @param string $method "GET" or "POST"
* @param string $endpoint API endpoint (e.g. "/api/v1/integration/.../ping")
* @param string $body Request body for POST, empty for GET
* @param string $query Query string, e.g. "param=value", or empty
* @param bool $verbose true for debug output, false for only response
* @return void
*/
function callApiWithHmacAuth($method, $endpoint, $body = '', $query = '', $verbose = false) {
global $CLUSTER_URL, $SECRET;
$fullRequestPath = "/charon" . $endpoint;
$requestData = $endpoint;
if (!empty($body)) $requestData .= "|" . $body;
if (!empty($query)) $requestData .= "|" . $query;
$requestHash = sha1Hex($requestData);
$jwt = buildJwt($requestHash, $SECRET);
$url = $CLUSTER_URL . $fullRequestPath . (empty($query) ? '' : ('?' . $query));
if ($verbose) {
echo "========= Outgoing Request =========\n";
echo "URL: $url\n";
echo "Method: $method\n";
echo "Headers:\n";
echo " Content-Type: application/json\n";
echo " auth-token: $jwt\n";
echo "Body:\n";
echo empty($body) ? " [No body for GET request]\n" : " $body\n";
echo "=== Debugging Hash Input ===\n";
echo "request-data: $requestData\n";
echo "request-hash: $requestHash\n";
echo "====================================\n";
}
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'auth-token: ' . $jwt
]);
if ($method === 'POST' && !empty($body)) {
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
}
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($verbose) {
echo "Response Code: $httpCode\n";
echo "Response Body: $response\n";
} else {
echo $response . "\n";
}
}
// Example usage for GET request
callApiWithHmacAuth(
"GET",
"/api/v1/integration/$INTEGRATION_ID/ping",
"",
"",
false // verbose output
);
// Example usage for POST request
// $newEmail = "user@example.com";
// $postBody = json_encode([
// "email" => $newEmail,
// "group" => 0,
// "firstname" => "testName"
// ]);
// callApiWithHmacAuth(
// "POST",
// "/api/v1/integration/$INTEGRATION_ID/event",
// $postBody,
// "subtype=user",
// true // verbose output
// );
?>You can find more information about Mapp Connect in our Mapp Connect documentation.