Skip to main content
Italiano
Help Desk

Contacts management

Updated

The following is a description of functions to manage contacts.

Contacts

Note: In all functions that support the specification of an ordered pair (field_name, field_value), when the field name is "flag_stato" it can be substituted with "status". In this case the field_value allowed are: "subscribed", "unsubscribed", "unconfirmed", "suspended".

subscribeContact

Warning: we strongly recommend you to use the mergeContact function instead of the subscribeContact function.

Creates a new contact in status active; if a contact with the same primary key already exists, this is updated.

Note
to check the result of the operation it is necessary to verify MNContactOperation.ok function, as this operation does not return any exception in case of errors for field's values, but it provides a very detailed description for any problem.
Parameter Type Description
idDatabase String Id returned by queryContactsByGroup or queryContactsByField.
values List of MNContactValue it is necessary to valorize the 'EMAIL' field.  
For list of values fields (multi values fields, multi relation fields) the values' separator is a comma.   For list of value fields it is also possible add or remove single values using the following syntax: #diff:++3,--2,--5 (or #diff:++three,--two,--five with lookuprelations option set to true), that means add to contact value 3 and remove values 2 and 5 (without touching the other values assigned to the contact)
options List of <Option> Available options:  
  • Boolean deny_update_contact: it prevents to update a contact;  
  • Boolean force_allow_restore_contact_on_update: it allows to reactivate a suspended or unsubscribed contact even if 'deny_update_contact' is set to 'true';  
  • Boolean deny_subscribe_newcontact: it prevents to subscribe new contacts;  
  • Boolean deny_subscribed_unsubscribed_contact: denies to reactivate already unsubscribed contacts  
  • Boolean sendemail: tells whether send or not a welcome message  
  • Integer idtemplate: welcome message template ID  
  • String sendemailonactions: list of comma separated MergeContact actions allowed to send the welcome message ("insert","update","delete","nothing","reactivate","restore","subscription_confirm", "suspend")  
  • String messageRetention: Specify a retention policy for the welcome message between "minimal" (discard the message body), "full" (keep the whole message and headers) and "reserved" (discard the recipient).  
  • String phonestrictvalidation: (default 'false') If 'true' enable a strict validation on cell numbers (i.e. cell number without international prefix will be discarded)  
  • String lookuprelations: (default 'false') If 'true' for every relation field a lookup on the table is done in order to use the logical primary key value of the table instead of the integer internal key  
  • Integer addToSimpleGroup: (default empty) If not empty the contact will be added to the given audience. The id must be a valid id of a static audience in the database of the contact. If the contact is already assigned to the audience no error is reported  
  • Integer removeFromSimpleGroup: (default empty) If not empty the contact will be remove from the given audience. The id must be a valid id of a static audience in the database of the contact. If the contact is not yet assigned to the audience no error is reported  
  • String storeEvent: This option requests to register an event. The only valid value is 'contactUnsubscribed'. You have to supply messageRef option as well.
  • String messageRef: Set the reference message onto which register the event requested by storeEvent option. You can get this value using [message:ref] placeholder

Return values: MNContactOperation

Permissions: Manage contacts of database

unsubscribeContact

Sets a contact to the status removed, so he/she will no longer receive communications.

