This page is the Technical Reference of the Magnews REST API: here you’ll find the complete list of endpoints, including methods, parameters, payloads, request and response examples, and error codes.
If you’re just getting started with the Magnews APIs, begin with the REST API Getting Started Guide: it provides a full overview and explains the core concepts.
If you prefer to start testing endpoints right away, open our Postman collection and try the calls in just a few minutes.
Transactional
Note: What magnews refers to as “Transactional messages” are called Simple messages in the API.
GET | Get simple message status
/v19/simplemessages/message/:idmessageQuery Parameters
| Key | Type | Description |
|---|---|---|
address |
String | Email or SMS recipient. |
actualStatus |
String | Status of the transactional message. Possible values: internalError, hardBounce, waiting, sent, notSent, softBounce. |
sentDate |
Date | Delivery date. |
opened |
Boolean |
true if the message was opened. |
lastOpenedTs |
Date | Timestamp of the last open event. |
clicked |
Boolean |
true if the message was clicked. |
lastClickedTs |
Date | Timestamp of the last click event. |
idbouncecategory |
Integer | The ID of the bounce category. |
complainted |
Boolean |
true if the message resulted in a complaint. |
notSentCause |
String | Detailed reason if actualStatus is notSent. Possible values: unknown, blacklisted_recipient, cancelled, unsubscribed, forbidden_from, forbidden_replyto, maxsize_exceeded, phonerecipient_notallowed, empty_recipient, forbidden_smsfrom, forbidden_smsnumericfrom, no_credit. |
Path variables
| Variable | Description |
|---|---|
idmessage |
id of a transactional message |
Example responses
200 - Success Response
{
"messageId": "123456",
"address": "recipient@example.com",
"actualStatus": "sent",
"sentDate": "2023-06-15T10:30:00.000Z",
"opened": true,
"clicked": false,
"complainted": false,
"converted": false,
"messageRetention": "full",
"externalId": null
}GET | Get simple message status by external id
/v19/simplemessages/messagebyexternalid/:externalIdGet the status of a simple message by external ID
Path variables
| Variable | Description |
|---|---|
externalId |
Example responses
200 - Success Response
{
"messageId": "123456",
"address": "recipient@example.com",
"actualStatus": "sent",
"sentDate": "2023-06-15T10:30:00.000Z",
"opened": true,
"clicked": false,
"complainted": false,
"converted": false,
"messageRetention": "full",
"externalId": "ext-123456"
}GET | Get simple message info
/v19/simplemessages/message/:idmessage/infoGet information about a simple message by ID
Path variables
| Variable | Description |
|---|---|
idmessage |
Example responses
200 - Success Response
{
"messageId": "123456",
"address": "recipient@example.com",
"actualStatus": "sent",
"sentDate": "2023-06-15T10:30:00.000Z",
"opened": true,
"clicked": false,
"complainted": false,
"converted": false,
"messageRetention": "full",
"externalId": null,
"subject": "Test Email",
"fromEmail": "sender@example.com",
"fromName": "Sender Name",
"messageType": "email",
"htmlBody": "This is a <i>test</i> email",
"textBody": "This is a test email"
}POST | Send simple message
/v19/simplemessages/messageSend a transactional message
Request Body
options
| Option | Type | Default Value | Description |
|---|---|---|---|
idcontact |
Integer | null |
Lookup contact profile by internal ID. |
iddatabase |
Integer | null |
If contact not found, renders email as if sent to a contact in this database. |
contactprimarykey |
String | null |
Lookup contact profile by primary key in the specified database (see iddatabase). |
contactprimarykeyoptional |
Boolean | false |
If contact isn’t found, uses message.to as recipient instead of failing. Note: No statistics are recorded if contact is not found. |
usecontactemail |
Boolean | false |
Override message.to with the contact’s email. |
cssinline |
Boolean | false |
Apply CSS inline to HTML content. |
embeddedimages |
Boolean | false |
Download and embed images from HTML content. |
idwebsite |
Integer | (default website ID) | Website ID used to render absolute URLs (images, unsubscribe links, etc.). |
usenewsletterastemplate |
Boolean | false |
Use a communication template (notification template) as the message body. |
renderatsend |
Boolean | false |
Render the message at send time (preferred with usenewsletterastemplate; no DB persistence). |
usehtmlcodeastemplate |
Boolean | false |
Use provided HTML code as the message body (allows Giotto conditions). |
idnewsletter |
Integer | null |
Communication template ID for rendering (requires usenewsletterastemplate=true). |
newsletterkey |
String | null |
Communication template key for rendering (requires usenewsletterastemplate=true). If both idnewsletter and newsletterkey are set, idnewsletter takes precedence. |
format |
String | "html" |
Message format: "html", "text", or "multipart". |
validatesmslength |
Boolean | true |
Validate SMS parts count against maxsmsparts and account settings. |
maxsmsparts |
Integer | (account max SMS parts) | Maximum allowed SMS parts; messages exceeding this limit are not sent. |
expectedDeliveryTs |
Timestamp | (empty = ASAP) | Schedule message delivery; empty means send immediately. |
temp.xxx |
String | "" |
Set initial value of temp.xxx Giotto variables ([temp:xxx] syntax). |
messageRetention |
String | "minimal" |
Retention policy: "minimal" (discard body), "full" (keep body & headers), "reserved". |
externalId |
String | "null" |
Assign an external ID to the message. |
inputparam.xxx |
String | "" |
Set inputparam.xxx Giotto variables ([inputparam:xxx] syntax). |
nospool |
Boolean | false |
Attempt to send without spooling for timelier delivery. |
idlanguage |
String | null |
Language ID: "ITA", "ENG", "FRA", or null. |
usecontactcell |
Boolean | false |
Override message.to with contact’s phone number for SMS. |
values
| Field | Type | Default Value | Description |
|---|---|---|---|
type |
String | null |
Message type: "email" or "sms". |
to |
String | null |
Recipient email address or phone number. |
fromemail |
String | null |
From header email address (email messages only). |
fromname |
String | null |
From header name (email messages only). |
replyto |
String | null |
Reply-To header email address (email messages only). |
subject |
String | null |
Email subject (email messages only). |
preheader |
String | null |
Preview text (email messages only). |
charset |
String | null |
Email charset (email messages only). |
htmlbody |
String | null |
HTML content (email messages only). |
textbody |
String | null |
Plain-text content (email messages only). |
from |
String | null |
SMS sender ID (phone number or name, SMS only). |
smsbody |
String | null |
SMS message text (SMS only). |
idmessagetype |
Integer | (none) | Transactional message type ID for stats aggregation. |
attachments |
Array | null |
Array of attachment objects (see below). |
header.xxxx |
String | (none) | Custom header lines, e.g. header.Message-ID=MyID@server (email messages only). |
Attachment object
| Property | Type | Description |
|---|---|---|
filename |
String | Attachment file name. |
contenttype |
String | MIME type; inferred from filename if omitted. |
body |
String | File content as Base64-encoded string. |
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"options": {
"usecontactemail": false,
"nospool": false
},
"values": {
"type": "email",
"fromemail": "sender@example.com",
"fromname": "Sender Name",
"to": "recipient@example.com",
"subject": "Test Email",
"htmlbody": "This is a <i>test</i> email"
}
}Example responses
200 - Success Response
{
"messageId": "123456",
"address": "recipient@example.com",
"actualStatus": "waiting",
"sentDate": "2023-06-15T10:30:00.000Z",
"opened": false,
"clicked": false,
"complainted": false,
"converted": false,
"messageRetention": "full",
"externalId": null
}400 - Error Response - Empty From Email
{
"error": "an empty fromemail is not valid"
}500 - Server Error Response
{
"error": "Internal server error",
"message": "An unexpected error occurred while processing your request"
}POST | Send simple message using contact data
/v19/simplemessages/messageSend a transactional message with an attachment to a platform contact
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"options": {
"usecontactemail": true,
"idcontact": 1,
"nospool": false
},
"values": {
"type": "email",
"fromemail": "sender@example.com",
"fromname": "Sender Name",
"subject": "Test Email for Contact",
"htmlbody": "This is a <i>test</i> email for contact",
"attachments": [
{
"filename": "hello.csv",
"contenttype": "text/csv",
"body": "bmFtZSxlbWFpbAp0ZXN0LHRlc3RAZXhhbXBsZS5jb20="
}
]
}
}Example responses
200 - Success Response
{
"messageId": "123456",
"address": "contact@example.com",
"actualStatus": "waiting",
"sentDate": "2023-06-15T10:30:00.000Z",
"opened": false,
"clicked": false,
"complainted": false,
"converted": false,
"messageRetention": "full",
"externalId": null
}POST | Send simple message using template
/v19/simplemessages/messageSend a transactional message using a communication as a template filled with temp vars
Note: If you specify the
subject value, you must remove the renderatsend option (and vice versa).Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"options": {
"usenewsletterastemplate": "true",
"idnewsletter": 5,
"renderatsend": "true",
"temp.myvar1": "hello",
"temp.myvar2": "world"
},
"values": {
"type": "email",
"fromemail": "email@test.informatica.it",
"fromname": "Test",
"replyto": "email@test.informatica.it",
"to": "recipient@domain.it"
}
}Example responses
200 - Success Response
{
"messageId": "123456",
"address": "contact@example.com",
"actualStatus": "waiting",
"sentDate": "2023-06-15T10:30:00.000Z",
"opened": false,
"clicked": false,
"complainted": false,
"converted": false,
"messageRetention": "full",
"externalId": null
}POST | Send SMS message
/v19/simplemessages/messageSend transactional SMS message
Send a single SMS message using the same options as the email message request.
See Send simple message options for full details.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"options": {
"usenewsletterastemplate": "true",
"idnewsletter": 5
},
"values": {
"type": "sms",
"from": "smssender",
"smsbody": "helloooo",
"to": "+390000000"
}
}Example responses
- Success Response
POST | Send MIME message
/v19/simplemessages/mimemessage?recipient=recipient@example.com&cssinline=false&idmessagetype=0&retention=full&destination=frontendSend a MIME transactional message
If the message is sent successfully, this function returns the message ID; otherwise it returns an error.
Prerequisites:
- Define the mandatory
recipientquery parameter.
- Include the header:
Content-Type: message/rfc822.
Query parameters
| Key | Type | Description |
|---|---|---|
recipient |
String | Recipient email address (mandatory). |
idcontact |
Integer | ID of the contact to link to the message (optional). |
expectedDeliveryTs |
Timestamp | Unix timestamp in milliseconds (default null) to schedule future delivery. |
destination |
String | Specifies delivery channel: frontend (contact), backend (platform user), or bulk (Simply-SMTP). Default is frontend. |
idmessagetype |
Integer | Message type for statistics aggregation. |
cssinline |
Boolean | Whether to apply CSS inline to the HTML content. |
retention |
String | Retention policy: minimal (discard body), full (store body & headers), or reserved. |
externalId |
String | Custom external ID (up to 1000 chars) for mapping the message to another system. |
Result
Returns a JSON object:
| Field | Description |
|---|---|
ok |
true or false
|
error |
Error description (if ok is false) |
messageId |
ID of the transactional message (if ok is true) |
Query parameters
| Parameter | Description |
|---|---|
recipient |
recipient@example.com |
cssinline |
false |
idmessagetype |
0 |
retention |
full |
destination |
frontend |
Headers
| Header | Value |
|---|---|
Content-Type |
message/rfc822 |
Request body
From: "MN test" <sender@example.com>
Message-ID: <5bec11c119194c14999e592feb46e3cf@localhost>
Subject: Test Email
To: recipient@example.com
MIME-Version: 1.0
Content-Type: multipart/alternative;
boundary="start"
--start
Content-type: text/html; charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable
<html>
<head>
</head>
<body>
<div>This is a test email</div>
</body>
</html>
--start--Example responses
200 - Success Response
{
"messageId": "1",
"ok": true,
"error": ""
}400 - Error Response - Empty From Email
{
"messageId": null,
"ok": false,
"error": "Empty from in body message"
}500 - Server Error Response
{
"messageId": null,
"ok": false,
"error": "Error: Internal server error"
}POST | Batch Send simple messages
/v19/simplemessages/messagesSend multiple simple messages in a batch.
Options are the same as Send simple messages.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"messages": [
{
"options": {
"usecontactemail": false,
"nospool": false
},
"values": {
"type": "email",
"fromemail": "sender@example.com",
"fromname": "Sender Name",
"to": "recipient1@example.com",
"subject": "Test Email 1",
"htmlbody": "This is a <i>test</i> email 1"
}
},
{
"options": {
"usecontactemail": false,
"nospool": false
},
"values": {
"type": "email",
"fromemail": "sender@example.com",
"fromname": "Sender Name",
"to": "recipient2@example.com",
"subject": "Test Email 2",
"htmlbody": "This is a <i>test</i> email 2"
}
}
]
}Example responses
200 - Success Response
{
"results": [
{
"result": {
"messageId": "123456",
"address": "recipient1@example.com",
"actualStatus": "waiting",
"sentDate": "2023-06-15T10:30:00.000Z",
"opened": false,
"clicked": false,
"complainted": false,
"converted": false,
"messageRetention": "full",
"externalId": null
}
},
{
"result": {
"messageId": "123457",
"address": "recipient2@example.com",
"actualStatus": "waiting",
"sentDate": "2023-06-15T10:30:00.000Z",
"opened": false,
"clicked": false,
"complainted": false,
"converted": false,
"messageRetention": "full",
"externalId": null
}
}
]
}400 - Error Response - Empty From Email
{
"error": "an empty fromemail is not valid"
}500 - Server Error Response
{
"error": "Internal server error",
"message": "An unexpected error occurred while processing your request"
}Communications
Note: The Newsletters section includes both marketing communications and transactional templates.
GET | Get newsletter basic information
/v19/newsletters/:id/infoGet newsletter (communication or transactional template) basic information such as name, type, status, thumbnail image, channel details (like email headers), etc.
Path variables
| Variable | Description |
|---|---|
id |
the newsletter id (communication or template id) |
Example responses
200 - Communication example
{
"id": 101,
"name": "Summer Deals Newsletter",
"type": "communication",
"status": "draft",
"idjourney": 202,
"journey": "Summer Campaign 2025",
"idworkflow": 0,
"idlandingpage": 0,
"creationDate": 1730707200000,
"lastUpdateDate": 1731285600000,
"sentDate": null,
"scheduledSendDate": null,
"channels": [
{
"preheader": "Save big on your summer essentials",
"from_email": "offers@magnews.com",
"channel": "email",
"absplit": false,
"from_name": "Magnews Marketing Team"
}
],
"thumbnail": "http://myfrontendinstance/newsletterthumb/6/101?_cv=704942055&s=b3ffd470b2e15490d33eb314a1e7102ef6fe760c401120982a9df241fdcf849e"
}200 - Transactional example
{
"id": 337,
"name": "WhatsApp test Rest API",
"type": "transactional",
"status": "active",
"idjourney": 11,
"journey": "My journey",
"idworkflow": 0,
"idlandingpage": 0,
"creationDate": 1725360693687,
"lastUpdateDate": 1725370784810,
"sentDate": null,
"scheduledSendDate": null,
"channels": [
{
"channel": "whatsappbusiness"
}
],
"thumbnail": "http://myfrontendsite/newsletterthumb/6/337?_cv=1419749233&s=4db29bf46d558cd9f5226e1fd19bc547f04a7060526747fa4c799122aab8288f"
}POST | Update newsletter basic information
/v19/newsletters/:id/updateUpdates an existing newsletter. This endpoint allows modifying fields such as the name, subject, sender information, and descriptions. If the newsletter has an A/B split test enabled, you can target a specific variant for the update.
Usage Notes
- Transactional Newsletters: The
newsletterKeyfield can only be set if the newsletter is configured as a transactional template.
- A/B Split Test: If the newsletter has an active A/B test, the
subject,preheader,fromEmailandfromNamefields will update the specific variant if the endpoint is called with theabsplitversionquery parameter (e.g.,/update?absplitversion=b).
- Optionality: It is not necessary to send all fields; you can include only the ones you actually intend to modify in the JSON body.
Path variables
| Variable | Description |
|---|---|
id |
the newsletter id (communication or template id) |
Request body
{
"name": "Newsletter Promozionale Gennaio 2026",
"subject": "Sconti esclusivi solo per te!",
"fromEmail": "marketing@example.com",
"fromName": "Team Marketing MagNews",
"emailReplyTo": "supporto@example.com",
"preheader": "Scopri le offerte riservate ai nostri migliori clienti.",
"usersDescription": "Campagna per il lancio dei saldi invernali 2026.",
"contactsDescription": "Comunicazioni periodiche su sconti e promozioni."
}Example responses
200 - Update newsletter basic information
POST | Send communication (create delivery)
/v19/communications/communication/:id/sendTriggers the sending of a communication (newsletter) to a specified target. This creates a new Delivery instance. You can configure scheduling (immediate, postponed, periodic, or partitioned) and various delivery options for different channels (email, sms).
Request body includes this fields:
-
enableEmail: Whether to enable email channel.
-
enableSms: Whether to enable sms channel.
-
customChannels: List of custom channels to enable (comma separated).
-
target: List of target group IDs.
-
skipConfirmation: If true, skips the confirmation step if required by the campaign.
-
schedule: Scheduling configuration (see below)
-
options: Delivery options (see below)
Scheduling configuration:
-
type: Type of schedule:immediate,scheduled,periodic,partitioned.
-
period: For periodic:daily,weekly,monthly,yearly.
-
year,month,day,hour,minute: Date and time components for the schedule.
-
sendtimeOptimization: If true, enable send-time optimization.
-
useContactsTimeZone: If true, use the contacts' time zone for delivery time.
-
weekDays: For weekly period:monday,tuesday,..
-
partitions: For partitioned deliveries: list of { "delta": long, "percent": int }
-
startInterval,endInterval: Dates used to define a range for periodic deliveries.
Options:
-
recall: Whether this is a recall delivery.
-
failOnEmptyTarget: If true, the request fails if the target has no contacts.
-
ignoreUserPreferencesOnChannels: Ignore global user channel preferences and send the message anyway.
-
additionalTargetFilterQuery: MQL filter to further restrict the target.
-
email: Email specific options (subject override, encoding, images embedding, etc.).
-
sms: SMS specific options (from override, encoding).
-
speedLimiter: Limit the sending speed (enabled,maxSpeedPerMinute).
-
authorization: Configure authorization workflow.
-
report: Configure delivery report notification.
Response:
-
iddelivery: id of the delivery to use in/delivery/:iddelivery/status|pause|stop|resumeendpoints
-
errors: detailed errors (no channels enabled for communication, missing required parameters, no target for sending,...)
Path variables
| Variable | Description |
|---|---|
id |
372 |
Request body
{
"enableEmail": true,
"skipConfirmation": true,
"target": [
129
],
"schedule": {
"type": "immediate"
},
"options": {
"failOnEmptyTarget": true,
"useAllChannels": true,
"email": {
"useNewsletterOptions": true,
"allowDuplicatedRecipients": false
},
"additionalTargetFilterQuery": "SELECT * FROM CONTACTS WHERE email like '%diennea.com'"
}
}Example responses
200 - Send communication
{
"iddelivery": 81,
"errors": null
}GET | Get delivery status
/v19/deliveries/delivery/:iddelivery/statusRetrieves the detailed status and configuration of a specific delivery. Returns information about the current state, scheduling, and target audience.
Response Body
The response is a JSON object with the following fields:
-
iddelivery(int): The unique identifier of the delivery.
-
idnewsletter(int): The identifier of the newsletter associated with the delivery.
-
trial(boolean): Indicates if it's a trial delivery.
-
status(string): The current status of the delivery. Possible values are:
- unconfirmed: The delivery has not been confirmed.
- scheduled: The delivery is waiting to be sent at the scheduled time.
- sending: The delivery is being prepared or sent.
- error: An error occurred during preparation or sending.
- finished: The delivery has completed successfully.
- paused: The delivery has been paused.
- stopped: The delivery was interrupted or stopped.
-
target(list of integers): A list of audience IDs that are the target of this delivery.
-
targetUsesAdditionalFilter(boolean): Indicates if additional filters are applied to the target
-
requestedMessages(map): A map showing the number of requested messages per channel (e.g., "email", "sms").
-
startDate(date): The timestamp when the delivery started or is scheduled to start.
-
schedule(object): An object describing the scheduling configuration.
Path variables
| Variable | Description |
|---|---|
iddelivery |
The unique integer ID of the delivery |
Example responses
200 - Get delivery status
{
"iddelivery": 81,
"idnewsletter": 372,
"trial": false,
"status": "sending",
"target": [
129
],
"targetUsesAdditionalFilter": true,
"requestedMessages": {
"sms": 0,
"email": 12
},
"startDate": 1769176616187,
"schedule": {
"type": "immediate"
}
}POST | Pause delivery
/v19/deliveries/delivery/:iddelivery/pausePauses an active delivery. Suspends the execution of a delivery. The delivery must be active and not yet completed or moved to history. Requires "send newsletter" permissions.
Path variables
| Variable | Description |
|---|---|
iddelivery |
The unique integer ID of the delivery |
Example responses
200 - Pause delivery
POST | Resume delivery
/v19/deliveries/delivery/:iddelivery/resumeResumes a previously paused delivery. Restarts a delivery that was suspended. It sets the resume time to the current system time. Requires "send newsletter" permissions.
Path variables
| Variable | Description |
|---|---|
iddelivery |
The unique integer ID of the delivery |
Example responses
200 - Resume delivery
POST | Stop delivery
/v19/deliveries/delivery/:iddelivery/stopStops an active delivery. This method attempts to cancel an ongoing delivery. It requires "send newsletter" permissions for the campaign associated with the delivery.
Path variables
| Variable | Description |
|---|---|
iddelivery |
The unique integer ID of the delivery |
Example responses
200 - Stop delivery
GET | Query deliveries
/v19/deliveries/query?query=SELECT * from DELIVERIES where idnewsletter=5Queries delivery records that satisfy an MQL query; a delivery represents a single instance created each time a communication is sent, whether for testing or for a production send.
The response is a JSON array of objects containing:
-
iddelivery: ID of the delivery
-
idnewsletter: ID of the associated communication
-
trial: whether the delivery is a test (trial)
-
status: a value between "sending", "error", "unconfirmed", "scheduled", "paused", "finished", "stopped"
-
target: list of target audience IDs
-
targetUseAdditionalFilter: whether an additional filter is applied to the target
-
requestedMessages: count of requested messages per channel (ie: 'email': 23, 'sms': 2)
-
startDate: start date and time of delivery (unix ts milliseconds)
-
schedule: the scheduling configuration
The schedule object contains a type field which determines the structure:
-
immediate: No additional fields.
-
scheduled: Includesyear, month, day, hour, minute, sendTimeOptimization, useContactsTimeZone.
-
periodic: Includes period (daily, weekly, monthly, yearly),month, day, hour, minute, weekDays, useContactsTimeZone, sendTimeOptimization, startInterval, endInterval.
-
partitioned: Includes partitions (a list of objects with delta and percent).
Query parameters
| Parameter | Description |
|---|---|
query |
MQL query to filter deliveries |
Example responses
200 - Query communication deliveries
[
{
"iddelivery": 2,
"idnewsletter": 5,
"trial": false,
"status": "finished",
"target": [
8
],
"targetUsesAdditionalFilter": false,
"requestedMessages": {
"sms": 1,
"email": 0
},
"startDate": 1487852029587,
"schedule": {
"type": "immediate"
}
}
]Contacts
GET | Find contact by id
/v19/contacts/contact/:idcontactFind a contact by ID
Path variables
| Variable | Description |
|---|---|
idcontact |
1 |
Example responses
200 - Success Response
{
"idcontact": 1,
"email": "contact@example.com",
"name": "John Doe",
"surname": "Smith",
"company": "Example Corp",
"phone": "+1234567890",
"mobile": "+1987654321",
"address": "123 Main St",
"city": "New York",
"zipcode": "10001",
"country": "USA",
"subscriptionDate": "2023-01-15T10:30:00.000Z",
"unsubscriptionDate": null,
"status": "active",
"customFields": {
"custom1": "value1",
"custom2": "value2"
}
}GET | Query contacts
/v19/contacts/query?query=select * from contacts where iddatabase=7 limit 2Return a list of contacts matching the specified query.
Writing queries
See the Query documentation for more details on how to write queries.
Query parameters
| Parameter | Description |
|---|---|
query |
select * from contacts where iddatabase=7 limit 2 |
Example responses
200 - Success Response
[
{
"iddatabase": 7,
"idcontact": 500106,
"status": "unsubscribed",
"fields": {
"ls_score_dm_3": "0",
"ls_scoring_1": "cold",
"ls_score_dm_1": "0",
"ls_scoring_3": "cold",
"idlettore": "500106",
"iddatabase": "7",
"causa_eliminazione": "1",
"data_ultima_esportazione": "",
"idcontact": "500106",
"fax": "",
"shop_accepts_marketing": "false",
"nome_utente": "5062206324890",
"primarykey": "5062206324890",
"ls_score_bh": "0",
"riceve_sms": "0",
"suspend_til_date": "",
"idfriend": "0",
"check": "4215818",
"riceve_email": "1",
"formato_spedizione": "2",
"data_ultima_modifica": "25/02/2025 12:58",
"rfm_output_f_1": "0",
"rfm_output_f_3": "0",
"flag_stato": "99",
"data_eliminazione": "22/09/2022 11:51",
"rfm_output_r_1": "0",
"rfm_output_r_3": "0",
"causa_sospensione": "0",
"lingua": "",
"cognome": "Clementi",
"data_iscrizione": "26/03/2021 10:37",
"notrack": "false",
"timezone": "",
"dominio": "informatica.it",
"data_ultima_azione": "",
"cell": "",
"data_sospensione": "",
"iddeliverycluster": "0",
"login": "5062206324890",
"rfm_output_c_1": "Prospect",
"shopify_imported": "true",
"rfm_output_c_3": "Prospect",
"provenienza": "2",
"email": "diana.example+test@informatica.it",
"ls_score_dm": "-5",
"riceve_fax": "0",
"_fieldsets_with_record": "[]",
"dyn_address1_composite": "via marconi",
"data_conf_isc": "",
"ls_score_bh_3": "0",
"ls_score_bh_1": "0",
"idaddressbook": "7",
"rfm_output_m_1": "0",
"rfm_output_m_3": "0",
"ls_scoring_updated_at": "30/10/2023 12:58"
}
},
{
"iddatabase": 7,
"idcontact": 500303,
"status": "unsubscribed",
"fields": {
"ls_score_dm_3": "0",
"ls_scoring_1": "cold",
"ls_score_dm_1": "0",
"ls_scoring_3": "cold",
"idlettore": "500303",
"iddatabase": "7",
"causa_eliminazione": "1",
"data_ultima_esportazione": "",
"idcontact": "500303",
"fax": "",
"shop_accepts_marketing": "false",
"nome_utente": "5143771775130",
"primarykey": "5143771775130",
"ls_score_bh": "0",
"riceve_sms": "0",
"suspend_til_date": "",
"idfriend": "0",
"check": "9014573",
"riceve_email": "1",
"formato_spedizione": "2",
"data_ultima_modifica": "22/09/2022 11:50",
"rfm_output_f_1": "0",
"rfm_output_f_3": "0",
"flag_stato": "99",
"data_eliminazione": "22/09/2022 11:51",
"rfm_output_r_1": "0",
"rfm_output_r_3": "0",
"causa_sospensione": "0",
"lingua": "",
"cognome": "clem6",
"data_iscrizione": "27/07/2022 00:02",
"notrack": "false",
"timezone": "",
"dominio": "test.informatica.it",
"data_ultima_azione": "",
"cell": "",
"data_sospensione": "",
"iddeliverycluster": "0",
"login": "5143771775130",
"rfm_output_c_1": "Prospect",
"shopify_imported": "true",
"rfm_output_c_3": "Prospect",
"provenienza": "2",
"email": "diana.example+6@test.informatica.it",
"ls_score_dm": "-5",
"riceve_fax": "0",
"_fieldsets_with_record": "[]",
"data_conf_isc": "",
"ls_score_bh_3": "0",
"ls_score_bh_1": "0",
"idaddressbook": "7",
"rfm_output_m_1": "0",
"rfm_output_m_3": "0",
"ls_scoring_updated_at": "30/10/2023 12:58"
}
},
{
"iddatabase": 7,
"idcontact": 500304,
"status": "unsubscribed",
"fields": {
"ls_score_dm_3": "0",
"ls_scoring_1": "cold",
"ls_score_dm_1": "0",
"ls_scoring_3": "cold",
"idlettore": "500304",
"iddatabase": "7",
"causa_eliminazione": "1",
"data_ultima_esportazione": "",
"idcontact": "500304",
"fax": "",
"shop_accepts_marketing": "false",
"nome_utente": "5143784521882",
"primarykey": "5143784521882",
"ls_score_bh": "0",
"riceve_sms": "0",
"suspend_til_date": "",
"idfriend": "0",
"check": "16705419",
"riceve_email": "1",
"formato_spedizione": "2",
"data_ultima_modifica": "22/09/2022 11:50",
"rfm_output_f_1": "0",
"rfm_output_f_3": "0",
"flag_stato": "99",
"data_eliminazione": "22/09/2022 11:51",
"rfm_output_r_1": "0",
"rfm_output_r_3": "0",
"causa_sospensione": "0",
"lingua": "",
"cognome": "clem7",
"data_iscrizione": "27/07/2022 00:02",
"notrack": "false",
"timezone": "",
"dominio": "test.informatica.it",
"data_ultima_azione": "",
"cell": "",
"data_sospensione": "",
"iddeliverycluster": "0",
"login": "5143784521882",
"rfm_output_c_1": "Prospect",
"shopify_imported": "true",
"rfm_output_c_3": "Prospect",
"provenienza": "2",
"email": "diana.example@test.informatica.it",
"ls_score_dm": "-5",
"riceve_fax": "0",
"_fieldsets_with_record": "[]",
"data_conf_isc": "",
"ls_score_bh_3": "0",
"ls_score_bh_1": "0",
"idaddressbook": "7",
"rfm_output_m_1": "0",
"rfm_output_m_3": "0",
"ls_scoring_updated_at": "30/10/2023 12:58"
}
},
{
"iddatabase": 7,
"idcontact": 500305,
"status": "unsubscribed",
"fields": {
"ls_score_dm_3": "0",
"ls_scoring_1": "cold",
"ls_score_dm_1": "0",
"ls_scoring_3": "cold",
"idlettore": "500305",
"iddatabase": "7",
"causa_eliminazione": "1",
"data_ultima_esportazione": "",
"idcontact": "500305",
"fax": "",
"shop_accepts_marketing": "false",
"nome_utente": "5143840293018",
"primarykey": "5143840293018",
"ls_score_bh": "0",
"riceve_sms": "0",
"suspend_til_date": "",
"idfriend": "0",
"check": "300681",
"riceve_email": "1",
"formato_spedizione": "2",
"data_ultima_modifica": "22/09/2022 11:50",
"rfm_output_f_1": "0",
"rfm_output_f_3": "0",
"flag_stato": "99",
"data_eliminazione": "22/09/2022 11:51",
"rfm_output_r_1": "0",
"rfm_output_r_3": "0",
"causa_sospensione": "0",
"lingua": "",
"cognome": "clem8",
"data_iscrizione": "27/07/2022 00:02",
"notrack": "false",
"timezone": "",
"dominio": "test.informatica.it",
"data_ultima_azione": "",
"cell": "",
"data_sospensione": "",
"iddeliverycluster": "0",
"login": "5143840293018",
"rfm_output_c_1": "Prospect",
"shopify_imported": "true",
"rfm_output_c_3": "Prospect",
"provenienza": "2",
"email": "diana.example+8@test.informatica.it",
"ls_score_dm": "-5",
"riceve_fax": "0",
"_fieldsets_with_record": "[]",
"data_conf_isc": "",
"ls_score_bh_3": "0",
"ls_score_bh_1": "0",
"idaddressbook": "7",
"rfm_output_m_1": "0",
"rfm_output_m_3": "0",
"ls_scoring_updated_at": "30/10/2023 12:58"
}
}
]POST | Merge contact by id
/v19/contacts/contact/:idcontactCreates or updates a contact by providing the idcontact.
Options
You can map these options in the json body of the request, under "options" object.
| Option | Type | Default | Description |
|---|---|---|---|
| iddatabase | Integer | Database ID for the new contact | |
| sendemail | Boolean | false | Request to send an email to the contact |
| sendemailonactions | String (comma-separated) | insert, restore | Actions for which to send email, depending on the merge result: insert, update, nothing, reactivate, restore, subscription_confirm, update, delete, suspend
|
| idtemplate | Integer | null | ID of the template of the transactional message to use for the email |
| enterworkflow | Boolean | false | Request the contact to enter an automated flow |
| enterworkflowonactions | String (comma-separated) | insert, restore | Actions triggering entrance to automated flow |
| key | String | null | Entry point ID for automated flow. If idworkflow not specified, all flows with the entry point are triggered |
| idworkflow | Integer | 0 | Specific workflow ID to enter. If 0, all matching flows are triggered |
| wf. | Primitive types | Session context variable, e.g., "wf.source": "website"
|
|
| denyupdatecontact | Boolean | false | Prevents contact update |
| forceallowrestorecontactonupdate | Boolean | false | Allows reactivation even with denyupdatecontact = true
|
| denysubscribenewcontact | Boolean | false | Prevents subscription of new contacts |
| denysubscribeunsubscribedcontact | Boolean | false | Denies reactivation of unsubscribed contacts |
| messageRetention | String | "minimal" | Retention policy: "minimal", "full", or "reserved"
|
| lookuprelations | Boolean | false | If true, uses logical keys for relational fields |
| addToSimpleGroup | Integer | Adds contact to the specified static audience | |
| removeFromSimpleGroup | Integer | Removes contact from the specified static audience | |
| returnwebtrackingid | Boolean | false | Returns Web Tracking session ID |
| storeEvent | String | This option requests to register an event. Only valid value: "contactUnsubscribed"; requires messageRef
|
|
| messageRef | String | Message reference for storeEvent
|
Values
You can map these values in the JSON body of the request, under the values object.
The values field contains the data to be associated with the contact. Keys must match the field IDs (e.g., email, name, status, etc.).
For the status field, you can specify one of the following values: subscribed, unsubscribed, unconfirmed or suspended.
⚠️ For decimal numbers, always use a JSON string, and format the decimal separator according to the international settings of the user performing the operation. Valid examples: "1234.56" or "1234,56".
For multivalue fields, use a string containing a comma-separated list of values, like this:
"MULTIVALUESFIELD": "\"value1\",\"value2\"".
Response
The API response contains the following fields:
| Key | Type | Description |
|---|---|---|
ok |
Boolean |
true if the operation was successful |
pk |
String | Primary key of the contact |
idcontact |
Integer | Unique ID of the contact |
action |
String | Executed action: one of insert, update, delete, nothing, reactivate, restore, subscription_confirm, suspend
|
errors |
Array | List of possible errors; each includes a type and the related field |
sendemail |
Object | Result of the email sending (if requested) |
sendemail.emailsent |
Boolean |
true if the email was sent |
sendemail.emailaddress |
String | Email address of the recipient |
sendemail.idsimplemessage |
String | ID of the transactional message |
enterworkflow |
Object | Result of the automated flow entry request |
enterworkflow.workflowentered |
Boolean |
true if at least one automated flow session was triggered |
enterworkflow.idworkflowsessions |
Array of Integer | List of session IDs for the triggered flows |
Path variables
| Variable | Description |
|---|---|
idcontact |
1 |
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"values": {
"email": "contact@example.com",
"name": "John Doe"
},
"options": {
"updateIfExists": true
}
}Example responses
200 - Success Response
{
"idcontact": 1,
"email": "contact@example.com",
"name": "John Doe",
"result": "updated",
"message": "Contact successfully updated"
}POST | Merge contact by primary key
/v19/contacts/mergeUpdate or insert a contact by matching the database primary key value (e.g., email or username).
For json body specification refer to Merge contact options and values.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"values": {
"email": "contact@example.com",
"name": "John Doe"
},
"options": {
"iddatabase": 1,
"updateIfExists": true
}
}Example responses
200 - Success Response
{
"idcontact": 1,
"email": "contact@example.com",
"name": "John Doe",
"result": "created",
"message": "Contact successfully created"
}POST | Subscribe contact
/v19/contacts/subscribeSubscribe a contact or change the contact status to subscribed if the contact already exists.
For json body specification refer to Merge contact options and values.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"values": {
"email": "contact@example.com",
"name": "John Doe"
},
"options": {
"iddatabase": 1
}
}Example responses
200 - Success Response
{
"idcontact": 1,
"email": "contact@example.com",
"name": "John Doe",
"result": "subscribed",
"message": "Contact successfully subscribed to addressbook 1"
}POST | Unsubscribe contact
/v19/contacts/unsubscribeUnsubscribe a contact.
For json body specification refer to Merge contact options and values.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"values": {
"email": "contact@example.com"
},
"options": {
"iddatabase": 1
}
}Example responses
200 - Success Response
{
"idcontact": 1,
"email": "contact@example.com",
"result": "unsubscribed",
"message": "Contact successfully unsubscribed from addressbook 1"
}DELETE | Delete contact
/v19/contacts/delete/:idcontact?dropformsdata=truePermanently deletes a single contact and all associated data.
Path variables
| Variable | Description |
|---|---|
idcontact |
Query parameters
| Parameter | Description |
|---|---|
dropformsdata |
(boolean, optional) If not specified, defaults to true. When true, also deletes the contact’s form submissions. |
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Example responses
204 - Success response
400 - Delete contact (contact not found)
{
"error": "contact not found or missing permissions",
"debugMessage": "contact not found or missing permissions"
}POST | Batch merge contacts
/v19/contacts/batchmergeMerge multiple contacts in a batch.
For json body specification refer to Merge contact options and values.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"iddatabase": 1,
"contacts": [
{
"values": [
{
"field": "email",
"value": "contact1@example.com"
},
{
"field": "name",
"value": "John Doe"
}
]
},
{
"values": [
{
"field": "email",
"value": "contact2@example.com"
},
{
"field": "name",
"value": "Jane Doe"
}
]
}
],
"options": {
"updateIfExists": true
}
}Example responses
200 - Success Response
{
"results": [
{
"idcontact": 1,
"email": "contact1@example.com",
"name": "John Doe",
"result": "created",
"message": "Contact successfully created"
},
{
"idcontact": 2,
"email": "contact2@example.com",
"name": "Jane Doe",
"result": "updated",
"message": "Contact successfully updated"
}
],
"totalProcessed": 2,
"totalCreated": 1,
"totalUpdated": 1,
"totalErrors": 0
}200 - Add to static group
[
{
"ok": true,
"pk": "testemail482404@test.example.com",
"idcontact": 482470,
"action": "update",
"errors": null,
"sendemail": null,
"enterworkflow": null,
"idwebtracking": null
},
{
"ok": true,
"pk": "testemail482405@test.example.com",
"idcontact": 482471,
"action": "update",
"errors": null,
"sendemail": null,
"enterworkflow": null,
"idwebtracking": null
}
]POST | Batch delete contacts
/v19/contacts/batchdeleteDeletes multiple contacts in batch. A contact can be identified either by its unique ID or by the pair _primary key + database ID_. Contacts are deduplicated before processing. The optional query parameter dropFormsData (boolean, defaults to true) works as described above, also deletes the contact’s form submissions.
If allowPartialDelete is set to true, contacts that cannot be deleted are skipped, while the others are removed. The request completes with a 200 response and includes a summary report.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"contactids": [102,103],
"contactpks": [
{
"contactpk": "testemail34@test.example.com",
"iddatabase": 1
},
{
"contactpk": "testemail35@test.example.com",
"iddatabase": 2
}
]
}Example responses
200 - Batch delete contacts
{
"results": [
{
"idcontact": null,
"contactpk": "testemail35@test.example.com",
"iddatabase": 2,
"successful": false,
"error": "contact not found by primary key and database id lookup"
},
{
"idcontact": 100,
"contactpk": "testemail34@test.example.com",
"iddatabase": 1,
"successful": true,
"error": null
},
{
"idcontact": 102,
"contactpk": "testemail36@test.example.com",
"iddatabase": 1,
"successful": true,
"error": null
},
{
"idcontact": 103,
"contactpk": "testemail37@test.example.com",
"iddatabase": 1,
"successful": true,
"error": null
}
]
}Audiences
GET | Find audience by id
/v19/audiences/audience/:idaudienceFind an audience by ID
Path variables
| Variable | Description |
|---|---|
idaudience |
1 |
Example responses
200 - Success Response
{
"iddatabase": 0,
"name": "Contatti sospesi",
"idgroup": 1,
"idparent": 78,
"idlist": 0,
"idplanneddelivery": 0,
"ondemand": false,
"creationdate": 1436524697587,
"lastmodificationdate": 1599040054627,
"expiredate": null,
"creationuserid": 2,
"modificationuserid": 2,
"staticgroup": false,
"contactgroupstatus": null
}GET | Query audiences
/v19/audiences/query?query=SELECT * FROM groups WHERE idgroup=18Return a list of audiences matching the specified query.
Writing queries
See the Query documentation for more details on how to write queries.
Note: the groups table refers to audiences.
Query parameters
| Parameter | Description |
|---|---|
query |
SELECT * FROM groups WHERE idgroup=18 |
Example responses
200 - Query audiences
[
{
"iddatabase": 0,
"name": "Iscritti alla newsletter - Non clienti",
"idgroup": 11,
"idparent": 9,
"idlist": 0,
"idplanneddelivery": 0,
"ondemand": false,
"creationdate": 1537856218520,
"lastmodificationdate": 1537856218507,
"expiredate": null,
"creationuserid": 2,
"modificationuserid": 2,
"staticgroup": false,
"contactgroupstatus": null
}
]POST | Create static audience
/v19/audiences/audience/createCreates a new static audience in a specific database. You can optionally set an expiration date for the audience.
Request body
{
"name": "Audience 1",
"iddatabase": 1,
"expireDate": "1769442767000"
}Example responses
200 - Create static audience
{
"idaudience": 130
}DELETE | Delete static audience
/v19/audiences/audience/:idaudienceDeletes an existing audience. Before deletion, the system checks if the audience is currently in use within the platform (e.g., in Journeys, Workflow limits, or as a target for other audiences). If it is in use, the deletion will fail with a list of references where the audience is used.
Path variables
| Variable | Description |
|---|---|
idaudience |
The unique integer ID of the audience to delete. |
Web Tracking
GET | Get web tracking for contact
/v19/webtracking/contact/:idcontactGet web tracking information for a contact by ID
Path variables
| Variable | Description |
|---|---|
idcontact |
Example responses
200 - Success Response
{
"idcontact": 1,
"email": "contact@example.com",
"name": "John Doe",
"visits": [
{
"visitId": "v123456",
"date": "2023-06-15T10:30:00.000Z",
"url": "https://example.com/products",
"referrer": "https://google.com",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
"ipAddress": "192.168.1.1",
"duration": 120,
"pageViews": 3
},
{
"visitId": "v123457",
"date": "2023-06-16T14:45:00.000Z",
"url": "https://example.com/checkout",
"referrer": "https://example.com/products",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
"ipAddress": "192.168.1.1",
"duration": 180,
"pageViews": 5
}
],
"totalVisits": 2,
"lastVisitDate": "2023-06-16T14:45:00.000Z"
}GET | Query web tracking contacts
/v19/webtracking/contacts?query=select * from contacts where iddatabase=7Query web tracking information for contacts using a query string
Writing queries
See the Query documentation for more details.
Query parameters
| Parameter | Description |
|---|---|
query |
select * from contacts where iddatabase=7 |
Example responses
200 - Success Response
{
"contacts": [
{
"idcontact": 1,
"email": "contact@example.com",
"name": "John Doe",
"lastVisitDate": "2023-06-16T14:45:00.000Z",
"totalVisits": 2,
"lastUrl": "https://example.com/checkout"
},
{
"idcontact": 2,
"email": "contact2@example.com",
"name": "Jane Doe",
"lastVisitDate": "2023-06-17T09:15:00.000Z",
"totalVisits": 3,
"lastUrl": "https://example.com/checkout/confirmation"
}
],
"totalResults": 2,
"page": 1,
"pageSize": 10,
"totalPages": 1
}Insights
GET | Communication summary
/v19/insights/newsletter/:idnewsletter?channel=whatsappbusinessGet a summary of communication statistics with optional parameters. If the communication is archived, requests for a detailed contacts report (i.e., including \query\ or \idaudience\ parameters) will return a 400 Bad Request error.
The NaN value in rates, indicates that the rate cannot be computed because the denominator is zero.
Path variables
| Variable | Description |
|---|---|
idnewsletter |
53 |
Query parameters
| Parameter | Description |
|---|---|
channel |
Channel to filter by: email, sms, fax, or a custom channel name (default: first available channel for the newsletter) |
Example responses
200 - Communication summary
{
"idnewsletter": 762,
"channel": "email",
"firstSentAt": 1709274646985,
"lastSentAt": 1709275053263,
"deliveryRate": 98.16,
"bounceRate": 1.84,
"openRate": 9.79,
"clickToOpenRate": 13.04,
"clickRate": 1.28,
"conversionRate": 0,
"clickPerClicked": 152.33,
"conversionToClickRate": 0.36,
"reachedRate": 98.16,
"openersRate": 9.79,
"clickersToOpenersRate": 13.04,
"clickersRate": 1.28,
"convertersRate": 0,
"messagesSent": 22262,
"messagesReceived": 21852,
"messagesOpened": 2140,
"messagesUnreliableOpened": 3418,
"messagesClicked": 279,
"messagesConverted": 1,
"messagesWithUnsubscribeClicks": 24,
"messagesWithSpamReports": 0,
"messagesForwarded": 0,
"messagesHardBounced": 14,
"messagesSoftBounced": 396,
"recipients": 22262,
"reached": 21852,
"openers": 2140,
"unreliableOpeners": 3418,
"clickers": 279,
"converters": 1,
"unsubscribers": 24,
"spamReporters": 0,
"forwarders": 0,
"totalOpens": 3368,
"totalUnreliableOpens": 10290,
"totalClicks": 425,
"totalConversions": 1,
"totalUnsubscribes": 24,
"totalSpamReports": 0,
"totalForwards": 0,
"contents": [
{
"idcontent": 7001,
"name": "Product 2",
"clickers": 50,
"totalClicks": 64,
"messagesClicked": 50,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/ae1020_c-2218.html"
},
{
"idcontent": 6995,
"name": "Product 1",
"clickers": 103,
"totalClicks": 132,
"messagesClicked": 103,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/sr1001_c-2214.html"
},
{
"idcontent": 7000,
"name": "Pinterest",
"clickers": 2,
"totalClicks": 2,
"messagesClicked": 2,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.pinterest.com/example"
},
{
"idcontent": 6999,
"name": "Instagram",
"clickers": 2,
"totalClicks": 2,
"messagesClicked": 2,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.instagram.com/example"
},
{
"idcontent": 7002,
"name": "Product 2",
"clickers": 18,
"totalClicks": 23,
"messagesClicked": 18,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/sr1001_c-2117.html"
},
{
"idcontent": 6997,
"name": "https://www.example.com/nuova-collezione/",
"clickers": 105,
"totalClicks": 119,
"messagesClicked": 105,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/nuova-collezione/"
},
{
"idcontent": 6996,
"name": "Product 3",
"clickers": 73,
"totalClicks": 83,
"messagesClicked": 73,
"converters": 1,
"totalConversions": 1,
"messagesConverted": 1,
"url": "https://www.example.com/ae1020_c-2215.html"
}
],
"conversionGoalStats": []
}200 - Filtered by contacts's query
{
"idnewsletter": 53,
"channel": "email",
"firstSentAt": 1606217684913,
"lastSentAt": 1606234943583,
"deliveryRate": 100,
"bounceRate": 0,
"openRate": 0,
"clickToOpenRate": "NaN",
"clickRate": 0,
"conversionRate": 0,
"clickPerClicked": "NaN",
"conversionToClickRate": "NaN",
"reachedRate": 100,
"openersRate": 0,
"clickersToOpenersRate": "NaN",
"clickersRate": 0,
"convertersRate": 0,
"messagesSent": 3,
"messagesReceived": 3,
"messagesOpened": 0,
"messagesUnreliableOpened": 0,
"messagesClicked": 0,
"messagesConverted": 0,
"messagesWithUnsubscribeClicks": 0,
"messagesWithSpamReports": 0,
"messagesForwarded": 0,
"messagesHardBounced": 0,
"messagesSoftBounced": 0,
"recipients": 1,
"reached": 1,
"openers": 0,
"unreliableOpeners": 0,
"clickers": 0,
"converters": 0,
"unsubscribers": 0,
"spamReporters": 0,
"forwarders": 0,
"totalOpens": 0,
"totalUnreliableOpens": 0,
"totalClicks": 0,
"totalConversions": 0,
"totalUnsubscribes": 0,
"totalSpamReports": 0,
"totalForwards": 0,
"contents": [],
"conversionGoalStats": []
}200 - With conversion goals
{
"idnewsletter": 511,
"channel": "email",
"firstSentAt": 1725875118426,
"lastSentAt": 1725875118891,
"deliveryRate": 100,
"bounceRate": 0,
"openRate": 100,
"clickToOpenRate": 100,
"clickRate": 100,
"conversionRate": 100,
"clickPerClicked": 250,
"conversionToClickRate": 100,
"reachedRate": 100,
"openersRate": 100,
"clickersToOpenersRate": 100,
"clickersRate": 100,
"convertersRate": 100,
"messagesSent": 4,
"messagesReceived": 4,
"messagesOpened": 4,
"messagesUnreliableOpened": 0,
"messagesClicked": 4,
"messagesConverted": 4,
"messagesWithUnsubscribeClicks": 0,
"messagesWithSpamReports": 0,
"messagesForwarded": 0,
"messagesHardBounced": 0,
"messagesSoftBounced": 0,
"recipients": 4,
"reached": 4,
"openers": 4,
"unreliableOpeners": 0,
"clickers": 4,
"converters": 4,
"unsubscribers": 0,
"spamReporters": 0,
"forwarders": 0,
"totalOpens": 18,
"totalUnreliableOpens": 0,
"totalClicks": 10,
"totalConversions": 4,
"totalUnsubscribes": 0,
"totalSpamReports": 0,
"totalForwards": 0,
"contents": [
{
"idcontent": 1305,
"name": "Example.com",
"clickers": 1,
"totalClicks": 1,
"messagesClicked": 1,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com"
},
{
"idcontent": 1306,
"name": "Contact:CAMPO",
"clickers": 1,
"totalClicks": 2,
"messagesClicked": 1,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://[contact:CAMPO]"
}
],
"conversionGoalStats": [
{
"idgoal": 4,
"conversions": 4,
"conversionRate": 100,
"lastConversion": 1725877397000,
"totalValue": 468.99,
"averageValue": 117.2475,
"goalName": "Magento",
"currency": "€"
}
]
}GET | Communication summaries
/v19/insights/newsletters?queryNewsletter=SELECT * from NEWSLETTERS where template=0 AND sentdate > '{d 2025-07-01}'&channel=emailGet a list of communication summaries with optional parameters. If a communication is archived and contact-level details are requested (i.e., including query or idaudience parameters), that communication is automatically excluded from the result. If those parameters are not specified, aggregated statistics remain available even for archived communications.
Query parameters
| Parameter | Description |
|---|---|
queryNewsletter |
SQL-like query to filter newsletters (e.g. "SELECT * FROM NEWSLETTERS WHERE sent=true and sentDate >= today(-7)") |
channel |
Channel to filter by (email, sms, fax, or a custom channel name) |
Example responses
200 - Get Newsletter summary
[
{
"idnewsletter": 370,
"channel": "email",
"firstSentAt": 1752763608300,
"lastSentAt": 1752763608300,
"deliveryRate": 100.0,
"bounceRate": 0.0,
"openRate": 100.0,
"clickToOpenRate": 100.0,
"clickRate": 100.0,
"conversionRate": 0.0,
"clickPerClicked": 300.0,
"conversionToClickRate": 0.0,
"reachedRate": 100.0,
"openersRate": 100.0,
"clickersToOpenersRate": 100.0,
"clickersRate": 100.0,
"convertersRate": 0.0,
"messagesSent": 1,
"messagesReceived": 1,
"messagesOpened": 1,
"messagesUnreliableOpened": 0,
"messagesClicked": 1,
"messagesConverted": 0,
"messagesWithUnsubscribeClicks": 0,
"messagesWithSpamReports": 0,
"messagesForwarded": 0,
"messagesHardBounced": 0,
"messagesSoftBounced": 0,
"recipients": 1,
"reached": 1,
"openers": 1,
"unreliableOpeners": 0,
"clickers": 1,
"converters": 0,
"unsubscribers": 0,
"spamReporters": 0,
"forwarders": 0,
"totalOpens": 3,
"totalUnreliableOpens": 0,
"totalClicks": 3,
"totalConversions": 0,
"totalUnsubscribes": 0,
"totalSpamReports": 0,
"totalForwards": 0,
"contents": [
{
"idcontent": 1305,
"name": "Example.com",
"clickers": 1,
"totalClicks": 1,
"messagesClicked": 1,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0
},
{
"idcontent": 1306,
"name": "Contact:CAMPO",
"clickers": 1,
"totalClicks": 2,
"messagesClicked": 1,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0
}
],
"conversionGoalStats": []
}
]GET | Transactional summary
/v19/insights/transactional/:idnewsletter?conversiongoals=true&channels=emailRetrieves detailed insights and performance statistics for a specific transactional message. This endpoint provides delivery rates, engagement metrics (opens, clicks), and conversion data. It supports filtering by date range, specific contact criteria using a query, and specific communication channels.
The NaN value in rates, indicates that the rate cannot be computed because the denominator is zero.
The response is a JSON object containing:
-
idnewsletter: The unique identifier of the transactional message (template).
-
channels: A set of active communication channels for this transactional message (e.g., email, sms).
-
deliveryRate: The percentage of messages successfully delivered compared to the total sent.
-
bounceRate: The percentage of messages that bounced (hard or soft).
-
openRate: The percentage of delivered messages that were opened.
-
clickToOpenRate: The percentage of unique openers who also clicked at least one link.
-
clickRate: The percentage of delivered messages that resulted in at least one click.
-
conversionRate: The percentage of delivered messages that resulted in a conversion.
-
clickPerClicked: The average number of clicks per unique clicker.
-
conversionToClickRate: The percentage of unique clickers who also converted.
-
messagesSent: Total number of messages sent.
-
messagesReceived: Total number of messages successfully delivered.
-
messagesOpened: Number of unique messages opened.
-
messagesUnreliableOpened: Number of messages with "unreliable" opens (e.g., detected via machine opens).
-
messagesClicked: Number of unique messages that had at least one click.
-
messagesConverted: Number of unique messages that resulted in a conversion.
-
messagesWithUnsubscribeClicks: Number of unique messages that led to an unsubscribe click.
-
messagesWithSpamReports: Number of unique messages that were reported as spam.
-
messagesHardBounced: Total number of hard bounces.
-
messagesSoftBounced: Total number of soft bounces.
-
totalOpens: Total number of open events recorded.
-
totalUnreliableOpens: Total number of unreliable open events recorded.
-
totalClicks: Total number of click events recorded across all links.
-
totalConversions: Total number of conversion events recorded.
-
totalUnsubscribes: Total number of unsubscriptions.
-
totalSpamReports: Total number of spam complaints.
-
contents: A list of objects representing performance for each individual link in the message, each containing:
- idcontent: Unique identifier of the content/link.
- name: Name or label of the link.
- url: The actual URL of the link.
- clickers: Number of unique contacts who clicked this link.
- totalClicks: Total number of clicks for this link.
- messagesClicked: Number of unique message instances where this link was clicked.
- converters: Number of unique contacts who converted after clicking this link.
- totalConversions: Total number of conversions attributed to this link.
- messagesConverted: Number of unique message instances where a conversion was attributed to this link.
-
conversionGoalStats: A list of objects representing statistics for each conversion goal (included only if conversiongoals=true), each containing:
- idgoal: Unique identifier of the conversion goal.
- goalName: The name of the goal.
- conversions: Number of conversions for this goal.
- conversionRate: The conversion rate for this specific goal.
- lastConversion: The timestamp of the last recorded conversion for this goal.
- totalValue: The total monetary or numerical value of all conversions for this goal.
- averageValue: The average value per conversion.
- currency: The currency associated with the goal values.
Path variables
| Variable | Description |
|---|---|
idnewsletter |
Required. Id of the transactional message for which insights are requested. |
Query parameters
| Parameter | Description |
|---|---|
conversiongoals |
Optional. If set to true, the response will include detailed statistics for conversion goals associated with the transactional message. |
channels |
Optional. A comma-separated list of channels to filter the statistics (e.g., email,sms). |
Example responses
200 - Transactional summary
{
"idnewsletter": 512,
"channels": [
"email"
],
"deliveryRate": 99.82,
"bounceRate": 0.18,
"openRate": 21.45,
"clickToOpenRate": 18.52,
"clickRate": 3.97,
"conversionRate": 1.22,
"clickPerClicked": 138.4,
"conversionToClickRate": 30.73,
"messagesSent": 6250,
"messagesReceived": 6239,
"messagesOpened": 1338,
"messagesUnreliableOpened": 1520,
"messagesClicked": 248,
"messagesConverted": 76,
"messagesWithUnsubscribeClicks": 2,
"messagesWithSpamReports": 0,
"messagesHardBounced": 0,
"messagesSoftBounced": 11,
"totalOpens": 2345,
"totalUnreliableOpens": 4810,
"totalClicks": 343,
"totalConversions": 94,
"totalUnsubscribes": 2,
"totalSpamReports": 0,
"contents": [
{
"idcontent": 2101,
"name": "https://www.example.com/",
"clickers": 22,
"totalClicks": 30,
"messagesClicked": 22,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/"
},
{
"idcontent": 2102,
"name": "tiktok",
"clickers": 2,
"totalClicks": 2,
"messagesClicked": 2,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.tiktok.com/@example"
},
{
"idcontent": 2103,
"name": "https://shop.example.com/",
"clickers": 5,
"totalClicks": 5,
"messagesClicked": 5,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://shop.example.com/"
},
{
"idcontent": 3604,
"name": "Example Brand Made in Italy",
"clickers": 158,
"totalClicks": 235,
"messagesClicked": 164,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:checkout.checkouturl]"
},
{
"idcontent": 3605,
"name": "Product Item Fashion Black",
"clickers": 61,
"totalClicks": 71,
"messagesClicked": 61,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:item.link]"
}
],
"conversionGoalStats": [
{
"idgoal": 7,
"conversions": 88,
"conversionRate": 1.408,
"lastConversion": 1769105250000,
"totalValue": 9240.5,
"averageValue": 105,
"goalName": "Purchase (S)",
"currency": "€"
}
]
}GET | Transactional summaries
/v19/insights/transactionals?queryTransactional=SELECT * from NEWSLETTERS where idworkflow = 3&channel=emailRetrieves a list of performance summaries for a batch of transactional messages (or workflow messages or message on site messages). This endpoint allows for bulk retrieval of transactional statistics, enabling performance comparison across multiple templates. It requires a query to select which transactional messages to include and supports filtering the statistics themselves by date range, specific contact criteria, and communication channels.
The response is a JSON array of transactional summary objects. (see /insight/transactional/:idnewsletter endpoint for details)
Query parameters
| Parameter | Description |
|---|---|
queryTransactional |
SQL-like query to filter transactionals |
channel |
Channel to filter by (email, sms, fax, or a custom channel name) |
Example responses
200 - Transactional summaries
[
{
"idnewsletter": 412,
"channels": [
"email"
],
"deliveryRate": 99.72,
"bounceRate": 0.28,
"openRate": 25.10,
"clickToOpenRate": 30.85,
"clickRate": 7.74,
"conversionRate": 7.22,
"clickPerClicked": 142.15,
"conversionToClickRate": 93.30,
"messagesSent": 17200,
"messagesReceived": 17152,
"messagesOpened": 4305,
"messagesUnreliableOpened": 3820,
"messagesClicked": 1332,
"messagesConverted": 1243,
"messagesWithUnsubscribeClicks": 21,
"messagesWithSpamReports": 0,
"messagesHardBounced": 0,
"messagesSoftBounced": 48,
"totalOpens": 8950,
"totalUnreliableOpens": 14100,
"totalClicks": 1894,
"totalConversions": 2380,
"totalUnsubscribes": 21,
"totalSpamReports": 0,
"contents": [
{
"idcontent": 3101,
"name": "Pantaloni Sport Fashion Pro Gray",
"clickers": 220,
"totalClicks": 355,
"messagesClicked": 225,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:item.link]"
},
{
"idcontent": 3102,
"name": "https://www.example.com/",
"clickers": 30,
"totalClicks": 45,
"messagesClicked": 32,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/"
},
{
"idcontent": 3103,
"name": "Proceed to checkout",
"clickers": 915,
"totalClicks": 1510,
"messagesClicked": 965,
"converters": 915,
"totalConversions": 1510,
"messagesConverted": 965,
"url": "[temp:checkout.checkouturl]"
},
{
"idcontent": 3104,
"name": "https://shop.example.com/",
"clickers": 2,
"totalClicks": 2,
"messagesClicked": 2,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://shop.example.com/"
},
{
"idcontent": 3105,
"name": "Privacy Policy",
"clickers": 2,
"totalClicks": 2,
"messagesClicked": 2,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/privacy-policy"
}
],
"conversionGoalStats": []
},
{
"idnewsletter": 528,
"channels": [
"email"
],
"deliveryRate": 99.48,
"bounceRate": 0.52,
"openRate": 18.25,
"clickToOpenRate": 15.40,
"clickRate": 2.81,
"conversionRate": 2.15,
"clickPerClicked": 158.20,
"conversionToClickRate": 76.50,
"messagesSent": 5100,
"messagesReceived": 5073,
"messagesOpened": 926,
"messagesUnreliableOpened": 1180,
"messagesClicked": 143,
"messagesConverted": 109,
"messagesWithUnsubscribeClicks": 5,
"messagesWithSpamReports": 1,
"messagesHardBounced": 0,
"messagesSoftBounced": 27,
"totalOpens": 1580,
"totalUnreliableOpens": 3650,
"totalClicks": 226,
"totalConversions": 182,
"totalUnsubscribes": 5,
"totalSpamReports": 1,
"contents": [
{
"idcontent": 4125,
"name": "https://www.example.com/",
"clickers": 5,
"totalClicks": 6,
"messagesClicked": 5,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/"
},
{
"idcontent": 4504,
"name": "Example Brand Made in Italy",
"clickers": 92,
"totalClicks": 145,
"messagesClicked": 95,
"converters": 92,
"totalConversions": 145,
"messagesConverted": 95,
"url": "[temp:checkout.checkouturl]"
},
{
"idcontent": 4505,
"name": "Abbigliamento Fitness Green",
"clickers": 53,
"totalClicks": 82,
"messagesClicked": 53,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:item.link]"
}
],
"conversionGoalStats": []
},
{
"idnewsletter": 464,
"channels": [
"email"
],
"deliveryRate": 99.58,
"bounceRate": 0.42,
"openRate": 22.85,
"clickToOpenRate": 21.90,
"clickRate": 5.01,
"conversionRate": 4.52,
"clickPerClicked": 148.10,
"conversionToClickRate": 90.20,
"messagesSent": 6300,
"messagesReceived": 6274,
"messagesOpened": 1434,
"messagesUnreliableOpened": 1350,
"messagesClicked": 314,
"messagesConverted": 285,
"messagesWithUnsubscribeClicks": 15,
"messagesWithSpamReports": 1,
"messagesHardBounced": 2,
"messagesSoftBounced": 24,
"totalOpens": 2780,
"totalUnreliableOpens": 4650,
"totalClicks": 465,
"totalConversions": 510,
"totalUnsubscribes": 15,
"totalSpamReports": 1,
"contents": [
{
"idcontent": 5449,
"name": "Special Offer Example",
"clickers": 225,
"totalClicks": 340,
"messagesClicked": 230,
"converters": 225,
"totalConversions": 340,
"messagesConverted": 230,
"url": "[temp:checkout.checkouturl]"
},
{
"idcontent": 5787,
"name": "https://www.example.com/",
"clickers": 12,
"totalClicks": 16,
"messagesClicked": 12,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/"
},
{
"idcontent": 5769,
"name": "Fashion Top Black Edition",
"clickers": 68,
"totalClicks": 109,
"messagesClicked": 68,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:item.link]"
}
],
"conversionGoalStats": []
},
{
"idnewsletter": 531,
"channels": [
"email"
],
"deliveryRate": 99.81,
"bounceRate": 0.19,
"openRate": 20.15,
"clickToOpenRate": 19.50,
"clickRate": 3.93,
"conversionRate": 1.18,
"clickPerClicked": 140.80,
"conversionToClickRate": 30.25,
"messagesSent": 6100,
"messagesReceived": 6088,
"messagesOpened": 1227,
"messagesUnreliableOpened": 1450,
"messagesClicked": 239,
"messagesConverted": 72,
"messagesWithUnsubscribeClicks": 2,
"messagesWithSpamReports": 0,
"messagesHardBounced": 0,
"messagesSoftBounced": 12,
"totalOpens": 2150,
"totalUnreliableOpens": 4780,
"totalClicks": 336,
"totalConversions": 88,
"totalUnsubscribes": 2,
"totalSpamReports": 0,
"contents": [
{
"idcontent": 6137,
"name": "https://www.example.com/",
"clickers": 20,
"totalClicks": 28,
"messagesClicked": 20,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/"
},
{
"idcontent": 6140,
"name": "tiktok",
"clickers": 2,
"totalClicks": 2,
"messagesClicked": 2,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.tiktok.com/@example"
},
{
"idcontent": 6141,
"name": "https://shop.example.com/",
"clickers": 4,
"totalClicks": 4,
"messagesClicked": 4,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://shop.example.com/"
},
{
"idcontent": 6506,
"name": "Example Style Italy",
"clickers": 145,
"totalClicks": 225,
"messagesClicked": 150,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:checkout.checkouturl]"
},
{
"idcontent": 6507,
"name": "Bolero Top Jacket Black",
"clickers": 55,
"totalClicks": 82,
"messagesClicked": 55,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:item.link]"
}
],
"conversionGoalStats": []
},
{
"idnewsletter": 347,
"channels": [
"email"
],
"deliveryRate": 99.30,
"bounceRate": 0.70,
"openRate": 27.10,
"clickToOpenRate": 31.50,
"clickRate": 8.54,
"conversionRate": 7.85,
"clickPerClicked": 130.50,
"conversionToClickRate": 92.10,
"messagesSent": 19500,
"messagesReceived": 19363,
"messagesOpened": 5247,
"messagesUnreliableOpened": 4350,
"messagesClicked": 1654,
"messagesConverted": 1523,
"messagesWithUnsubscribeClicks": 38,
"messagesWithSpamReports": 0,
"messagesHardBounced": 65,
"messagesSoftBounced": 72,
"totalOpens": 10850,
"totalUnreliableOpens": 16200,
"totalClicks": 2158,
"totalConversions": 2850,
"totalUnsubscribes": 39,
"totalSpamReports": 0,
"contents": [
{
"idcontent": 7689,
"name": "instagram",
"clickers": 3,
"totalClicks": 4,
"messagesClicked": 3,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.instagram.com/examplecosmetics/"
},
{
"idcontent": 7690,
"name": "tiktok",
"clickers": 2,
"totalClicks": 3,
"messagesClicked": 2,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.tiktok.com/@example"
},
{
"idcontent": 7691,
"name": "https://shop.example.com/",
"clickers": 8,
"totalClicks": 10,
"messagesClicked": 8,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://shop.example.com/"
},
{
"idcontent": 7764,
"name": "Tuta Sportiva Pro Merlin",
"clickers": 225,
"totalClicks": 390,
"messagesClicked": 230,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:item.link]"
},
{
"idcontent": 7692,
"name": "Privacy Policy",
"clickers": 4,
"totalClicks": 5,
"messagesClicked": 4,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/privacy"
},
{
"idcontent": 7765,
"name": "Buy Now",
"clickers": 1012,
"totalClicks": 1650,
"messagesClicked": 1045,
"converters": 1012,
"totalConversions": 1650,
"messagesConverted": 1045,
"url": "[temp:checkout.checkouturl]"
},
{
"idcontent": 7687,
"name": "https://www.example.com/",
"clickers": 62,
"totalClicks": 78,
"messagesClicked": 62,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/"
}
],
"conversionGoalStats": []
},
{
"idnewsletter": 366,
"channels": [
"email"
],
"deliveryRate": 99.88,
"bounceRate": 0.12,
"openRate": 23.10,
"clickToOpenRate": 23.85,
"clickRate": 5.51,
"conversionRate": 4.90,
"clickPerClicked": 138.50,
"conversionToClickRate": 88.50,
"messagesSent": 7800,
"messagesReceived": 7791,
"messagesOpened": 1800,
"messagesUnreliableOpened": 1850,
"messagesClicked": 430,
"messagesConverted": 382,
"messagesWithUnsubscribeClicks": 4,
"messagesWithSpamReports": 0,
"messagesHardBounced": 0,
"messagesSoftBounced": 9,
"totalOpens": 3250,
"totalUnreliableOpens": 6400,
"totalClicks": 595,
"totalConversions": 680,
"totalUnsubscribes": 4,
"totalSpamReports": 0,
"contents": [
{
"idcontent": 8804,
"name": "Privacy Policy",
"clickers": 2,
"totalClicks": 2,
"messagesClicked": 2,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/legal/privacy"
},
{
"idcontent": 8770,
"name": "Pantaloni Sport Magenta",
"clickers": 82,
"totalClicks": 145,
"messagesClicked": 82,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "[temp:item.link]"
},
{
"idcontent": 8771,
"name": "Buy Now",
"clickers": 275,
"totalClicks": 420,
"messagesClicked": 288,
"converters": 275,
"totalConversions": 420,
"messagesConverted": 288,
"url": "[temp:checkout.checkouturl]"
},
{
"idcontent": 8799,
"name": "https://www.example.com/",
"clickers": 15,
"totalClicks": 22,
"messagesClicked": 15,
"converters": 0,
"totalConversions": 0,
"messagesConverted": 0,
"url": "https://www.example.com/"
}
],
"conversionGoalStats": []
}
]GET | Workflow summary
/v19/insights/workflow/:idworkflowRetrieves detailed insights and statistics for a specific workflow. This endpoint provides information such as total, active, and failed sessions, along with a breakdown of session exits by type and label. It supports filtering results by date range and by specific contact criteria using a query.
The response is a JSON array of WorkflowInsight objects. Each object contains:
-
idworkflow: The unique identifier of the workflow.
-
idjourney: The ID of the journey (campaign) associated with the workflow.
-
name: The name of the workflow.
-
status: The current status of the workflow (e.g., "active", "draft", "paused").
-
totalSessions: Total number of sessions started within the specified period and filters.
-
activeSessions: Number of sessions currently in progress.
-
errorSessions: Number of sessions that ended with an error status.
-
firstSessionDate: Timestamp of the first session found in the results.
-
lastSessionDate: Timestamp of the last session found in the results.
-
sessionExits: A list of objects representing how sessions ended, each containing:
- label: The label of the exit node in the workflow.
- exitType: The type of exit (positive, neutral, negative).
- count: The number of sessions that exited through this specific node.
Path variables
| Variable | Description |
|---|---|
idworkflow |
The unique identifier of the workflow for which insights are requested. |
Example responses
200 - Workflow summary
{
"idworkflow": 7,
"idjourney": 5,
"name": "Recover Missing Orders",
"status": "stopped",
"totalSessions": 10163,
"activeSessions": 0,
"errorSessions": 0,
"firstSessionDate": 1732921200000,
"lastSessionDate": 1734562800000,
"sessionExits": [
{
"label": "Recovered",
"exitType": "positive",
"count": 10002
},
{
"label": "Clicked to recover",
"exitType": "positive",
"count": 6
},
{
"label": "Exit without recovering",
"exitType": "negative",
"count": 155
}
]
}GET | Workflow summaries
/v19/insights/workflows?queryWorkflow=SELECT * FROM WORKFLOWS WHERE idcampaign = 123Retrieves detailed insights and statistics for a batch of workflows. This endpoint allows for bulk retrieval of workflow performance data, including session counts (total, active, error) and session exit breakdowns. It supports filtering both the set of workflows to analyze and the specific contact sessions to include in the statistics, within a defined date range.
The response is a JSON array of workflow insigiths objects. (see /insight/workflow/:idworkflow endpoint for details)
Query parameters
| Parameter | Description |
|---|---|
queryWorkflow |
An optional SQL-like query string to filter the list of workflows for which insights are requested. If omitted, it defaults to `SELECT * FROM WORKFLOWS`. The results are limited to a maximum of 100 workflows per request. |
Example responses
200 - Workflow summaries
[
{
"idworkflow": 11,
"idjourney": 7,
"name": "shopify",
"status": "active",
"totalSessions": 0,
"activeSessions": 0,
"errorSessions": 0,
"firstSessionDate": null,
"lastSessionDate": null,
"sessionExits": [
{
"label": "Default Exit",
"exitType": "neutral",
"count": 0
}
]
},
{
"idworkflow": 16,
"idjourney": 1,
"name": "dynamics",
"status": "active",
"totalSessions": 76,
"activeSessions": 2,
"errorSessions": 0,
"firstSessionDate": 1665439200000,
"lastSessionDate": 1689026400000,
"sessionExits": [
{
"label": "Success",
"exitType": "positive",
"count": 74
}
]
},
{
"idworkflow": 33,
"idjourney": 10,
"name": "Recover abandoned carts",
"status": "draft",
"totalSessions": 0,
"activeSessions": 0,
"errorSessions": 0,
"firstSessionDate": null,
"lastSessionDate": null,
"sessionExits": [
{
"label": "Purchase",
"exitType": "positive",
"count": 0
},
{
"label": "No purchase",
"exitType": "negative",
"count": 0
}
]
}
]Scheduled Works
This section describes the available REST API functions for retrieving data related to scheduled operations (called "Scheduled tasks" in magnews platform).
GET | Find scheduled work by id
/v19/scheduledworks/:idoperationFind a scheduled work by ID
Path variables
| Variable | Description |
|---|---|
idoperation |
1 |
Example responses
200 - Success Response
{
"idoperation": 1,
"name": "Daily Newsletter",
"description": "Send daily newsletter to subscribers",
"type": "email",
"status": "active",
"creationDate": "2023-01-15T10:30:00.000Z",
"lastExecutionDate": "2023-06-20T08:00:00.000Z",
"nextExecutionDate": "2023-06-21T08:00:00.000Z",
"schedule": {
"type": "daily",
"time": "08:00:00",
"timezone": "Europe/Rome"
},
"parameters": {
"idaudience": 1,
"idtemplate": 5
}
}GET | Trigger scheduled work
/v19/scheduledworks/:idoperation/trigger?delay=:delayTrigger a scheduled work by ID with optional delay.
Path variables
| Variable | Description |
|---|---|
idoperation |
Query parameters
| Parameter | Description |
|---|---|
delay |
Optional delay in minutes |
Example responses
200 - Success Response
{
"idoperation": 1,
"name": "Daily Newsletter",
"status": "triggered",
"executionTime": "2023-06-20T10:35:00.000Z",
"message": "Operation successfully triggered with 5 minutes delay",
"executionId": "exec-123456"
}Export
Using the Bulk Export API
If you need to export data from custom or system tables, use this API.
This endpoint executes a full query and returns the complete result set.
There is no pagination, but the result is streamed efficiently.
The response is encoded in CSV format with the following default settings:
- Encoding: UTF-8
-
Field separator:
;
- No field delimiter
-
Line separator: Windows (
\r\n)
You can customize these options via query parameters in the request body (see the examples requests for both POST and GET modes).
Writing queries
See the Query documentation for more details.
GET | Bulk download (get)
/v19/export/bulkdownload?query=SELECT * FROM CONTACTS LIMIT 100&lineSeparator=\n"ationMark="&encoding=UTF-8&fieldSeparator=,Download data using a MQL query (GET method).
See the Query documentation for more details on how to write queries.
Query parameters
| Parameter | Description |
|---|---|
query |
SELECT * FROM CONTACTS LIMIT 100 |
lineSeparator |
Optional line separator |
quotationMark |
Optional quotation mark |
encoding |
Optional encoding |
fieldSeparator |
Optional field separator |
Example responses
200 - Success Response
idcontact,email,name,surname,company,phone,status
1,"contact@example.com","John","Doe","Example Corp","+1234567890","active"
2,"contact2@example.com","Jane","Doe","Example Inc","+1987654321","active"POST | Bulk download (post)
/v19/export/bulkdownloadDownload data using a MQL query (POST method)
See the Query documentation for more details on how to write queries.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"query": "SELECT * FROM CONTACTS LIMIT 100",
"options": {
"lineSeparator": "\n",
"quotationMark": "\"",
"encoding": "UTF-8",
"fieldSeparator": ","
}
}Example responses
200 - Success Response
idcontact,email,name,surname,company,phone,status
1,"contact@example.com","John","Doe","Example Corp","+1234567890","active"
2,"contact2@example.com","Jane","Doe","Example Inc","+1987654321","active"Entities
An entity is a custom data table defined as User Entity on magnews.
Note: In the
:entityName parameter, use the name of the user entity, not the name of the underlying data table.GET | Find entity
/v19/entities/:entityName/dataFind an entity by name
Result: Returns an existing record.
The lookup is performed using the fields provided in the POST body, typically the table primary key or the user-defined primary key fields.
Path variables
| Variable | Description |
|---|---|
entityName |
products |
Example responses
200 - Success Response
{
"entityName": "products",
"fields": [
{
"name": "id",
"type": "integer",
"isPrimaryKey": true
},
{
"name": "name",
"type": "string",
"maxLength": 100
},
{
"name": "description",
"type": "string",
"maxLength": 500
},
{
"name": "price",
"type": "decimal",
"precision": 10,
"scale": 2
},
{
"name": "category",
"type": "string",
"maxLength": 50
},
{
"name": "creationDate",
"type": "datetime"
}
],
"totalRecords": 120,
"lastModifiedDate": "2023-06-15T10:30:00.000Z"
}POST | Merge entity
/v19/entities/:entityName/dataInsert or update a record in an entity table
Post body options
| Option | Type | Default Value | Description |
|---|---|---|---|
operationtype |
String | upsert |
Type of operation to perform. Possible values are: update, insert or upsert. |
Post body fields format
| Column data type | Entity field type | Example | Description |
|---|---|---|---|
| Text / Long text | "my string value" |
Double quoted string | |
| Integer (1 byte) | Integer | 1 |
Integer number |
| Integer (1 byte) | Checkbox | true |
Boolean value: true or false
|
| Integer (4 or 8 bytes) | 10 |
Integer or long number | |
| Decimal number |
"10.5" or "10,5"
|
Quoted string formatted according to current user's international settings | |
| Date | "24/06/2017" |
Quoted string formatted according to date format and time zone settings | |
| Date and time | "24/06/2017 10:17" |
Quoted string formatted |
Path variables
| Variable | Description |
|---|---|
entityName |
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"fields": {
"id": 1,
"updated_at": "25/05/2025 00:00"
}
}Example responses
200 - Success Upsert entity
{
"primarykey": {
"id": 1
},
"fields": {
"tax_amount": 0,
"item_discount_amount": 0,
"item_tax_amount": 0,
"discount_amount": 0,
"created_at": "14/05/2024 15:59",
"qty_ordered": 2,
"total_item_count": 0,
"tax_percent": 0,
"updated_at": "25/05/2025 00:00",
"price_incl_tax": 0,
"price": 74,
"product_id": 859,
"grand_total": 158,
"id": 1,
"idcontact": 500595,
"state": "complete",
"sku": "MP11-33-Brown",
"store_id": 1,
"coupon_code": null,
"item_id": 6,
"quote_id": 5,
"entity_id": 4,
"shipping_amount": 10,
"subtotal": 148,
"name": "Aether Gym Pant -33-Brown",
"customer_id": 2,
"order_currency_code": "USD",
"status": "complete"
}
}POST | Batch merge entity
/v19/entities/:entityName/batchdataCreate or update user entity instances from batch
Path variables
| Variable | Description |
|---|---|
entityName |
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"options":{
"operationtype":"upsert",
"fulldump":false
},
"entities":[
{
"primarykey": {
"myautoincprimarykey":1
},
"fields": {
"myuserprimarykey": 1234,
"mystringfield": "hello",
"myint": 1,
"mynumber": 10.05,
"mybool": true,
"mydatetime": "24/06/2021 10:05",
"mydate": "24/06/2021"
}
}
]
}Example responses
200 - Success Response
[
{
"entityName": "products",
"operationType": "upsert",
"result": "created",
"message": "Entity successfully created",
"id": 121,
"fields": {
"myuserprimarykey": 1234,
"mystringfield": "hello",
"myint": 1,
"mynumber": 10.05,
"mybool": true,
"mydatetime": "24/06/2021 10:05",
"mydate": "24/06/2021"
}
}
]Account
GET | Get residual credit
/v19/account/residualcredit/:channelGet the available credit for a channel (email or sms)
Allowed values for channel: email, sms.
Result: A number representing the residual credit.
- If credit is 1000, it returns a value approximated to the nearest thousand, rounding down.
- If credit is 0 or negative, it returns 0.
- For accounts with a flat plan, it returns residual credit plus automatic credit.
- For accounts with a final balance plan, it always returns \-1.
Path variables
| Variable | Description |
|---|---|
channel |
Example responses
200 - Success Response
{
"channel": "email",
"residualCredit": 50000,
"totalCredit": 100000,
"usedCredit": 50000,
"unit": "messages",
"lastUpdated": "2023-06-20T15:30:00.000Z"
}GET | Get user information
/v19/account/userinfoGet relevant information about the user profile associated with the current token and its account.
Example responses
200 - Success Response
{
"idaccount": 42,
"accountName": "SunnyWear",
"accountLogin": "sunnywear",
"iduser": 17,
"userName": "janedoe",
"emailAddress": "jane.doe@example.com",
"firstName": "Jane",
"lastName": "Doe",
"companyName": "SunnyWear Inc.",
"locale": "ENG",
"dateFormat": "dd/MM/yyyy",
"timeFormat": "HH:mm",
"dateTimeFormat": "dd/MM/yyyy HH:mm",
"roleName": "Administrator"
}MQL
Magnews Query Language is a meta sql language used to query system and custom table of a magnews account.
See the Query documentation for more details on how to write queries.
POST | Execute MQL select
/v19/mql/executeExecute an MQL select query. For update/insert/delete queries, use Execute MQL update endpoint.
Writing queries
See the Query documentation for more details on how to write queries.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"query": "select idcontact, email, data_ultima_modifica from contacts where data_ultima_modifica > ? and email like ?",
"options": {
"max": "10"
},
"parameters": ["15/07/2024 09:45", "%@example.com%"]
}Example responses
200 - Success Response
{
"recordCount": 10,
"columnNames": [
"idcontact"
],
"records": [
{
"record": [
{
"key": "idcontact",
"value": "1"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "2"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "3"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "4"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "5"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "6"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "37"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "38"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "68"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "69"
}
]
}
]
}500 - Bad query error
{
"error": "Internal Server Error",
"debugMessage": "bad query select * from contacts limit, parser error is: Encountered unexpected token:<EOF>\n at line 1, column 28.\n\nWas expecting one of:\n\n \":\"\n \"?\"\n \"ALL\"\n \"NULL\"\n <S_LONG>\n."
}200 - Query static audience members
{
"recordCount": 8,
"columnNames": [
"idcontact"
],
"records": [
{
"record": [
{
"key": "idcontact",
"value": "33"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "34"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "35"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "482470"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "482471"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "542425"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "542437"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "542438"
}
]
}
]
}200 - Query audiences
{
"recordCount": 10,
"columnNames": [
"idgroup",
"name",
"creationdate",
"lastmodificationdate"
],
"records": [
{
"record": [
{
"key": "idgroup",
"value": "1"
},
{
"key": "name",
"value": "%%dbreaders,suspended%%"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "02/09/2020 11:47"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "2"
},
{
"key": "name",
"value": "%%dbreaders,unsubscribed%%"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "02/09/2020 11:47"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "3"
},
{
"key": "name",
"value": "%%dbreaders,waiting%%"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "02/09/2020 11:47"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "4"
},
{
"key": "name",
"value": "%%dbreaders,all%%"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "02/09/2020 11:47"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "5"
},
{
"key": "name",
"value": "%%dbreaders,suspended%%"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "02/09/2020 11:47"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "6"
},
{
"key": "name",
"value": "%%dbreaders,unsubscribed%%"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "02/09/2020 11:47"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "7"
},
{
"key": "name",
"value": "%%dbreaders,waiting%%"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "02/09/2020 11:47"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "8"
},
{
"key": "name",
"value": "%%dbreaders,all%%"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "02/09/2020 11:47"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "9"
},
{
"key": "name",
"value": "Iscritti alla newsletter"
},
{
"key": "creationdate",
"value": "25/09/2018 08:16"
},
{
"key": "lastmodificationdate",
"value": "25/09/2018 08:16"
}
]
},
{
"record": [
{
"key": "idgroup",
"value": "10"
},
{
"key": "name",
"value": "Iscritti alla newsletter - Clienti"
},
{
"key": "creationdate",
"value": "25/09/2018 08:16"
},
{
"key": "lastmodificationdate",
"value": "25/09/2018 08:16"
}
]
}
]
}200 - Query workflows
{
"recordCount": 10,
"columnNames": [
"idworkflow",
"name",
"creationdate",
"idcampaign"
],
"records": [
{
"record": [
{
"key": "idworkflow",
"value": "1"
},
{
"key": "name",
"value": "magneto"
},
{
"key": "creationdate",
"value": "16/10/2015 08:25"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "5"
},
{
"key": "name",
"value": "dynamics"
},
{
"key": "creationdate",
"value": "17/05/2019 11:36"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "15"
},
{
"key": "name",
"value": "Magento Test Workflow"
},
{
"key": "creationdate",
"value": "26/07/2022 11:22"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "16"
},
{
"key": "name",
"value": "dynamics"
},
{
"key": "creationdate",
"value": "11/10/2022 09:50"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "19"
},
{
"key": "name",
"value": "Prova LinkedIn Stefic"
},
{
"key": "creationdate",
"value": "25/01/2023 09:16"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "20"
},
{
"key": "name",
"value": "Prova 2 LinkedIn Stefic"
},
{
"key": "creationdate",
"value": "25/01/2023 11:10"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "21"
},
{
"key": "name",
"value": "Shopify stefic"
},
{
"key": "creationdate",
"value": "17/03/2023 09:15"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "24"
},
{
"key": "name",
"value": "Prova stefic"
},
{
"key": "creationdate",
"value": "17/04/2023 14:48"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "25"
},
{
"key": "name",
"value": "prova aggiorna contatto"
},
{
"key": "creationdate",
"value": "17/04/2023 15:33"
},
{
"key": "idcampaign",
"value": "1"
}
]
},
{
"record": [
{
"key": "idworkflow",
"value": "29"
},
{
"key": "name",
"value": "New automated flow"
},
{
"key": "creationdate",
"value": "26/09/2023 14:41"
},
{
"key": "idcampaign",
"value": "1"
}
]
}
]
}200 - Query journeys
{
"recordCount": 2,
"columnNames": [
"idcampaign",
"name",
"status",
"creationdate",
"lastmodificationdate"
],
"records": [
{
"record": [
{
"key": "idcampaign",
"value": "1"
},
{
"key": "name",
"value": "My Campaign"
},
{
"key": "status",
"value": "active"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "10/07/2015 12:38"
}
]
},
{
"record": [
{
"key": "idcampaign",
"value": "4"
},
{
"key": "name",
"value": "Sito web | My Web Site"
},
{
"key": "status",
"value": "active"
},
{
"key": "creationdate",
"value": "10/07/2015 12:38"
},
{
"key": "lastmodificationdate",
"value": "10/07/2015 12:38"
}
]
}
]
}200 - Query workflow messages
{
"recordCount": 2,
"columnNames": [
"idnewsletter",
"name",
"template",
"subject",
"idworkflow"
],
"records": [
{
"record": [
{
"key": "idnewsletter",
"value": "24"
},
{
"key": "name",
"value": "Nuovo workflow #1 (email)"
},
{
"key": "template",
"value": "true"
},
{
"key": "subject",
"value": ""
},
{
"key": "idworkflow",
"value": "1"
}
]
},
{
"record": [
{
"key": "idnewsletter",
"value": "26"
},
{
"key": "name",
"value": "Nuovo workflow #2 (email)"
},
{
"key": "template",
"value": "true"
},
{
"key": "subject",
"value": ""
},
{
"key": "idworkflow",
"value": "1"
}
]
}
]
}200 - Query deliveries
{
"recordCount": 10,
"columnNames": [
"iddelivery",
"idnewsletter",
"startdate",
"emailchannelenabled",
"smschannelenabled",
"status",
"emailmessages",
"smsmessages",
"scheduletype",
"trial"
],
"records": [
{
"record": [
{
"key": "iddelivery",
"value": "2"
},
{
"key": "idnewsletter",
"value": "5"
},
{
"key": "startdate",
"value": "02/23/2017 13:13"
},
{
"key": "emailchannelenabled",
"value": "false"
},
{
"key": "smschannelenabled",
"value": "true"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "0"
},
{
"key": "smsmessages",
"value": "1"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "false"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "3"
},
{
"key": "idnewsletter",
"value": "6"
},
{
"key": "startdate",
"value": "02/23/2017 13:54"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "1"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "false"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "4"
},
{
"key": "idnewsletter",
"value": "7"
},
{
"key": "startdate",
"value": "01/11/2018 09:28"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "1"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "false"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "5"
},
{
"key": "idnewsletter",
"value": "8"
},
{
"key": "startdate",
"value": "02/06/2018 12:01"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "1"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "false"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "6"
},
{
"key": "idnewsletter",
"value": "19"
},
{
"key": "startdate",
"value": "05/17/2019 12:25"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "3"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "false"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "7"
},
{
"key": "idnewsletter",
"value": "25"
},
{
"key": "startdate",
"value": "06/20/2019 10:25"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "2"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "false"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "9"
},
{
"key": "idnewsletter",
"value": "34"
},
{
"key": "startdate",
"value": "06/26/2019 14:16"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "1"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "true"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "10"
},
{
"key": "idnewsletter",
"value": "34"
},
{
"key": "startdate",
"value": "06/26/2019 15:16"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "1"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "true"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "11"
},
{
"key": "idnewsletter",
"value": "34"
},
{
"key": "startdate",
"value": "06/26/2019 15:45"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "2"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "false"
}
]
},
{
"record": [
{
"key": "iddelivery",
"value": "12"
},
{
"key": "idnewsletter",
"value": "77"
},
{
"key": "startdate",
"value": "11/26/2019 12:16"
},
{
"key": "emailchannelenabled",
"value": "true"
},
{
"key": "smschannelenabled",
"value": "false"
},
{
"key": "status",
"value": "finished"
},
{
"key": "emailmessages",
"value": "1"
},
{
"key": "smsmessages",
"value": "0"
},
{
"key": "scheduletype",
"value": "single"
},
{
"key": "trial",
"value": "false"
}
]
}
]
}200 - Execute MQL select (with query parameters)
{
"recordCount": 10,
"columnNames": [
"idcontact",
"email",
"data_ultima_modifica"
],
"records": [
{
"record": [
{
"key": "idcontact",
"value": "2"
},
{
"key": "email",
"value": "anagramma@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "4"
},
{
"key": "email",
"value": "roni_cost@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "5"
},
{
"key": "email",
"value": "subscriber1@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "17"
},
{
"key": "email",
"value": "someonel1@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "18"
},
{
"key": "email",
"value": "someonel2@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "19"
},
{
"key": "email",
"value": "someonel3@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "20"
},
{
"key": "email",
"value": "someonel4@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "21"
},
{
"key": "email",
"value": "someonel5@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "22"
},
{
"key": "email",
"value": "someonel6@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
},
{
"record": [
{
"key": "idcontact",
"value": "23"
},
{
"key": "email",
"value": "someonel7@example.com"
},
{
"key": "data_ultima_modifica",
"value": "11/18/2025 12:53"
}
]
}
]
}POST | Execute MQL update/insert/delete
/v19/mql/updateExecute an MQL update query (update/insert/delete). For select queries use Execute MQL query endpoint.
⚠️ Update, insert and delete operations can only be performed on custom entities, not on system entities such as contacts or newsletters.
Headers
| Header | Value |
|---|---|
Content-Type |
application/json |
Request body
{
"query": "update orders set order_shipped=? where id=?",
"parameters": ["true", 13]
}Example responses
200 - Success Response
{
"updatedCount": 1
}Webhooks
Webhooks allow external systems to receive events from magnews in near real-time.
An external application must expose an HTTPS URL capable of receiving POST requests: for each event generated, magnews will send a request to that endpoint with the event data.
POST | Create webhook
/v19/webhooks/createRegisters a new webhook to receive magnews events in near real-time.
A webhook can be registered only if the URI provided meets these requirements:
- HTTPS with a valid certificate (TLS with a non-expired, non-self-signed certificate issued by a trusted CA)
- URI compliant with RFC 2396
- The endpoint must return HTTP 200 quickly (timeout: connection 1s, read 5s). Any other status code is treated as an error.
- Successful initial verification: before creating the subscription, magnews sends a test request to verify the endpoint.
Request body
{
"uri": "https://www.example.com/mywebhook_handler",
"topics": "contacts/update,contacts/delete"
}Example responses
200 - Success response
{
"id": 1,
"status": "active",
"uri": "https://www.example.com/mywebhook_handler",
"topics": "contacts/delete,contacts/update",
"digitalCertificateId": 2,
"creationDate": "14/11/2025 13:00",
"creationUserId": 3,
"lastModDate": "14/11/2025 13:00",
"lastModUserId": 3,
"lastExecDate": "",
"backoffDate": ""
}400 - Test request failed
{
"error": "test request failed",
"debugMessage": "HTTP 400 test request failed"
}POST | Update webhook
/v19/webhooks/updateUpdate a webhook subscription (uri, status, topics)
Request body
{
"id": 3,
"uri": "https://www.example.com/mywebhook_handler",
"topics": "contacts/update,contacts/delete",
"status": "suspended"
}Example responses
200 - Success response
{
"id": 3,
"status": "suspended",
"uri": "https://www.example.com/mywebhook_handler",
"topics": "contacts/delete,contacts/update",
"digitalCertificateId": 24,
"creationDate": "11/14/2025 13:53",
"creationUserId": 4,
"lastModDate": "11/14/2025 14:09",
"lastModUserId": 4,
"lastExecDate": "11/14/2025 14:08",
"backoffDate": "11/14/2025 14:38"
}GET | Get webhook
/v19/webhooks/:idFind a Webhook Subscription given its ID
Path variables
| Variable | Description |
|---|---|
id |
3 |
Example responses
200 - Success response
{
"id": 3,
"status": "active",
"uri": "https://www.example.com/mywebhook_handler",
"topics": "contacts/delete,contacts/update",
"digitalCertificateId": 24,
"creationDate": "11/14/2025 13:53",
"creationUserId": 4,
"lastModDate": "11/14/2025 13:56",
"lastModUserId": 2,
"lastExecDate": "11/14/2025 13:56",
"backoffDate": "11/14/2025 13:58"
}GET | List webhooks
/v19/webhooks/listList all Webhook Subscriptions
Example responses
200 - Success response
[
{
"id": 3,
"status": "active",
"uri": "https://www.example.com/mywebhook_handler",
"topics": "contacts/delete,contacts/update",
"digitalCertificateId": 24,
"creationDate": "11/14/2025 13:53",
"creationUserId": 4,
"lastModDate": "11/14/2025 13:58",
"lastModUserId": 2,
"lastExecDate": "11/14/2025 13:58",
"backoffDate": "11/14/2025 14:08"
}
]DELETE | Delete webhook
/v19/webhooks/delete/:idDeletes a Webhook Subscription given its ID
Path variables
| Variable | Description |
|---|---|
id |
id of the webhook subscription |
Example responses
204 - Success response
System
GET | Get api version
/v19Returns the API version
Example responses
200 - Success Response
v19