General information

Authentication

Manago AI API v3 uses a new and simpler authentication mechanism. The only authentication field required is a Header API-KEY containing your API key. You can create a new API key in Manago AI ➔ Integration Center ➔ API ➔ API v3.

Example:

<?php
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'API-KEY: S7LOELpItzOXVAZzMa…VEMbIJL6EH4Z45TTgK'
        )
    );
?>

Note: You can specify when your API key expires, as well as revoke an already created API key. If you have trouble with authentication, start by verifying that your API key is valid. The key status can be checked in the same place where you create new keys.

Header name: API-KEY
Header value: API key from Manago AI

Validations

To make sure the data transferred to Manago AI is well-structured, ordered, and easily accessible we use validations for some specific fields. The most important validations include:

Data type	Standard	External resources
Email	RFC882	RFC882 at ietf.org
URL	Apache URL validator	UrlValidator at apache.org
Currency	ISO 4217	ISO 4217 at SIX
Language	ISO 639-1	ISO 639-1 at loc.gov
Language and region	BCP 47	BCP 47 codes at Microsoft

Methods and Content-Types

Manago AI API v3 uses two HTTP methods:

POST – used for inserting, updating, and deleting data. It is also used when asynchronously downloading data from Manago AI
GET – used when synchronously downloading data from Manago AI

All POST requests must be encapsulated in JSON format. Most libraries automatically add Content-Type: application/json header when sending data encapsulated in JSON.

General errors and warnings

It’s only those who do nothing that make no mistakes. – Joseph Conrad

Manago AI API is designed to gracefully accept all data that meet the requirements and reject only those requests that cannot be processed. Below you can find a list of general errors and warnings with Reason codes assigned to them.

Error/warning	Reason code	HTTP
Authentication error `Error message`	10	400
Field exceeds limit `fieldName\|min:0\|max:256\|Error message`	11	400
Data trimmed warning `fieldName\|max:256\|Warning message`	12	200
Missing required field `fieldName\|Error message`	13	400
Wrong field type `fieldName:type\|Error message`	14	400
Using non-unique value `fieldName\|Error message`	15	400
Trying to access resource with identifier not present in Manago AI `fieldName\|Error message`	16	400
Trying to set a required value as null `fieldName\|Error message`	17	400
Value not matching a required structure (RegEx) `fieldName\|Error message`	18	400
Trying to add a resource above available limit `resourceName\|limit:3\|Error message`	19	400

Emails

List emails

Sample request:

https://api.manago.ai/v3/email/list?type=STANDARD&dateFrom=1559938888&dateTo=1659938888

Sample response:

{
    "emails": [
        {
            "emailId": "1234-...-5678",
            "sender": {
                "emailId": "1234-...-5678",
                "emailAddress": "[email protected]",
                "displayName": "Example Sender"
            },
            "modifiedOn": 1559938888,
            "name": "My example email",
            "subject": "Just a subject example",
            "designedIn": "DND",
            "group": "Example group",
            "author": "[email protected]"
        },
        {
            "emailId": "8765-...-4321",
            "sender": {
                "accountId": "abcd-...-dcba",
                "emailAddress": "[email protected]",
                "displayName": "Example Sender"
            },
            "modifiedOn": 1659938888,
            "type": "STANDARD",
            "name": "Another example email",
            "subject": "Simple subject example",
            "designedIn": "HTML",
            "group": "Example group",
            "author": "[email protected]"
        }
    ]
}

You can list emails created in Manago AI to display them in an external system. This could be useful when creating an integration that allows you to send emails directly from an eCommerce platform or to list emails available for subscription confirmation.

Endpoint:

https://api.manago.ai/v3/email/list

Method:

GET

Fields

Field	Limits	Description
type	enum	Specify the types of emails you want to list or export: STANDARD SUBSCRIPTION_CONFIRMATION The default value is STANDARD
dateFrom*	UNIX timestamp in s	Starting date of export. The modified on date is used.
dateTo*	UNIX timestamp in s	Ending date of export. The modified on date is used.

Response:

The response will contain a maximum of 100 emails. If your export contains more than 100 emails you can use the modifiedOn date of the last email from the array as dateFrom parameter for your next export.

Field	Description
emails	Array of emails created in Manago AI
emailId	Internal Manago AI email identifier
sender	Object containing information about sending account
accountId	Internal Manago AI sender identifier
emailAddress	Sender email address
displayName	Sender display name. Most email clients use this field when displaying the email sender in a form: Display Name < [email protected] >.
modifiedOn	Last modification date of email
name	Email name as specified in Manago AI
subject	Email subject
designedIn	Field specifying how the email was created. The enum can be: HTML DND ZIP FREEMARKER URL
group	Email group as specified in Manago AI
author	Manago AI user who has created the email

Web Push

Send Web Push notification

Sample request

{
    "templateId": "a9ed-...-1234",
    "recipients": [
        {
            "addresseeType": "EMAIL",
            "value": "[email protected]"
        },
        {
            "addresseeType": "CONTACT_ID",
            "value": "a4b5-...-b4a6"
        }
    ],
    "consentIds": [
        "b2ab-...-2e1d",
        "e50e-...-a7ea"
    ],
    "dateTime": 1659928898000
}

Sample Response

{
    "conversationId": "e2db-...-e03f"
}

This method allows you to send Web Push notifications to selected Contacts who have granted consent via specified consent prompts. The method requires providing the notification template ID, a list of recipients (defined using Contact selectors), and the relevant consent prompt IDs. Optionally, you can schedule the notification by providing a UNIX timestamp; otherwise, the notification will be sent immediately.

Endpoint:

https://api.manago.ai/v3/webPush/send

Method:

POST

Body (JSON):

Field	Limits	Description
templateId^*	UUID	ID of the Web Push notification template to be sent. You can find it in the URL address of the template when editing it.
recipients^*	Array of objects	List of intended recipients of the notification. Refer to the Contact Selectors documentation.
consentIds^*	Array of UUID	Array of Web Push consent prompt IDs. Only Contacts who consented through the specified prompts will receive the Web Push notification. The prompts can be either website-based or browser-based. You can find their IDs in Menu → Channels → Web Push → Consent prompts, by expanding an item in the list using the arrow icon.
dateTime	UNIX timestamp [s]	Date and time when the Web Push notification should be sent. The default value is “now”. To schedule the notification for a later time, provide a UNIX timestamp (in seconds).

Response

Field	Description
conversationId	Identifier of the Web Push campaign.

List Web Push notification templates

Sample request:

https://api.manago.ai/v3/web/push/list?dateFrom=1559938888&dateTo=1659938888

Sample response:

{
    "notifications": [
        {
            "id": "1234-...-5678",
            "name": "Upsell campaign",
            "modifiedOn": 1559938888,
            "author": "[email protected]"
        },
        {
            "id": "8765-...-4321",
            "name": "Welcome new user",
            "modifiedOn": 1659938888,
            "author": "[email protected]"
        }
    ]
}

This method allows you to retrieve a list of Web Push notification templates created in Manago AI.
The response includes template IDs, which can be used in external systems to schedule the sending of notifications from Manago AI.

Endpoint:

https://api.manago.ai/v3/web/push/list

Method:

GET

Fields

Field	Limits	Description
dateFrom	UNIX timestamp [s]	Start date of the export time range. Templates are selected based on their last modification date.
dateTo	UNIX timestamp [s]	End date of the export time range. Templates are selected based on their last modification date.

Response

The response contains a maximum of 100 notification templates. If you expect that your export includes more than 100 templates, use the modifiedOn date of the last template in the array as the dateFrom value for the next export request.

Field	Description
id	Template ID from Manago AI.
name	Internal template name from Manago AI.
modifiedOn	Last modification date of the template.
author	Manago AI user who created the template.

Sent Web Push notification statistics

This method allows you to retrieve statistics on Web Push notifications sent via Manago AI. By specifying optional filtering parameters, such as sourceType (MASS, WORKFLOW, RULE) and sourceId, you can obtain data on a specific Web Push campaign. The response provides key metrics such as the number of notifications sent, displayed (basic and Rich), and clicked (basic and Rich) within a given time range (maximum 30 days). The results are exported in NDJSON format, and the download link is provided via webhook once the export file is ready.