Note:
to check the outcome of the operation is necessary to verify MNContactOperation.ok.
Normally this operation does not generate any error, except in case of errors in the field values. Anyway it provides a very detailed description for any problem.
Parameter Type Description
idDatabase String Id returned by queryContactsByGroup or queryContactsByField.
values List of ContactData At least you have to define the database primary key - e.g. the "EMAIL" field
options List of <Option>
  • Boolean sendemail: tells whether send or not an unsubscribe message  
  • Integer idtemplate: unsubscribe message template ID  
  • String sendemailonactions: list of comma separated MergeContact actions allowed to send the unsubscribe message ("insert","update","delete","nothing","reactivate","restore","subscription_confirm", "suspend")  
  • String messageRetention: Specify a retention policy for the unsubscribe message between "minimal" (discard the message body), "full" (keep the whole message and headers) and "reserved" (discard the recipient).  
  • String lookuprelations: (default 'false') If 'true' for every relation field a lookup on the table is done in order to use the logical primary key value of the table instead of the integer internal key  
  • Integer addToSimpleGroup: (default empty) If not empty the contact will be added to the given audience. The id must be a valid id of a static audience in the database of the contact. If the contact is already assigned to the audience no error is reported  
  • Integer removeFromSimpleGroup: (default empty) If not empty the contact will be remove from the given audience. The id must be a valid id of a static audience in the database of the contact. If the contact is not yet assigned to the audience no error is reported  
  • String storeEvent: This option requests to register an event. The only valid value is 'contactUnsubscribed'. You have to supply messageRef option as well.
  • String messageRef: Set the reference message onto which register the event requested by storeEvent option. You can get this value using [message:ref] placeholder
  • Boolean deny_update_contact: it prevents to update a contact;  
  • Boolean force_allow_restore_contact_on_update: it allows to reactivate a suspended or unsubscribed contact even if 'deny_update_contact' is set to 'true';  
  • Boolean deny_subscribe_newcontact: it prevents to subscribe new contacts;  
  • Boolean deny_subscribed_unsubscribed_contact: denies to reactivate already unsubscribed contacts  

Return values: MNContactOperation

Permissions: Manage contacts of database

mergeContact

Main function for contacts management, with which it is possible to:

  • Create a new contact
  • Update contact's data


The semantics of this function is:

  • Search contact by the primary key
  • If it exists, it tries an update
  • If it does not exist, it tries an insert
Note
  • to check the outcome of the operation is necessary to verify MNContactOperation.ok as this operation does not any except in case of errors in the field values, but it provides a very detailed description for any problem.
  • If you need to perform many consecutive requests of this operation (e.g. to implement data synchronization scenarios), it is useful to use the operation batchMergeContacts for a synchronous operation and startBatchContactsUpdate for an asynchronous operation.
  • a contact removal is achieved by setting the STATUS field to 'unsubcribed' (admitted values for this field are 'subscribed', 'unconfirmed', 'unsubscribed' and 'suspended') or by using unsubscribeContact.
  • for multi-value fields you need to format the value as CSV, using the comma as field separator and the double quotes as text delimiter - e.g. 'one', 'two', 'three'.
  • for multichannel accounts it is recommended to define a value for fields RICEVE_EMAIL, RICEVE_SMS e RICEVE_FAX, that are used to enable delivery through each channel - this operation has to be done as the system does not automatically enable the channel when a recipient is valued.
Parameter Type Description
idDatabase String Id returned by queryContactsByGroup or queryContactsByField.
values List of MNContactValue For list of values fields (multi values fields, multi relation fields) the values separator is a comma.  For list of value fields it is also possible add or remove single values using the following syntax: #diff:++3,--2,--5 (or #diff:++three,--two,--five with lookuprelations option set to true), that means add to contact value 3 and remove values 2 and 5 (without touching the other values assigned to the contact)
options List of <Option> Available options:
  • Boolean deny_update_contact: it prevents to update a contact;
  • Boolean force_allow_restore_contact_on_update: it allows to reactivate a suspended or unsubscribed contact even if 'deny_update_contact' is set to 'true';
  • Boolean deny_subscribe_newcontact: it prevents to subscribe new contacts;
  • Boolean deny_subscribed_unsubscribed_contact: denies to reactivate already unsubscribed contacts
  • Boolean sendemail: tells whether send or not a welcome message
  • Integer idtemplate: welcome message template ID
  • String sendemailonactions: list of comma separated MergeContact actions allowed to send the welcome message ("insert","update","delete","nothing","reactivate","restore","subscription_confirm", "suspend")
  • String messageRetention: Specify a retention policy for the welcome message between "minimal" (discard the message body), "full" (keep the whole message and headers) and "reserved" (discard the recipient).
  • String lookuprelations: (default 'false') If 'true' for every relation field a lookup on the table is done in order to use the logical primary key value of the table instead of the integer internal key
  • Integer addToSimpleGroup: (default empty) If not empty the contact will be added to the given audience. The id must be a valid id of a static audience in the database of the contact. If the contact is already assigned to the audience no error is reported
  • Integer removeFromSimpleGroup: (default empty) If not empty the contact will be remove from the given audience. The id must be a valid id of a static audience in the database of the contact. If the contact is not yet assigned to the audience no error is reported
  • String storeEvent: This option requests to register an event. The only valid value is 'contactUnsubscribed'. You have to supply messageRef option as well.
  • String messageRef: Set the reference message onto which register the event requested by storeEvent option. You can get this value using [message:ref] placeholder

Return values: MNContactOperation

Permissions: Manage contacts of database

deleteContacts

Permanently delete a list of contacts.

Warning: this operation is unrecoverable and deletes all data associated with contacts including audience and special lists information, wizards and web pages submissions.
Parameter Type Description
idContact List of <Integer> List of Contacts ID to be deleted

Return values: Void

Permissions: Manage contacts of database

batchMergeContacts

Has the same function as mergeContact, but it is applied in batch. It is recommended to optimize performance.

Note
even if this function allows a more efficient execution of the operation (by reusing data structures and connections on the server side), it is not recommended to request batches of more than 1000 items (please, contact the technical support for any further information or suggestion).

It is recommended to evaluate startBatchContactsUpdate to have an asynchronous management.

Parameter Type Description
idDatabase String Id returned by queryContactsByGroup or queryContactsByField.
values List of BatchMergeValues At least you have to define the database primary key - e.g. the "EMAIL" field
options List of <Option> Available options:  
  • Boolean deny_update_contact: it prevents to update a contact;  
  • Boolean force_allow_restore_contact_on_update: it allows to reactivate a suspended or unsubscribed contact even if 'deny_update_contact' is set to 'true';  
  • Boolean deny_subscribe_newcontact: it prevents to subscribe new contacts;  
  • Boolean deny_subscribed_unsubscribed_contact: denies to reactivate already unsubscribed contacts  

Return values: List of MNContactOperation

Permissions: Manage contacts of database

findContactById

Returns data of a contact from its internal id number.
If you need to perform many consecutive requests of this operation (e.g. to implement data synchronization scenarios), it is recommended to use the batchFindContactById function.

Parameter Type
idContact String

Return values: MNContact

Permissions: Export data of contacts of database

batchFindContactById

Returns data from multiple contacts using their internal id number.
The result includes only the contacts that are found in the database (therefore, the returned list may have fewer elements than the idContacts list).

Parameter Type
idContacts List of String

Return values: List of MNContact

Permissions: Export data of contacts of database

findContactByPrimaryKey

With a research by primary key filter it returns data for a contact in a Database.

Note
If you need to perform many consecutive requests of this operation (e.g. to implement data synchronization scenarios), it is recommended to use the batchFindContactByPrimaryKey function.
Parameter Type
idDatabase String
primaryKeyValue String

Return values: MNContact

Permissions: Export data of contacts of database

batchFindContactByPrimaryKey

With a research by primary key filter it returns data for several contacts in a database.
The result includes only contacts that are found in the database (therefore, the returned list may have fewer elements than the primaryKeyValues list).

Parameter Type
idDatabase String
primaryKeyValues List of String

Return values: List of MNContact

Permissions: Export data of contacts of database

batchFindContactByPrimaryKeyEx

Advanced version of batchFindContactbyPrimaryKey, it allows to specify some options.

Parameter Type Description
idDatabase String  
primaryKeyValues List of String  
options List of <Option> By defining the option 'only_system_fields' = 'true' for each contact will be uploaded only system fields (STATO, PRIMARYKEY, EMAIL, ...). This option is useful because it has faster execution and less data traffic on the network.

Return values: List of MNContact

Permissions: Export data of contacts of database

queryContacts

Returns a RowSet id with contacts matching the query specified.
If you want some RowSet's info, see Utility