Sample request:

{
  "sourceId": "9b1de7e3-b8e5-4a98-91cf-4f8c50b473bc",
  "sourceType": "MASS",
  "dateFrom": "2024-12-01",
  "dateTo": "2024-12-30"
}

Sample synchronous response:

{
  "success": true,
  "requestId": "d83a9b47-4f4e-441a-88f2-0bb7cb8dfd12",
  "message": ["Export added to queue. You will receive a webhook with the URL of file containing exported data.
    The webhook URL can be modified in Manago AI -> Integration Center -> API -> API v3 tab"]
}

Sample webhook response:

{
  "requestId": "d83a9b47-4f4e-441a-88f2-0bb7cb8dfd12",
  "fileUrl": "https://storage.googleapis.com/path/to/file/on/gcs"
}

Sample export file (NDJSON format) for MASS:

{"sourceId":"c34d97b1-ef7d-4c45-a12d-b44d54edba21","sourceType":"MASS","name":"Web Push example","sent":15,"displayedBasic":5,"displayedRich":3,"clickedBasic":1,"clickedRich":2,"sentOn":1736410477}
{"sourceId":"b44d54edba21-ef7d-4c45-a12d-c34d97b1","sourceType":"MASS","name":"Another Web Push example","sent":15,"displayedBasic":5,"displayedRich":3,"clickedBasic":1,"clickedRich":2,"sentOn":1736510977}

Sample export file (NDJSON format) for WORKFLOW/RULE:

{"sourceId":"123456","sourceType":"WORKFLOW","name":"Web Push from Workflow example","sent":15,"displayedBasic":5,"displayedRich":3,"clickedBasic":1,"clickedRich":2,"lastSentDate":1736410477}
{"sourceId":"557","sourceType":"WORKFLOW","name":"Workflow example","sent":170,"displayedBasic":5,"displayedRich":43,"clickedBasic":5,"clickedRich":32,"lastSentDate":1737619810}
{"sourceId":"1003732","sourceType":"WORKFLOW","name":"Workflow example","sent":20,"displayedBasic":10,"displayedRich":0,"clickedBasic":9,"clickedRich":0,"lastSentDate":1737544133}

Endpoint:

https://api.manago.ai/v3/webpush/stats

Method:

POST

Fields:

Field	Limits	Description
sourceId	UUID or integer	Optional filtering parameter. Include this parameter to obtain statistics only for a specific notification template. For MASS notifications: The UUID of the notification sending process. For WORKFLOW/RULE: The integer identifier of the Workflow/Automation Rule (included in the URL).
sourceType	ENUM	Optional filtering parameter. The sending method for which statistics are to be returned. The following values are supported: MASS, RULE, WORKFLOW. This field is required when sourceId is provided.
dateFrom*	UNIX timestamp or YYYY-MM-DD	Start and end date for the statistics. The maximum allowed time range is 30 days. The UNIX timestamp is rounded to the beginning of a given day (dateFrom is inclusive, whereas dateTo is exclusive).
dateTo*	UNOX timestamp or YYYY-MM-DD

IMPORTANT: The URL of the export file included in the webhook response is valid for 10 minutes only.

Export file contents:

Field	Description
sourceId	MASS source: Notification sending process ID WORKFLOW source: Workflow ID RULE source: Automation Rule ID
sourceType	Notification sending method (MASS, WORKFLOW, or RULE)
name	MASS source: Web Push template name WORKFLOW source: Workflow name RULE source: Automation Rule name
sent	Number of Web Push notifications sent in the specified time period
displayedBasic	Number of basic Web Push notifications displayed in the specified time period
displayedRich	Number of Rich Web Push notifications displayed in the specified time period
clickedBasic	Number of basic Web Push notifications clicked in the specified time period
clickedRich	Number of Rich Web Push notifications clicked in the specified time period
sentOn	MASS source only: Scheduled sending date
lastSentDate	WORKFLOW/RULE sources only: Date of the most recently sent Web Push notification. Important: This value can be outside of the requested time range.

Export of sent Web Push notification data

This method allows you to retrieve data on Web Push notifications sent via Manago AI. By specifying optional filtering parameters such as sourceType (MASS, WORKFLOW, RULE) and sourceId, you can obtain data on a specific notification or campaign. The response includes key details for each individual notification sent within a given date range (maximum 30 days). The results are exported in NDJSON format, and the download link is provided via webhook once the export is ready.

Sample request:

{
  "sourceId": "9b1de7e3-b8e5-4a98-91cf-4f8c50b473bc",
  "sourceType": "MASS",
  "dateFrom": "2024-12-01",
  "dateTo": "2024-12-30"
}

Sample synchronous response:

{
  "success": true,
  "requestId": "d83a9b47-4f4e-441a-88f2-0bb7cb8dfd12",
  "message": ["Export added to queue. You will receive a webhook with the URL of file containing exported data.
    The webhook URL can be modified in Manago AI -> Integration Center -> API -> API v3 tab"]
}

Sample webhook response:

{
  "requestId": "d83a9b47-4f4e-441a-88f2-0bb7cb8dfd12",
  "fileUrl": "https://storage.googleapis.com/path/to/file/on/gcs"
}

Sample export file (NDJSON format):

{"contactAnonymousId":"4f8c51e6-7a3f-4d1e-b5d3-019d88fa9d5b","sourceId":"f98a7e62-b8d4-4a3d-8a61-48b3f01a6b1d","status":"Sent","sentOn":1736410533,"displayedOn":1736411533,"clickedOn":1736411933,"sourceType":"MASS","contactId":"123e4567-e89b-12d3-a456-426614174000","email":"[email protected]","externalId":"ABC123"}
{"contactAnonymousId":"4f8c51e6-7a3f-4d1e-b5d3-019d88fa9d5b","sourceId":"f98a7e62-b8d4-4a3d-8a61-48b3f01a6b1d","status":"Sent","sentOn":1736410533,"displayedOn":1736411533,"clickedOn":1736411933,"sourceType":"MASS","contactId":"123e4567-e89b-12d3-a456-426614174001","email":"[email protected]","externalId":"DEF456"}

Endpoint:

https://api.manago.ai/v3/webpush/data

Method:

POST

Fields:

Field	Limits	Description
sourceId	UUID or integer	Optional filtering parameter. Include this parameter to obtain statistics only for a specific notification template. For MASS notifications: The UUID of the notification sending process. For WORKFLOW/RULE: The integer identifier of the Workflow/Automation Rule (included in the URL).
sourceType	ENUM	Optional filtering parameter. The sending method for which statistics are to be returned. The following values are supported: MASS, RULE, WORKFLOW. This field is required when sourceId is provided.
dateFrom*	UNIX timestamp or YYYY-MM-DD	Start and end date for the statistics. The maximum allowed time range is 30 days. The UNIX timestamp is rounded to the beginning of a given day (dateFrom is inclusive, whereas dateTo is exclusive).
dateTo*	UNOX timestamp or YYYY-MM-DD

IMPORTANT: The URL of the export file included in the webhook response is valid for 10 minutes only.

Export file contents:

Field	Description
sourceId	Source identifier
sourceType	Notification sending method (MASS, WORKFLOW, or RULE)
status	Web Push notification status (Currently, only Sent status)
sentOn	Date when the Web Push notification was sent
displayedOn	Date when the Web Push notification was displayed (or null if never displayed)
clickedOn	Date when the Web Push notification was clicked (or null if never displayed)
contactAnonymousId	Anonymous identifier (smuuid) of the WebPush recipient
contactId	Contact identifier from Manago AI. This field is present only for recipients who are monitored Contacts
email	Contact’s email address. This field is present only for recipients who are monitored Contacts
externalId	Contact’s external ID. This field is present only for recipients who are monitored Contacts

Sample request:

https://api.manago.ai/v3/web/push/consent/list?dateFrom=1559938888&dateTo=1659938888

Sample response:

{
    "consents": [
        {
            "id": "1234-...-5678",
            "name": "Home page - Marketing",
            "modifiedOn": 1559938888,
            "author": "[email protected]"
        },
        {
            "id": "8765-...-4321",
            "name": "Price Drop alerts",
            "modifiedOn": 1659938888,
            "author": "[email protected]"
        }
    ]
}

This method allows you to retrieve a list of Web Push consent prompts created in Manago AI (both website-based and browser-based). The response includes consent IDs, which can be used in external systems to schedule the sending of notifications from Manago AI.

Endpoint:

https://api.manago.ai/v3/web/push/consent/list

Method:

GET

Fields

Field	Limits	Description
dateFrom	UNIX timestamp [s]	Start date of the export time range. Consent prompts are selected based on their last modification date.
dateTo	UNIX timestamp [s]	End date of the export time range. Consent prompts are selected based on their last modification date.

Response

The response contains a maximum of 100 consent prompts. If you expect your export to include more than 100 consent prompts, use the modifiedOn date of the last consent prompt in the array as the dateFrom value for the next export request. If no dates are specified, the response includes the 100 most recently modified consent prompts.

Field	Description
id	Consent prompt ID from Manago AI.
name	Internal consent prompt name from Manago AI.
modifiedOn	Last modification date of the consent prompt.
author	Manago AI user who created the consent prompt.

Mobile Push

List Mobile Push notification templates

Sample request:

https://api.manago.ai/v3/mobile/push/template/list?dateFrom=1559938888&dateTo=1659938888&type=IN_APP&ids=1234-...-5678&ids=1234-...-9876&content=true

Sample response:

{
    "notifications": [
        {
            "id": "1234-...-5678",
            "name": "Upsell campaign",
            "type": "IN_APP",
            "modifiedOn": 1559938888,
            "author": "[email protected]",
            "system": ["ANDROID"]
        },
        {
            "id": "3789-...-4321",
            "name": "Welcome new user",
            "type": "IN_APP",
            "modifiedOn": 1659938888,
            "author": "[email protected]",
            "system": ["ANDROID", "IOS"]
        },
        {
            "id": "8765-...-98761",
            "name": "Welcome new subscriber",
            "type": "STATIC",
            "modifiedOn": 1659938888,
            "author": "[email protected]",
            "system": ["ANDROID","IOS"],
            "subject": "Welocme to Example.com!",
            "content": "We have a special offer for new subscribers! Enjoy 15% off for your next order with the code NEW15"
        }
    ]
}

This method allows you to retrieve a list of Mobile Push and/or In-App notification templates created in Manago AI. The response includes template IDs, which can be used in external systems to schedule the sending of notifications from Manago AI.

Endpoint:

https://api.manago.ai/v3/mobile/push/template/list

Method:

GET

Fields

Field	Limits	Description
dateFrom^*	UNIX timestamp [s]	Start date of the export time range. Templates are selected based on their last modification date.
dateTo^*	UNIX timestamp [s]	End date of the export time range. Templates are selected based on their last modification date.
type	Enum	Optional filtering parameter, accepting the following values: - IN_APP - returns only In-App templates. - DYNAMIC - returns only dynamic (personalized) Mobile Push templates. - STATIC - returns only static (non-personalized) Mobile Push templates. If not specified, all template types are returned by default.
ids	100 x UUID	Array of template IDs
content	boolean	A flag that determines whether to return the subject and content of the notification. The default value is false. The response returns subject and content for STATIC and DYNAMIC Push Notifications only (IN_APP and COMBO are always excluded).

Response

The response contains a maximum of 100 notification templates. If you expect that your export includes more than 100 templates, use the modifiedOn date of the last template in the array as the dateFrom value for the next export request.

Field	Description
id	Template ID from Manago AI.
name	Internal template name from Manago AI.
type	Template type: - IN_APP - In-App template. - DYNAMIC - Dynamic (personalized) Mobile Push. - STATIC - Static (non-personalized) Mobile Push template.
modifiedOn	Last modification date of the template.
author	Manago AI user who created the template.
system	Array of mobile operating system(s) for which the template is intended (“IOS”, “ANDROID”).
subject	Subject of the Push Notification
content	Content of the Push Notification

Send Mobile Push notification

Sample request:

{
    "templateId": "abcd-....1234",
    "recipients": [
        {
            "addresseeType": "EMAIL",
            "value": "[email protected]",
            "contentBoxes": {
                "conference_name": "Global Innovations Summit",
                "start_time": "11:00"
            }
        },
        {
            "addresseeType": "CONTACT_ID",
            "value": "a1b2-....c3d4",
            "contentBoxes": {
                "conference_name": "Global Innovations Summit"
            }
        }
    ],
    "allDevices": false,
    "expirationValue": 48,
    "dateTime": 1659938880000
}

Sample response

HTTP: 200

This method allows you to send Mobile Push notifications to selected recipients. It requires providing a notification template ID and a list of recipients (defined using Contact selectors). Optionally, you can specify whether the notification should be sent to all devices or only the device most recently used by the Contact. You can also define the sending time and the TTL (notification expiration time).

Endpoint:

https://api.manago.ai/v3/mobile/push/send

Method:

POST

Fields

Field	Limits	Description
templateId^*	UUID	ID of the Mobile Push notification template to be sent. You can find it in the URL address of the template when editing it.
recipients^*	Array of objects	List of intended recipients of the notification. Refer to the Contact Selectors documentation.
contentBoxes	Object (key-value map)	A map of content box keys and their values used to replace placeholders in the template. Keys correspond to placeholders defined in the template using `{{context_box:example}}` syntax. If a key is missing in the request, the default value from the template is used. If no default value is defined, an empty value is inserted.
allDevices	Bool	Flag indicating whether the notification should be sent to all devices associated with the Contact or only to the most recently used device. The default value is `false` (only the most recently used device).
dateTime	UNIX timestamp [seconds]	Date and time when the Mobile Push notification should be sent. The default value is “now”. To schedule the notification for a later time, provide a UNIX timestamp (in seconds).
expirationValue	1-672	TTL (time-to-live) of the notification in hours after the specified `dateTime`. After this time, the notification will expire and be ignored by the recipient’s device. Default: 24.

Response:

(no content)

List Mobile Push mass conversations

Sample request:

https://api.manago.ai/v3/mobile/push/conversation/list?dateFrom=1559938888&dateTo=1659938888&notificationId=0461-...-2edc

Sample response:

{
  "conversations": [
    {
      "id": "7b15-...-d477",
      "name": "simple campaign",
      "notificationId": "0461-...-2edc",
      "notificationType": "STATIC",
      "system": [
        "IOS",
        "ANDROID"
      ],
      "sentOn": 1771853530,
      "author": "[email protected]",
      "ttl": 86400,
      "status": "DONE"
    },
    {
      "id": "7549-...-5533",
      "name": "different campaign example",
      "notificationId": "0461-...-2edc",
      "notificationType": "STATIC",
      "system": [
        "IOS",
        "ANDROID"
      ],
      "sentOn": 1771851486,
      "author": "[email protected]",
      "ttl": 86400,
      "status": "DONE"
    }
  ]
}

This method allows you to retrieve a list of Mobile Push and/or In-App conversations created in Manago AI. The response includes conversation IDs, which can be used by external systems to get statistics.

Endpoint:

https://api.manago.ai/v3/mobile/push/conversation/list

Method:

GET

Fields:

Field	Limits	Description
dateFrom*	UNIX timestamp [s]	Start date of the export time range. Templates are selected based on their sentOn date.
dateTo*	UNIX timestamp [s]	End date of the export time range. Templates are selected based on their sentOn date.
notificationId	UUID	Optional filtering parameter

Response:

The response contains a maximum of 100 conversations. If you expect your export to include more than 100 conversations, use the sentOn date of the last template in the array as the dateFrom value for the next export request.

Field	Description
id	Unique identifier of the given conversation in UUID format
name	Internal name assigned to the given conversation
notificationId	ID of the template
notificationType	Specifies the type of notification used in the conversation: Returns values like: • STATIC • DYNAMIC • IN_APP • COMBO
system	List of operating systems to which the message was sent. Returns values like: • ANDROID • IOS
sentOn	Time and date the message was sent on (UNIX timestamp)
author	Email address of the author or creator of the conversation
ttl	Message Time to Live, specified in seconds.
status	Current status of the message execution or sending in the conversation. Returns values like: • CREATED • DELETED • READY • SCHEDULING • INCOMPLETE • DONE • OTHER

Get Mobile Push mass conversations statistics

Sample request:

https://api.manago.ai/v3/mobile/push/conversation/stat?conversationIds=6baf-...-0e97&conversationIds=d4a1-...-016e

Sample response:

{
  "conversationsStat": [
    {
      "conversationId": "6baf-...-0e97",
      "sentOn": 1772782103,
      "scheduled": 3079,
      "sent": 33,
      "viewed": 1,
      "clicked": 1,
      "cancelled": 0,
      "failed": 3046
    },
    {
      "conversationId": "d4a1-...-016e",
      "sentOn": 1776860940,
      "scheduled": 3069,
      "sent": 28,
      "viewed": 0,
      "clicked": 0,
      "cancelled": 0,
      "failed": 3041
    }
  ]
}

This method allows you to retrieve a list of Mobile Push and/or In-App conversations statistics.

Endpoint:

https://api.manago.ai/v3/mobile/push/conversation/stat

Method:

GET

Fields:

Field	Limits	Description
conversationIds	Array of UUID	Max 100 UUID

Response:

Field	Description
conversationId	Unique identifier of the conversation in UUID format to which the statistics apply.
sentOn	Date and time of sending (UNIX timestamp)
scheduled	Number of messages scheduled to be sent within this conversation
sent	Number of messages that were successfully sent
viewed	Number of messages that were displayed or opened by recipients
clicked	Number of clicks on links contained in the messages by recipients
cancelled	Number of messages that were canceled before being sent
failed	Number of messages that failed to be sent

Get statistics for Mobile Push notification template(s)

Sample Request:

https://api.manago.ai/v3/mobile/push/list/stat?notificationIds=a1b2-...-c3d4&notificationIds=e5f6-...-a1b2

Sample Response:

{
  "notificationsStat": [
    {
      "notificationId": "a1b2-c3d4",
      "lastSentOn": 1659938888,
      "sent": 34567,
      "viewed": 23456,
      "clicked": 12345,
      "failed": 2
    },
    {
      "notificationId": "e5f6-...-a1b2",
      "lastSentOn": 1699958888,
      "sent": 45678,
      "viewed": 5678,
      "clicked": 678,
      "failed": 3
    }
  ]
}

This method allows you to retrieve statistics for Mobile Push campaigns based on specified notification template(s) created in and sent via Manago AI. You can filter the results to include only campaigns sent through one or more specified sending methods (source). The response includes key metrics, such as the number of notifications sent, viewed, and clicked. The data is returned synchronously in JSON format.

Endpoint:

https://api.manago.ai/v3/mobile/push/list/stat

Method:

GET

Fields

Field	Limits	Description
notificationIds	100 x UUID	Array of Mobile Push template IDs. The template ID can be found in the URL when editing a template.
dateFrom	UNIX timestamp [s]	Time range of the export. If no dates are specified, the data is returned from the earliest available record up to the present moment. If you specify the dates, the maximum time span is 365 days.
dateTo	UNIX timestamp [s]	Time range of the export.
source	Enum	Optional filtering by source. Allowed values: MASS WORKFLOW API . The default (empty) value includes all sources.

Response

Field	Description
notificationId	Template ID from Manago AI.
lastSentOn	UNIX timestamp [s] of the most recent time the template was sent.
sent	Total number of Mobile Push notifications successfully sent.
viewed	Number of sent notifications that were delivered and opened (viewed) on recipients’ devices.
clicked	Number of notifications where recipients clicked an action button or a link.
failed	Number of notifications that failed to be sent due to errors (e.g., invalid tokens, unreachable devices).

List WhatsApp templates

Sample request (GET example):

https://api.manago.ai/v3/whatsapp/template/list?type=META_APPROVED&dateFrom=1777286680&dateTo=1778152786&channelId=1234&lang=es_MX&status=PAUSED

Sample response:

{
  "templates": [
    {
      "id": "3fa8-...-afa6",
      "name": "promo_template",
      "channelId": "channel-1",
      "lang": "es_MX",
      "category": "MARKETING",
      "status": "APPROVED",
      "type": "META_APPROVED",
      "modifiedOn": 1711000000
    }
  ]
}

This method returns a list of WhatsApp templates. If no parameter is provided, it returns 100 newest templates.

Endpoint:

https://api.manago.ai/v3/whatsapp/template/list

Method:

GET

Fields:

Field	Limits	Description
channelId	50	Optional. ID of the channel. You can list available channels using the /whatsapp/channel/list method.
dateFrom	UNIX timestamp [s]	Optional. Start date of the export time range. Templates are selected based on their last modification date.
dateTo	UNIX timestamp [s]	Optional. End date of the export time range. Templates are selected based on their last modification date.
type	Enum: META_APPROVED, SESSION	Optional. Type of the template.
lang	Enum	Optional. Language of the template. Allowed values: af, sq, ar, az, bn, bg, ca, zh_CN, zh_HK, zh_TW, hr, cs, da, nl, en, en_GB, en_US, et, fil, fi, fr, ka, de, el, gu, ha, he, hi, hu, id, ga, it, ja, kn, kk, rw_RW, ko, ky_KG, lo, lv, lt, mk, ms, ml, mr, nb, fa, pl, pt_BR, pt_PT, pa, ro, ru, sr, sk, sl, es, es_AR, es_ES, es_MX, sw, sv, ta, te, th, tr, uk, ur, uz, vi, zu.
status	Enum: PENDING, APPROVED, REJECTED, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION, LIMIT_EXCEEDED, CREATED	Optional. Status of the template.

Response:

Field	Description
id	Template ID from Manago AI.
name	Internal template name from Manago AI.
channelId	ID of the channel.
modifiedOn	Last modification date of the template as a UNIX timestamp [s].
lang	Language of the template.
category	Category of the template.
status	Status of the template.
type	Type of the template.

Get WhatsApp template statistics

Sample request (GET example):

https://api.manago.ai/v3/whatsapp/template/stat?templateIds=3997-...-72e7&dateFrom=1777286680&dateTo=1778152786&source=WORKFLOW

Sample response:

{
  "templatesStat": [
    {
      "templateId": "3fa8-...-afa6",
      "lastSentOn": 1711200000,
      "sent": 1000,
      "delivered": 970,
      "viewed": 700,
      "clicked": 120,
      "responded": 80,
      "respondedAll": 95,
      "failedMeta": 20,
      "failedInternal": 10
    }
  ]
}

This method returns a list of WhatsApp template statistics

Endpoint:

https://api.manago.ai/v3/whatsapp/template/stat

Method:

GET

Fields:

Field	Limits	Description
templateIds*	100 x UUID	ID of the template.
dateFrom	UNIX timestamp [s]	Start date of the export time range. Templates are selected based on their last modification date.
dateTo	UNIX timestamp [s]	End date of the export time range. Templates are selected based on their last modification date.
source	Enum: MASS, WORKFLOW, API	Optional filtering parameter. When provided, the response contains statistics only for the specified sending origin.

Response:

Field	Description
templateId	Template ID from Manago AI.
lastSentOn	Date the template was last sent, or `null` if it was never sent.
sent	Number of messages sent.
delivered	Number of messages delivered.
viewed	Number of messages viewed.
clicked	Number of messages clicked.
responded	Number of messages that received a response.
respondedAll	Aggregated number of all individual responses.
failedMeta	Number of messages failed by Meta.
failedInternal	Number of messages failed due to internal causes.

List WhatsApp mass conversations

Sample request:

https://api.manago.ai/v3/whatsapp/conversation/list?dateFrom=1777286680&dateTo=1778152786&channelIds=channel&templateId=6ba2-...-8fe2

Sample response:

{
  "conversations": [
    {
      "id": "0c2d-...-f7a1",
      "name": "Spring Promo 2026",
      "channelId": "channel-1",
      "templateId": "3fa856f4-5717-4562-b3fc-2c963f66afa6",
      "sentOn": 1711300000
    }
  ]
}

This method allows you to retrieve a list of WhatsApp conversations created in Manago AI. The response includes conversation IDs, which can be used by external systems to get statistics.

Endpoint:

https://api.manago.ai/v3/whatsapp/conversation/list

Method:

GET

Fields:

Field	Limits	Description
dateFrom*	UNIX timestamp [s]	Start date of the export time range. Templates are selected based on their sentOn date.
dateTo*	UNIX timestamp [s]	End date of the export time range. Templates are selected based on their sentOn date.
templateId	UUID	Optional filtering parameter
channelIds	Array of channel ids	Whatsapp channel ids

Response:

The response contains a maximum of 100 conversations. If you expect that your export includes more than 100 conversations, use the sentOn date of the last template in the array as the dateFrom value for the next export request.

Field	Description
id	Unique conversation ID (UUID)
name	Internal name from Manago AI of the conversation
channelId	ID of the channel
templateId	ID of the template
sentOn	Time and date of sending (UNIX timestamp)

Get Whatsapp mass conversations stats

Sample request:

https://api.manago.ai/v3/whatsapp/conversation/stat?conversationIds=a1b2-...-c3d4&conversationIds=d4c3-...-b2a1

Sample response:

{
  "conversationsStat": [
    {
      "conversationId": "a1b2-...-c3d4",
      "sentOn": 1711300000,
      "scheduled": 1000,
      "sent": 995,
      "delivered": 970,
      "viewed": 710,
      "clicked": 130,
      "responded": 85,
      "respondedAll": 96,
      "failedMeta": 15,
      "failedInternal": 10,
      "creditsUsed": 995
    },
    {
      "conversationId": "d4c3-...-b2a1",
      "sentOn": 1811300000,
      "scheduled": 2000,
      "sent": 1995,
      "delivered": 1970,
      "viewed": 1710,
      "clicked": 530,
      "responded": 185,
      "respondedAll": 196,
      "failedMeta": 15,
      "failedInternal": 0,
      "creditsUsed": 1995
    }
  ]
}

This method allows you to retrieve a list of Whatsapp conversations statistics.

Endpoint:

https://api.manago.ai/v3/whatsapp/conversation/stat

Method:

GET

Fields:

Field	Limits	Description
conversationIds*	Array of UUID	Max 100 UUID

Response:

The response contains a maximum of 100 conversations. If you expect that your export includes more than 100 conversations, use the modifiedOn date of the last template in the array as the dateFrom value for the next export request.

Field	Description
conversationId	Unique conversation ID (UUID)
sentOn	Time and date of sending (UNIX timestamp)
scheduled	Number of scheduled messages
sent	Number of messages sent
delivered	Number of messages delivered
viewed	Number of messages viewed
clicked	Number of messages clicked
responded	Number of messages that recieved a response
respondedAll	Aggregated number of all individual responses
failedMeta	Number of messages failed by Meta
failedInternal	Number of messages failed due to internal causes
creditsUsed	Number of credits used for this conversation

List WhatsApp channels

This method returns a list of all WhatsApp channels.

Sample request (GET example):

https://api.manago.ai/v3/whatsapp/channel/list

Sample response:

{
  "channels": [
    {
      "id": "abcd1234",
      "name": "Example internal name",
      "businessName": "Example Studio",
      "status": "APPROVED",
      "pendingDeletionAt": 1780271999,
      "modifiedOn": 1779865655
    }
  ]
}

Endpoint:

https://api.manago.ai/v3/whatsapp/channel/list

Method:

GET

Fields:

This method expects no parameters

Response:

Field	Description
id	Channel ID from Manago AI
name	Internal channel name from Manago AI
businessName	External channel name from Meta. Visible as the sender to the message recipients.
status	Status of the WhatsApp channel. ENUM field, allowed values: - ACTIVE - DISCONNECTED - PENDING - FAILED - DELETED
pendingDeletionAt	Channel cancellation time. Present when the channel has been canceled/disconnected, otherwise null.
modifiedOn	Last modification date of the channel

Send WhatsApp marketing message

This method allows you to send Meta-approved template messages

Sample request (POST example):

https://api.manago.ai/v3/whatsapp/send

Sample payload:

{
  "templateId": "metaTemplateId",
  "recipients": [
    {
      "addresseeType": "TAG",
      "value": "EXAMPLE_TAG"
    }
  ],
  "dateTime": "1779865655",
  "defaultPrefix": "+34"
}

Sample response:

HTTP: 200

Endpoint:

https://api.manago.ai/v3/whatsapp/send

Method:

POST

Fields:

Field	Limits	Description
templateId*	255	ID of the template from Meta
recipients*	Array[100]	List of intended recipients of the message. Refer to the Contact Selectors documentation.
dateTime	UNIX timestamp [s]	Date and time when the WhatsApp message should be sent. The default value is “now”. To schedule the message for a later time, provide a UNIX timestamp (in seconds).
defaultPrefix*	String Pattern: ^\+\d{1,4}$	Default phone prefix in international format. Must start with a + sign followed by 1 to 4 digits (e.g. +1, +44, +420).

Response:

(no content)

Send WhatsApp session message

This method allows you to send session template messages within the Meta’s 24h window rule.

Sample request (POST example):

https://api.manago.ai/v3/whatsapp/session/send

Sample payload:

{
  "templateId": "metaTemplateId",
  "recipient": {
    "addresseeType": "CONTACT",
    "value": "[email protected]"
  },
  "dateTime": "1779865655",
  "defaultPrefix": "+48"
}

Sample response:

HTTP: 200

Endpoint:

https://api.manago.ai/v3/whatsapp/session/send

Method:

POST

Fields:

Field	Limits	Description
templateId*	255	ID of the template from Meta
recipient*	Object	Intended recipient of the message. Refer to the Contact Selectors documentation. Only one recipient must be provided. Supported addresseeTypes: • CONTACT_ID • EMAIL • USER_ID
dateTime	UNIX timestamp [s]	Date and time when the WhatsApp message should be sent. The default value is “now”. To schedule the message for a later time, provide a UNIX timestamp (in seconds).
defaultPrefix*	String Pattern: ^\+\d{1,4}$	Default phone prefix in international format. Must start with a + sign followed by 1 to 4 digits (e.g. +48, +1, +420).

Response:

(no content)

Product Management

Creating a Product Catalog

Sample request:

{
  "catalogName": "Example.com Product Catalog",
  "setAsDefault": true,
  "currency": "USD",
  "location": "examplecom"
}

Sample request with currency formatting:

{
    "catalogName": "Example.com Product Catalog",
    "setAsDefault": true,
    "currency": "EUR",
    "currencyFormat": {
        "currencyCode": "EUR",
        "decimalPlaces": 2,
        "decimalSeparator": "COMMA",
        "thousandSeparator": "SPACE",
        "displayIdentifier": "SYMBOL",
        "identifierPosition": "AFTER_WITH_SPACE"
    },
    "location": "examplecom"
}

Sample response:

{
  "catalogId": "21c2-...-3266",
  "message":[]
}

This method lets you create a Product Catalog – an entity representing your online store. Product Catalogs are crucial for many functionalities in Manago AI, including Recommendation Frames, emails with product blocks, dynamic WebPushes, and more.

To maintain backwards compatibility with XML Product Feeds, you need to specify a location field when creating a new Product Catalog. This field is used when assigning external events (such as CART or PURCHASE) to a proper Product Catalog.

Some properties of Product Catalogs can be updated, including catalog name, currency, or location. To identify a Product Catalog, use the catalogId value. You can always check the catalogId value in Manago AI ➔ Integration Center ➔ Product Catalogs.

Endpoint:

https://api.manago.ai/v3/product/catalogUpsert

Method:

POST

Body (JSON):

Field	Limits	Description
catalogName*	64	Internal name of the Product Catalog to help you identify it in Manago AI. Allowed characters: `a‑zA‑Z0‑9 and _`
catalogId	36	Catalog identifier that is used to update an existing catalog. Do not specify when creating a new one.
setAsDefault	bool	Flag used to determine if Product Catalog should be available for Recommendation Frames
active	bool	Flag used to activate/deactivate the Catalog. By default, all Product Catalogs are active.
currency*	ISO 4217	ISO currency code, e.g. USD, EUR, etc.
currencyFormat	-	Object containing currency formatting configuration.
currencyCode+	ISO 4217	Three-letter currency code
decimalPlaces+	Integer (0-2)	Number of decimal places (0, 1, or 2)
decimalSeparator+	Enum	Character used to separate the decimal part. Allowed values: COMMA DOT
thousandSeparator+	Enum	Character used to separate thousand groups. Allowed values: SPACE THIN_SPACE (Unicode \u2009) COMMA DOT APOSTROPHE NONE (groups will not be separated)
displayIdentifier+	Enum	Type of currency display. Allowed values: SYMBOL – Will display currency symbol, e.g.. € CODE – will display currency code, e.g. EUR
identifierPosition+	Enum	Currency position relative to the value: BEFORE (e.g. $100) BEFORE_WITH_SPACE (e.g. $ 100) AFTER (e.g. 100€) AFTER_WITH_SPACE (e.g. 100 €)
customSymbol	12	Optional field to overwrite the default currency symbol. Digits are not allowed.
location*	255 only a-zA-Z0-9_ cannot start with a digit	Legacy field for assigning products to External Events.

+ Fields marked with a plus sign are mandatory when the currencyFormat object is present.

Listing Product Catalogs

This method lets you get a list of all Product Catalogs created in Manago AI as well as the maximum number of Product Catalogs that can be created on your account.

Endpoint:

https://api.manago.ai/v3/product/catalogList

Method:

GET

Request parameters:

This GET method expects no additional parameters.

Response:

Field	Description
problems	Array of additional information, including error messages
catalogId	Unique identifier of the Product Catalog, required when adding products to Catalog
setAsDefault	Flag specifying if the Product catalog can be used in recommendations (true) or analytics only (false)
currency	Currency as specified during Catalog creation
location	Location field used to match the External Event with Product Catalog
max	Total maximum number of Product Catalogs that can be created on your account.

Sample response:

{
  "catalogs": [
    {
      "catalogId": "21c2-...-3266",
      "name": "Example.com Product Catalog",
      "setAsDefault": false,
      "currency": "USD",
      "location": "examplecom"
    },
    {
      "catalogId": "a2d4-...-f0e3",
      "name": "Online Store Catalog",
      "setAsDefault": true,
      "currency": "EUR",
      "location": "myonlinestore"
    }
  ],
  "limits": {
    "max": 3
  }
}

Deleting a Product Catalog

Sample request:

{
  "catalogId": "21c2-...-3266"
}

This method allows you to delete a Product Catalog created in Manago AI, along with all products it contains. This action is irreversible.

Endpoint:

https://api.manago.ai/v3/product/catalogDelete

Method:

POST

Body (JSON):

Field	Limits	Description
catalogId*	UUID	Unique identifier of the Product Catalog to be deleted

Response

Field	Description
catalogId*	Unique identifier of the deleted Product Catalog

Sample response:

{
  "catalogId": "21c2-...-3266",
  "message": []
}

Adding or updating a product

Sample request:

{
  "catalogId": "21c2-...-3266",
  "products": [
    {
      "productId": "1234",
      "name": "Turtleneck sweater",
      "mainCategory": "sweaters",
      "categoryExternalId": "8642",
      "description": "Classic sweater with...",
      "productUrl": "https://example.com/shop/sweaters/turtleneck-sweater",
      "mainImageUrl": "https://example.com/media/turtleneck-sweater-cover.jpg",
      "available": true,
      "price": 79.99,
      "systemDetails": {
        "manufacturer": "My Brand",
        "gender": 0,
        "color": "black"
      }
    },
    {
      "productId": "1235",
      "name": "White t-shirt",
      "mainCategory": "t-shirts",
      "categoryExternalId": "1050",
      "categories": [
        "Winter collection",
        "Linen products"
      ],
      "description": "Classic t-shirt with...",
      "productUrl": "https://example.com/shop/t-shirts/white-t-shirt",
      "mainImageUrl": "https://example.com/media/white-t-shirt-cover.jpg",
      "imageUrls": [
        "https://example.com/media/white-t-shirt1.jpg",
        "https://example.com/media/white-t-shirt2.jpg",
        "https://example.com/media/white-t-shirt3.jpg"
      ],
      "available": true,
      "active": true,
      "quantity": 90,
      "price": 29.99,
      "discountPrice": 19.99,
      "unitPrice": 19.99,
      "systemDetails": {
        "brand": "My Brand",
        "manufacturer": "My Brand",
        "popularity": 40,
        "gender": 0,
        "season": "summer",
        "color": "white",
        "bestseller": true,
        "newProduct": false
      },
      "customDetails": {
        "detail1": "linen",
        "detail2": "short"
      },
      "setAsNull": [
        "detail1",
        "detail2",
        "detail3",
        "detail4",
        "detail5",
        "discountPrice"
      ]
    }
  ]
}

This method lets you add or update products in a Product Catalog. In Manago AI products are identified by the field productId. This can be the product ID from your eCommerce platform, the SKU or EAN code. This field is unique per product.

You can upload product variants if they meet both of the following conditions: 1. Product variant has its own productId. 2. Product variant has its own URL.

Endpoint:

https://api.manago.ai/v3/product/upsert

Method:

POST

Body (JSON):

Field	Limits	Description
catalogId*	36	Catalog identifier that is used to identify the Product Catalog for the upserted product
products*	100 You can transfer up to 100 products in one request.	Array of product objects with fields specified below
productId*	32	Product identifier from your eCommerce platform
name*	255	Product name. You can use diacritics and special characters.
mainCategory*	255	Category name that can be used in emails and when displaying Recommendation Frames
categoryExternalId	255	Category ID used for AI processing and calculating recommendations. If you don’t specify this field, the category ID will be assigned based on the mainCategory field.
categories	512 (total characters)	Other categories (array)
description	4096 Most functionalities can use the first 4096 characters only	Product description used in emails and custom Recommendation Frames. Most functionalities can use the first 4096 characters only.
productUrl*	2048 Most functionalities can use the first 512 characters only	Product URL that is used to match visits with products. Most functionalities can use the first 512 characters only.
mainImageUrl	2048 Most functionalities can use the first 512 characters only	Image URL to be used in Recommendation Frames and emails. Most functionalities can use the first 512 characters only.
imageUrls	5*2048	Additional product images that will be used in upcoming features
available*	bool	Marks products as temporarily unavailable. This allows you to prevent them from showing up in Recommendation Frames.
active	bool	Marks products as no longer present in your store. This will effectively turn off a given product.
quantity	int	Available quantity to be used in custom Recommendation Frames
price*	float (19.2) This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point	Standard product price
discountPrice	float (19.2) This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point	Discount product price. You can use this value to display product promo price next to a crossed out standard product price in emails and Recommendation Frames.
systemDetails	n/a	Set of details that can be used in various mechanisms in Manago AI
brand	text(255)	Standard product details
manufacturer	varchar(100)	Standard product details
season	varchar(40)	Standard product details
color	varchar(40)	Standard product details
popularity	int(max 100)	Integer value to mark how popular the upserted product is, for example, using a range 1-100.
bestseller	bool	Flags that you can use in emails and custom Recommendation Frames
newProduct	bool	Flags that you can use in emails and custom Recommendation Frames
gender (systemDetails object)	enum (-1, 0, 1, 2, 3, 4)	Enum to identify the gender the product is designed for: -1 – undefined, 0 – female, 1 – male, 2 – other, 4 – unisex
customDetails (object)	5*255	List of additional details as key-value pairs. Note: You can use custom key names (instead of detailX), however, some functionalities will still refer to those values using a key detailX.
setAsNull	Array	Array of product parameters to be set as null (meaning their values will be cleared). The following parameters can be set as null: `detail1`, `detail2`, `detail3`, `detail4`, `detail5`, and `discountPrice`. If you specify the value of a parameter and set this value as null in a single request, the value will be set as null.

Sample response:

{
  "requestId": "381d-...-12e7",
  "productIds": ["1234", "1235"]
}

Updating product price

You can update the price and discount price for products previously added to a Product Catalog.

Sample request:

{
  "catalogId": "21c2-...-3266",
  "products": [
    {
      "productId": "1234",
      "price": 199.99,
      "discountPrice": 149.99
    }
  ]
}

Endpoint:

https://api.manago.ai/v3/product/updatePrice

Method:

POST

Body (JSON):

Field	Limits	Description
catalogId	UUID	UUID of a Product Catalog. You can find it in Manago AI ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Catalog is created using the product/catalogUpsert method.
productId	255	Product identifier from your eCommerce platform
price	float (19.2) This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point	Standard product price
discountPrice	float (19.2) This value can contain up to 19 digits before the decimal point and 2 digits after the decimal point	Discount product price. You can use this value to display product promo price next to a crossed out standard product price in emails and Recommendation Frames.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
problems	Array of additional information, including error messages

Sample response:

{
  "success": true
}

Updating product stock

You can update the stock (quantity) for products previously added to a Product Catalog.

Sample request:

{
  "catalogId": "21c2-...-3266",
  "products": [
    {
      "productId": "1234",
      "quantity": 300
    }
  ]
}

Endpoint:

https://api.manago.ai/v3/product/updateQuantity

Method:

POST

Body (JSON):

Field	Limits	Description
catalogId	UUID	UUID of a Product Catalog. You can find it in Manago AI ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Catalog is created using the product/catalogUpsert method.
productId	255	Product identifier from your eCommerce platform
quantity	int	Available quantity to be used in custom Recommendation Frames

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
problems	Array of additional information, including error messages

Sample response:

{
  "success": true
}

Product Recommendations

Search for similar products with a photo upload

Sample request:

{
  "productCatalogId": "21c2-...-3266",
  "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOE... [truncated]",
  "maxItems": 4,
  "includeUnavailable": false,
  "includeProductData": false,
  "mode": "MIX"
}

Sample response:

{
  "products": [
    {
      "id": "P123",
      "score": 0.82,
      "urlAppendix": "utm_source=salesmanago&prod_id=3243454"
    },
    {
      "id": "P456",
      "score": 0.81,
      "urlAppendix": "utm_source=salesmanago&prod_id=4324345"
    },
    {
      "id": "P789",
      "score": 0.80,
      "urlAppendix": "utm_source=salesmanago&prod_id=9324354"
    },
    {
      "id": "P987",
      "score": 0.77,
      "urlAppendix": "utm_source=salesmanago&prod_id=132436"
    }
  ],
  "problems": []
}

This method allows you to retrieve a list of visually similar products based on a base64-encoded image uploaded to the search engine on your website or in your mobile application. The image is analyzed by AI to identify products with similar visual features in your Product Catalog.

Endpoint:

https://api.manago.ai/v3/recommendation/searchByPhoto

Method:

POST

Fields:

Field	Limits	Description
productCatalogId*	UUID	ID of the Product Catalog to be searched for visually similar products.
imageData*	1 500 000 characters (approx. 1.125 MB of image data)	Base64-encoded image embedded as a Data URL string (with data:image MIME type). Supported MIME types: JPEG JPG PNG GIF BMP TIFF WebP
includeUnavailable	Bool	Flag indicating whether the response should include unavailable products (products with quantity=0 or available=false). The default value is false.
includeProductData	Bool	Flag indicating whether the response should contain only the product IDs or product IDs and product data. The default value is false.
maxItems	50	Maximum number of products to be returned. You can specify values between 1 and 50. The default value is 4.
mode	Enum	Enum indicating how similarity scores are computed. Allowed values: FIRST: Compares the uploaded image only with the main (first) images of products.Recommended when you have only one photo per product. MIX: Computes an Exponential Moving Average (EMA) [α=0.15] of similarity scores across the uploaded image and all product images. This smooths out variations and gives a more balanced similarity score for each product. Recommended for products that look similar from different angles. BEST_MATCH: Compares the uploaded image to all individual images in your e-store and selects products based on the highest similarity score for any individual image, even if other images of the same product score lower. This option is recommended for most cases. The default value is FIRST.

Response:

Field	Description
products	Array of products ordered by visual similarity score.
id	Product ID of each visually similar product.
score	Value between 0 and 1 indicating the degree of visual similarity (calculated based on the selected mode) between the uploaded product and each returned product. A higher value signifies greater similarity.
urlAppendix	Additional URL parameters to be appended to product URLs for analytical and tracking purposes. These parameters can help monitor user interactions and gather more data on product performance in the context of recommendations.

Product Collections

What are Product Collections?

Product Collections allow you to store information about products associated with individual Contacts. This data can later be used to target Contacts who have a specific product in a Collection or to synchronize Collection contents between different devices via API.

The most representative example is a Wishlist—when a Contact adds a product to their Wishlist, you can add it to the Wishlist Product Collection and later use the selector: Product Collection contains item(s) to select Contacts who took a liking to a specific product.
Another example could be Interested in—a Product Collection for storing items a Contact has expressed interest in, for example, by hovering their cursor over a product or scrolling its description to a certain depth.

Product Collection types

There is no fixed list of Product Collection types. You can create a Product Collection with any name you want. Some examples:

Wishlist: A collection of products that a Contact has expressed interest in purchasing, and added them to a wishlist
Interested in: A collection of products that a Contact has shown interest in, but have not added to their wishlist nor purchased
Purchased: A collection of products that a Contact has actually bought or ordered
Viewed: A collection of products that a Contact has viewed on an e-commerce platform or website
Favorites: A collection of products that a Contact has marked as their favorite for easy access
Recommended: A collection of products to be recommended to a Contact. This effectively lets you use Manago AI delivery channels with your internal or 3rd-party recommender system
Reviewed: A collection of products that a Contact has reviewed or given feedback on

Creating a Product Collection

Sample request:

{
  "name": "Wishlist",
  "catalogId": "21c2-...-3266"
}

You can create a new Product Collection with a name of your choice and associate it with a selected Product Catalog.

Endpoint:

https://api.manago.ai/v3/product/collection/add

Method:

POST

Body (JSON):

Field	Limits	Description
name	255	Product Collection name, used to identify the Collection in Manago AI.
catalogId	UUID	UUID of a Product Catalog. You can find it in Manago AI ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Catalog is created using the product/catalogUpsert method.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
problems	Array of additional information, including error messages
collectionsUUID	Unique identifier of the Product Collection, required when adding, deleting, or listing products in the Collection

Sample response:

{
  "collectionUUID": "0a1b-...-2c3d",
  "success": true
}

Adding products to a Product Collection

Sample request:

{
  "collectionUUID": "0a1b-...-2c3d",
  "data": [
    {
      "contactId": "1a2b-...-3c4d",
      "productIds": [
        "P0123",
        "P1234",
        "P2345"
        ]
    },
    {
      "contactId": "2a3b-...-4c5d",
      "productIds": [
        "P0123",
        "P3456"
      ]
    }
  ]
}

You can add new products to a Product Collection in response to specific actions of individual Contacts.
You can also use this method when synchronizing external product lists for multiple products and multiple Contacts.

Endpoint:

https://api.manago.ai/v3/product/collection/products/add

Method:

POST

Body (JSON):

Field	Limits	Description
collectionUUID	UUID	UUID of a Product Collection. You can find it in Manago AI ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Collection is created using the product/collection/add method.
data	1000	Array of Contact➔product(s) assignments.
contactId	UUID	Contact ID as returned when the contact/upsert method is called. You can also use the value of the smclient cookie.
productIds	100*255	Array of product IDs. All specified product IDs must match the IDs in the associated Product Catalog.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
message	Array of additional information, including error messages

Sample response:

{
  "success": true,
  "message": "Products scheduled to be added for 1 out of 2 Contacts"
}

Removing products from a Product Collection

Sample request:

{
  "collectionUUID": "0a1b-...-2c3d",
  "data": [
    {
      "contactId": "1a2b-...-3c4d",
      "productIds": [
        "P0123",
        "P1234",
        "P2345"
      ]
    },
    {
      "contactId": "2a3b-...-4c5d",
      "productIds": [
        "P0123",
        "P3456"
      ]
    }
  ]
}

You can remove products from a Product Collection in response to specific actions of individual Contacts.
You can also use this method when synchronizing external product lists for multiple products and multiple Contacts.

Endpoint:

https://api.manago.ai/v3/product/collection/products/delete

Method:

POST

Body (JSON):

Field	Limits	Description
collectionUUID	UUID	UUID of a Product Collection. You can find it in Manago AI ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Collection is created using the product/collection/add method.
data	1000	Array of Contact➔product(s) assignments.
contactId	UUID	Contact ID as returned when the contact/upsert method is called. You can also use the value of the smclient cookie.
productIds	100*255	Array of product IDs. All specified product IDs must match the IDs in the associated Product Catalog.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
message	Array of additional information, including error messages

Sample response:

{
  "success": true,
  "message": "Products scheduled for removal for 1 out of 2 Contacts"
}

Listing products in Product Collection

Sample request:

{
  "collectionUUID": "0a1b-...-2c3d",
  "contactId" : "1a2b-...-3c4d"
}

You can retrieve a list of products contained in a Product Collection of a specific Contact.

Endpoint:

https://api.manago.ai/v3/product/collection/contact/products

Method:

POST

Body (JSON):

Field	Limits	Description
collectionUUID	UUID	UUID of a Product Collection. You can find it in Manago AI ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Collection is created using the product/collection/add method.
contactId	UUID	Contact ID as returned when the contact/upsert method is called. You can also use the value of the smclient cookie.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
message	Array of additional information, including error messages
products	Array of product IDs the Contact has in the specified Product Collection

Sample response:

{
  "success": true,
  "products": [
    "P0123",
    "P1234",
    "P2345"
  ]
}

Deleting a Product Collection

Sample request:

{
  "collectionUUID": "0a1b-...-2c3d"
}

You can delete a Product Collection from the Manago AI system, along with all Collection data associated with individual Contacts.

IMPORTANT: This action is irreversible and might cause a data loss.

Endpoint:

https://api.manago.ai/v3/product/collection/delete

Method:

POST

Body (JSON):

Field	Limits	Description
collectionUUID	UUID	UUID of a Product Collection. You can find it in Manago AI ➔ Integration Center ➔ Product Catalogs. The UUID is also returned when a Product Collection is created using the product/collection/add method.

Response:

Field	Description
success	Boolean value informing about the result of the request (successful/not successful)
problems	Array of additional information, including error messages

Sample response:

{
  "success": true
}

Customer Preference Center

Upsert a Key Information

Sample request:

{
  "owner": "[email protected]",
  "email": "[email protected]",
  "keyInformation": {
    "numeric": [
      {
        "name": "Shoe size",
        "value": 13
      }
    ],
    "text": [
      {
        "name": "Preferred color",
        "value": "black"
      },
      {
        "name": "Preferred price",
        "value": "$50 - $99"
      }
    ]
  },
  "setAsNull": [
    "Favorite brand",
    "Number of shoes"
  ]


}

Key Information is a data type used to store zero- and first-party data in Manago AI. Zero-party data is the most powerful data type in Marketing Automation because it is directly collected from the Contact, rather than being inferred or collected from third parties. Use Key Information upsert to add or update data gathered on your website. Important: Do not use this method to transfer information directly from Contact’s browser. Use backend integration when sending requests with API-KEY.

Endpoint:

https://api.manago.ai/v3/keyInformation/upsert

Method:

POST

Body (JSON):

Field	Max. length	Description
email*	RFC882	Contact identifier—either their email address or Contact ID
contactid*	UUID	Contact identifier—either their email address or Contact ID
keyInformation*	n/a	Object wrapping numeric and text arrays
numeric	n/a	Array of Key Information of a numeric type
text	n/a	Array of Key Information of a text type
name	255	Key Information name
value	255/BigDecimal	Key Information value
setAsNull	20x255	Array with Key Information names that should be nulled

Sample response:

{
  "requestId": "a1b2-...-c3d4"
}

Get Key Information

Sample request to retrieve a single value:
https://api.manago.ai/v3/keyInformation/get?contactId=1234-...-cdef&name=Shoe+size

Sample response:

{
  "contactId": "1234-...-cdef",
  "keyInformation": [
    {
      "name": "Shoe size",
      "value": 13
    }
  ]
}

You can get zero- and first-party data stored in Manago AI to personalize the Contact’s online experience. For example, if a Contact has indicated that they are interested in vegan products, you could display vegan-specific content and products on your app and website.

Endpoint:

https://api.manago.ai/v3/keyInformation/get

Method:

GET

Sample request to retrieve a single value:
https://api.manago.ai/v3/keyInformation/get?contactId=1234-...-cdef

Sample response:

{
  "contactId": "1234-...-cdef",
  "keyInformation": [
    {
      "name": "Shoe size",
      "value": 13
    },
    {
      "name": "Preferred color",
      "value": "black"
    },
    {
      "name": "Preferred price",
      "value": "$50 - $99"
    }
  ]
}

Request params:

Param Name	Limits	Description
email*	RFC882	Contact identifier—either their email address or Contact ID. For the email address, use the URL-encoding function.
contactid*	UUID
name	255	You can specify a Key Information name to retrieve a single value. If no key information name is specified all stored values will be returned. The value must be URL-encoded.

Other

Get status of request processing

Sample request (GET example):

https://api.manago.ai/v3/resource?requestId=968d-...-4c31

Sample response:

{
  "status": "DONE",
  "fileUrl": "https://storage.googleapis.com/sm-apiv3/(...)%3D%3D"
}

This method lets you manually get the request processing status, including resources like exported data files.

Endpoint:

https://api.manago.ai/v3/resource

Method:

GET

Fields:

Field	Limits	Description
requestId	UUID v4	ID of the operation. Currently, the supported methods include: `/v3/webpush/stats` `/v3/webpush/data`

Response:

Field	Description
status	Status of the operation. Possible values: • PENDING • PROCESSING • DONE • ERROR
fileUrl	URL of the resource (request result) returned if the operation is in DONE status

General information

Authentication

Validations

Methods and Content-Types

General errors and warnings

Emails

List emails

Endpoint:

Method:

Fields

Response:

Web Push

Send Web Push notification

Endpoint:

Method:

Body (JSON):

Response

List Web Push notification templates

Endpoint:

Method:

Fields

Response

Sent Web Push notification statistics

Endpoint:

Method:

Fields:

Export file contents:

Export of sent Web Push notification data

Endpoint:

Method:

Fields:

Export file contents:

List Web Push consent prompts

Endpoint:

Method:

Fields

Response

Mobile Push

List Mobile Push notification templates

Endpoint:

Method:

Fields

Response

Send Mobile Push notification

Endpoint:

Method:

Fields

Response:

List Mobile Push mass conversations

Endpoint:

Method:

Fields:

Response:

Get Mobile Push mass conversations statistics

Endpoint:

Method:

Fields:

Response:

Get statistics for Mobile Push notification template(s)

Endpoint:

Method:

Fields

Response

WhatsApp

List WhatsApp templates

Endpoint:

Method:

Fields:

Response:

Get WhatsApp template statistics

Endpoint:

Method:

Fields:

Response:

List WhatsApp mass conversations

Endpoint:

Method:

Fields:

Response:

Get Whatsapp mass conversations stats