Parameter Type Description
idDatabase String  
query String It only accepts queries with 'select *', it doesn't accept queries that specify field names.
Query examples:  
SELECT * FROM CONTACTS WHERE email = 'name@domain.com'  
SELECT * FROM CONTACTS WHERE email = 'name@domain1.com' OR email = 'name@domain2.com'  
SELECT * FROM CONTACTS WHERE name LIKE 'myname'  
SELECT * FROM CONTACTS WHERE name LIKE '%mynameendwith'  
SELECT * FROM CONTACTS WHERE name LIKE 'mynamestartswith%'  
SELECT * FROM CONTACTS WHERE name LIKE '%mynamecontains%'  
SELECT * FROM CONTACTS WHERE status = 'subscribed' /*active contacts*/  
SELECT * FROM CONTACTS WHERE status = 'unsubscribed' /*unsubscirbed contacts*/  
SELECT * FROM CONTACTS WHERE status = 'suspended' /*sospende contacts*/  
SELECT * FROM CONTACTS WHERE status = 'unconfirmed' /*unconfirmed contacts*/  
SELECT * FROM CONTACTS WHERE iddatabase = 1 /*contacts on database with id=1*/  
SELECT * FROM CONTACTS WHERE idcontact = 1 /*contact with id=1*/  
SELECT * FROM CONTACTS WHERE SLISTSUBSCRIPTION.LIST_14.SUBCRIPTIONSTATUS = 'SUBSCRIBED' /*contacts subscribed to special list with id=14*/  
SELECT * FROM CONTACTS WHERE SLISTSUBSCRIPTION.LIST_14.SUBCRIPTIONDATE >= '{ts 2013-01-01 00:00:00}' /*contacts subscribed in 2013 and after*/  
options List of <Option> Boolean only_system_fields: if 'true' for each contact will be uploaded only system fields (STATO, PRIMARYKEY, EMAIL, ...).

Return values: String

Permissions: Export data of contacts of all databases

countContacts

Counts contacts by a given query

Parameter Type Description
idDatabase String  
query String Query examples:  
SELECT COUNT(*) FROM CONTACTS WHERE email = 'name@domain.com'  
SELECT COUNT(*) FROM CONTACTS WHERE email = 'name@domain1.com' OR email = 'name@domain2.com'  
SELECT COUNT(*) FROM CONTACTS WHERE name LIKE 'myname'  
SELECT COUNT(*) FROM CONTACTS WHERE name LIKE '%mynameendwith'  
SELECT COUNT(*) FROM CONTACTS WHERE name LIKE 'mynamestartswith%'  
SELECT COUNT(*) FROM CONTACTS WHERE name LIKE '%mynamecontains%'  
SELECT COUNT(*) FROM CONTACTS WHERE status = 'subscribed' /*active contacts*/  
SELECT COUNT(*) FROM CONTACTS WHERE status = 'unsubscribed' /*unsubscirbed contacts*/  
SELECT COUNT(*) FROM CONTACTS WHERE status = 'suspended' /*sospende contacts*/  
SELECT COUNT(*) FROM CONTACTS WHERE status = 'unconfirmed' /*unconfirmed contacts*/  
SELECT COUNT(*) FROM CONTACTS WHERE iddatabase = 1 /*contacts on database with id=1*/  
SELECT COUNT(*) FROM CONTACTS WHERE idcontact = 1 /*contact with id=1*/  

Return values: Integer

Permissions: Export data of contacts of all databases

queryContactsByField

Returns a contacts Rowset id by searching on a field, with the same procedures of findContactsByField.
If you want some RowSet's info, see Utility

Parameter Type
idDatabase String
fieldName String
operator String
value String

Return values: String

Permissions: Export data of contacts of database

queryContactsByGroup

Returns a RowSet id with an audience contacts.
If you want some RowSet's info, see Utility

Parameter Type
idGroup String

Return values: String

Permissions: Export data of contacts of database

queryContactsByList

Returns a RowSet id with contacts subscribed to a list.

Note
these are contacts that belong to the audience associated to the list, i.e. they are explicitly subscribed to the list. In case of an 'extended' list, contacts are joined to those that are in the list target, excluding those that are explicitly removed.
If you want some RowSet's info, see Utility
Parameter Type
idDatabase String
idlist String

Return values: String

Permissions: Export data of contacts of database

queryContactsByFilter

Returns a RowSet ID with contacts that match the filter.

Parameter Type Description
idDatabase String  
filter Filter  
orderBy String Available values: DATA_ULTIMA_MODIFICA (last modification date) and DATA_ISCRIZIONE (subscription date); optional
asc Boolean Used for orderBy; optional, default false
options List of <Option> Available option: 'only_system_fields', return only system fields
credentials Credentials  

Return values: String

Permissions: Export data of contacts of database

fetchContacts

Returns a page of contacts.

Parameter Type Description
idRowSet String Id returned by queryContactsByGroup or queryContactsByField.
fromIndex Int  
toIndex Int  

Return values: MNContact

Permissions: Export data of contacts of database

findContactsByField

Returns a contacts list by searching on a field.

Parameter Type Description
idDatabase String  
fieldName String Corresponds to the 'name' field, not to the descriptive label.
operator String Filter
value String Is the value string conversion according to the international settings of the use.

Return values: List of MNContact

Permissions: Export data of contacts of database

batchFindContactByFilter

With a generic filter it returns data of several contacts in a database.

Parameter Type
idDatabase String
filter Filter
options List of <Option>

Return values: List of MNContact

Permissions: Export data of contacts of database

getAllDeliverabilityClusters

Delivery clusters are used to classify contacts in "engagement" clusters using a specific policy or web domain. This function retrieve all delivery clusters defined for this account. Results can be used to update contacts, to evaluate the field "IDDELIVERYCLUSTER" in structure MNContactValue

Parameter Type
options List of <Option>

Return values: List of MNDeliverabilityCluster

Databases

findFieldByName

Returns the definition for a field in a DB contacts.

Parameter Type Description
idDatabase String Shared fields have parameter idDatabase = '0'
name String Refers to the field id, not to its description

Return values: MNFieldInfo

Permissions: Manage fields of database

createField

Creates a new field for a specific database (or a shared field).

Parameter Type Description
idDatabase String To create a shared field you must indicate idDatabase = '0'
label String  
name String The value of the parameter name is unique in the system, there cannot be more fields with the same name
dataType String For the dataType list you can refer to the data structures reference
subDataType String For the subDataType list you can refer to the data structures reference
fieldOptions MNFieldOptions You can indicate the list of possible values for the fields bound (e.g. enum)
options List of <Option> You can use the option 'nofilter=true' to hide this new field from filters. You can use the option "usage" to define the usage of field:  
usage = 1 indicates field is used for contact's personal data  
usage = 2 indicates field is used for profiling data  
usage = 3 indicates field is used for audiences creation  
usage = other values indicates field is used for a custom audience (audiences must be created manually) 
You can use the option "relationEntityTable" to specify the custom table name for fields with dataYype TYPE_SIMPLERELATION and TYPE_SIMPLEMULTIRELATION

Return values: String name

Permissions: Manage fields of database

updateField

Modify a field for a specific database (or a shared field).

Parameter Type Description
idDatabase String To update a shared field you must indicate idDatabase = '0'
name String The value of the parameter name refers to the field ID that is unique in the system; there cannot be more fields with the same ID
fieldOptions MNFieldOptions You can specify the list of possible values of the field (e.g. enum).
If this parameter is empty (different from null), the list of values will be empty.
If this parameter equals null, the list of values will not be changed.
Passing only values:
  • The operation fails if the list of passed values does not include all those already present (match case sensitive on value) which are used by a contact or in the definition of an audience.
Passing ids and values:
  • The operation fails if the list of passed ids and values does not include all those already present (match case on id) which are used by a contact or in the definition of an audience.
  • The operation renames values that have a different name.
options List of <Option> You have the following options:  
minLength: minimum length  
maxLength: maximum length  
label: field label  
name: ID of the field - note: if the field is used by the placeholder - e.g. [mnNAME] - the modification involves an update of all the audiences and content

Return values: MNAlterSchemaResult

Permissions: Manage fields of database

findDatabaseById

Returns basic information about a Database

Parameter Type
idDatabase String

Return values: MNDatabaseInfo

Permissions: Use of database

getAllDatabases

Returns basic information about all Databases visible by this user (permission use database)

Parameter Type Description
options List of <Option> None options yet  

Return values: List of MNDatabaseInfo

Permissions: Use of each database

getFieldsByDatabase

Returns the definition of all fields for a Database

Parameter Type
idDatabase String

Return values: List of MNFieldInfo

Permissions: Manage fields of database

Audiences

createSimpleGroup

Creates an audience of contacts based on a simple filter 'FIELD OP VALUE' (e.g. SubscribedXX = true)

Parameter Type Description
idDatabase String  
groupName String  
fieldName String  
operator String For a list of operators please refer to the appendix
value String The value is converted into a string according to the international settings of the user
idParentGroup String indicates a possible parent audience for the new audience. If empty or null the new audience will be created as a subordinate audience of the database's principal audience

Return values: String idgroup

Permissions: Manage audiences of database

createSimpleStaticGroup

Creates a static audience of contacts. Use this method when implementing bulk load and send operations. A static audience does not use contact fields and so it does not slow down any find/update operation on contacts. In order to add contacts to the audience use the addDataToContactsRowsSet set of operations.

While creating a static audience consider adding the special option "autoexpire" = "true" in order to let the system drop the audience once is has been used for delivery purposes, this will preserve your account's database performances.

Parameter Type Description
idDatabase String  
groupName String  
options List of <Option> Available options:  
Boolean autoexpire: enable auto deletion of the audience after an expiriration date  
Timestamp expiredate: expire date of the static audience, if not given a default value will be set, considering global settings. For the format see formatting date-times.

Return values: String idgroup

Permissions: Manage audiences of database

findGroupById

Returns basic information about an audience of contacts

Parameter Type
idGroup String

Return values: MNGroupInfo

Permissions: Manage audiences of database

deleteGroup

Marks an audience of contacts as 'deleted'. It will not be shown any more in lists or returned from getGroupsByDatabase and queryGroups

Parameter Type
idGroup String

Return values: Void

Permissions: Manage audiences of database

getGroupsByDatabase

Returns basic information about all the audiences defined in a database.

Parameter Type
idDatabase String

Return values: List of MNGroupInfo

Permissions: Manage audiences of database

queryGroups

Returns basic information about some audiences defined in a database, searching with a query.
If you want some RowSet's info, see Utility

Parameter Type Description
idDatabase String  
query String Query examples on groups: 
SELECT * FROM GROUPS WHERE name = 'mygroup'  
SELECT * FROM GROUPS WHERE name LIKE '%mygroup'  
SELECT * FROM GROUPS WHERE idgroup = 1  
options List of <Option>  

Return values: List of MNGroupInfo

Permissions: Manage audiences of database (for each different database)

createStaticGroupFromQuery

Adds contacts to a static audience based on a custom query, the contacts are added to the audience once: the audience is not dynamic, if in the future some contact will match the query it won't be added to the audience automatically.
A new audience will be created on the fly.
The return value is an id of a batch operation, the status of which must be polled using the getBatchStatusInfo operation, the id of the created audience will be found inside the info field.

Parameter Type Description
idDatabase String  
query String Query examples on contacts: 
SELECT * FROM CONTACTS WHERE name = 'mycontact'  
SELECT * FROM CONTACTS WHERE status = 'suspended'  
options List of <Option>
  • String groupName: The name of the audience which has to be created on-the-fly  
  • Boolean autoexpire: Set it to true in order to create an self-destructable audience  
  • Timestamp expiredate: expire date of the static audience, if not given a default value will be set, considering global settings. For the format see formatting date-times.
  • String groupId: The id of a preexisting audience  

Return values: String

Permissions: Manage audiences of database (for each different database)

createDynamicGroupFromQuery

Creates a dynamic audience based on a custom query, this audience is dynamic, that is the query is executed whenever the user/system lists the content of the audience.
The return value is an id of a new created audience.

Parameter Type Description
idDatabase String  
query String Query examples on contacts: 
SELECT * FROM CONTACTS WHERE name = 'mycontact'  
SELECT * FROM CONTACTS WHERE status = 'suspended'  
options List of <Option>
  • String groupName: The name of the audience which has to be created on-the-fly  
  • String idParent: The id of parent audience  

Return values: String

Permissions: Manage audiences of database (for each different database)

createStaticGroupFromNewsletterTarget

Adds contacts to a static audience based on the target of a communication.
Considered target is email receivers only (no SMS nor faxes).
A new audience will be created on the fly.
The return value is an id of a batch operation, the status of which must be polled using the getBatchStatusInfo operation, the id of the created audience will be found inside the info field.

Parameter Type Description
idNewsletter String  
options List of <Option>
  • String groupName: The name of the audience which has to be created on-the-fly  
  • Boolean autoexpire: Set it to true in order to create an self-destructable audience  
  • Timestamp expiredate: expire date of the static audience, if not given a default value will be set, considering global settings. For the format see formatting date-times.
  • String groupId: The name of a preexisting audience  
  • String idDelivery: Consider the target for a specific delivery only  
  • String idDatabase: Add contacts belonging to a specific database only  
  • String queryFilter: A custom query as additional filter  
  • String statsFilter: Only adds contacts which has generated the requested communication event (bounced, received, opened, clicked, converted, unsubscribed, complained)  

Return values: String

Permissions: Manage audiences of database (for each different database)

Special lists

subscribeContactToList

Adds a contact to a list.

Note
to check the result of the operation is necessary to verify MNContactOperation.ok as this operation does not return any except in case of errors in the field values, but it provides a very detailed description for any problem.
Parameter Type Description
idDatabase String Id returned by queryContactsByGroup or queryContactsByField.
primaryKeyValue String At least you have to define the database primary key - e.g. the "EMAIL" field
idList String  
idSubscriptionCause String describes a contact origin, it is a numeric id that can be left empty or null

Return values: MNContactOperation

Permissions: Manage special lists of database and manage contacts of database

batchSubscribeContactToList

Joins contacts to the special list.

Parameter Type
idDatabase String
primaryKeyValues List of String
idList String
idSubscriptionCause String

Return values: MNContactOperation

Permissions: Manage special lists of database and manage contacts of database

unsubscribeContactFromList

Deletes a contact from a list.

Note :
to check the result of the operation is necessary to verify MNContactOperation.ok as this operation does not return any except in case of errors in the field values, but it provides a very detailed description for any problem.
Parameter Type Description
idDatabase String Id returned by queryContactsByGroup or queryContactsByField.
primaryKeyValue String At least you have to define the database primary key - e.g. the "EMAIL" field
idList String At least you have to define the database primary key - e.g. the "EMAIL" field
idUnsubscriptionCause String describes the cause of the unsubscription, it is a numeric id that can be left empty or null

Return values: MNContactOperation

Permissions: Manage special lists of database and manage contacts of database

batchUnsubscribeContactFromList

As unsubscribeContactFromList but it is executed for a batch of contacts.

Parameter Type
idDatabase String
primaryKeyValues List of String
idList String
idUnsubscriptionCause String

Return values: List of MNContactOperation

Permissions: Manage special lists of database and manage contacts of database

createSimpleList

Creates a simple list of type 'only opt-in'. The return value is id of the new list.

Parameter Type
idDatabase String
name String
options List of <Option>

Return values: String

Permissions: Manage special lists of database

getListsByDatabase

Returns basic information on all the lists defined within a database.

Parameter Type
idDatabase String

Return values: MNList

Permissions: Manage special lists of database

findListById

Returns the basic information on a list.

Parameter Type
idDatabase String
idList String

Return values: MNList

Permissions: Manage special lists of database

updateList

Modifies a list.

Parameter Type Description
idDatabase String ID of the database who the list belongs.
idList String ID of the list to be updated
options List of <Option> Available options:  
String name: list name  
String description: list description

Return values: String

Permissions: Manage special lists of database

findContactListSubscriptionToList

Returns a list subscription status of a contact.

Parameter Type
idDatabase String
primaryKeyValue String
idList String

Return values: MNContactListSubscriptionInfo

Permissions: Manage special lists of database and manage contacts of database

batchFindContactListSubscriptionToList

As findContactListSubscriptionToList but it is executed for a batch of contacts.

Parameter Type
idDatabase String
primaryKeyValues List of String
idList String

Return values: List of MNContactListSubscriptionInfo

Permissions: Manage special lists of database and manage contacts of database

Asynchrounous batch contact updates

createContactRowSet

Opens a RowSet on the server to contain contacts data that have to be uploaded/updated.

Return values: String

addDataToContactsRowsSet

Adds contacts data to the rowset.

Parameter Type
idRowSet String
data List of RawContactData
options List of <Option>

Return values: String

addDataToContactsRowsSetFromFile

Adds contacts data to the rowset reading a file - that can be a .CSV file (or other format) - according to the settings specified in in FileOptions (field separator, lines, file format, ...).
By default the file must be in CSV format with these parameters:

  • windows-1252 - as encoding
  • double quotes - as text qualifier
  • , - as field separator
  • CRLF (sequence of two bytes \r\n) - as rows separator

These settings can be overridden with the parameter "fileOptions" in FileOptions

Parameter Type Description
idRowSet String  
data Byte[] File to import
fileOptions FileOptions  
options List of <Option>  

Return values: String

startBatchContactsUpdate

Starts a batch operation (in the background) to update contacts.
This operation returns an id useful to get the operation status with getBatchStatusInfo.
Inside the MNBatchStartOptions structure you can set the iddatabase to be used as default for each contact, if not given iddatabase will default to '1'. You can set the IDDATABASE field for each record in order to work on multiple databases  If you want to add every updated/inserted contact in a static audience (see createSimpleStaticGroup) fill the addContactsToSimpleStaticGroup and idGroup properties

Parameter Type Description
idRowSet String  
options MNBatchStartOptions For more information about the available options see MNBatchStartOptions
advancedOptions List of <Option> Available options:  
Boolean deny_update_contact: it prevents to update a contact;  
Boolean force_allow_restore_contact_on_update: it allows to reactivate a suspended or unsubscribed contact even if 'deny_update_contact' is set to 'true';  
Boolean deny_subscribe_newcontact: it prevents to subscribe new contacts;  
Boolean deny_subscribed_unsubscribed_contact: it allows the modification only for existing contacts  
Boolean serialmode: enable optimizations for the case of single execution of this kind of operation. Warning: if you execute multiple concurrent operations with serialmode some of them could end in error status  
Boolean keepSourceData: keep a copy of the source data, for debug purposes only, defaults to 'false';  

Return values: String

Permissions: Manage contacts of database

getBatchStatusInfo

Returns the status of an update contacts operation. The field reportRowsSetId indicates the rowset id that contains the details of processing.
The number of records reported in the structure corresponds to the number of records processed, not necessarily the number of contacts updated or inserted.
To see the result in detail is necessary to use the fetchBatchContactsUpdateReport or fetchBatchCustomDataUpdateReport functions.

Parameter Type
idBatch String

Return values: MNBatchStatusInfo

cancelBatch

Requests to cancel a batch operation with id idBatch.

Parameter Type
idBatch String

Return values: Void

fetchBatchContactsUpdateReport

Returns a page of results of a batch contacts operation.

Parameter Type
idRowSet String
fromIndex int
toIndex int

Return values: List of MNContactOperation

AdPlanner

findPlannedDeliveryById

Returns information about a planned delivery

Parameter Type Description
idPlannedDelivery String  
options List of <Option>  

Return values: MNPlannedDelivery

Permissions: Be an administrator or be the owner of the planned delivery

getAllPlannedDeliveries

Returns a list of planned deliveries within a time range

Parameter Type Description
fromDate Date Minimum date for returned planned deliveries
toDate Date Maximum date for returned planned deliveries
options List of <Option>  

Return values: List of MNPlannedDelivery

Permissions: The list if filtered using the user's permissions

Workflows

enterWorkflow

Let a batch of contact enter one or more workflows.
For each contact this operation returns the list of ids for workflow sessions created for the contact. This is useful in order to test if any of the contacts really entered the workflow.
Inside the EnterWorkflowData structure you can set the idContact and a list of contextual variables, which in turn will become variables in the context of the session.
For each contact the sytem will try to enter all of the workflows which define a 'Start from API' event node which is configured with the given 'key', it is possible that the contact will not enter the workflow depending on the workflow configuration.

Parameter Type Description
contact List of EnterWorkflowData The information to use to start the workflows
key String The Key declared on 'Start from API' workflow nodes
options List of <Option> No option is currently available  

Return values: a EnterWorkflowResult structure for each EnterWorkflowData

Permissions: Sent to contacts of database