Communications management

The following is a list of API functions related to communications and contents.

Communications

createNewsletter

Creates a communication importing HTML creativity (or other format).
Returns the ID of the created communication.

Parameter	Type	Description
idCampaign	String	Indicates the journey in which to create the communication and from which it inherits the options.
content	Content	Content to import into the communication. Properties used: Content.name = name of communication and content. Content.contentType = one of following values: text/html: content is an HTML object text/url: content is an URL to import application/zip: content is a .ZIP file Content.text = value of the content for contentTypes text/html and text/url Content.binaryPayload = value of the content for contentType application/zip Content.binaryPayloadEncoding = encoding of Content.binaryPayload
options	List of <Option>	Available options: NAME: name for the communication (whether not set Content name will be used) SUBJECT: email subject FROMNAME: textual description for from (nickname) FROMEMAIL: communication from REPLYTO: communication reply to PROCESSHTMLDOCUMENT: indicates the use of an HTML import (default option is true) CONTACTSDESCRIPTION: description for contacts USERSDESCRIPTION: description for users TEMPLATE: id template of the communication. See getAllNewsletterTemplates OVERRIDETEXTVERSION: text fixed version of communication. If set, text version will not be automatically calculated from html version IDWEBSITE: id of the website to be used for links inside the email IDWEBDOMAIN: id of the webdomain to be used for links inside the email DEFAULTTARGET: list of id audience to use as default target of communication. If not specified it will be used journey target. If journey target has forceusetarget option active, then each audience of defaulttarget must be a audience or a subaudience of the journey target TAGS: list of integer representing id of tags to use as tags of communication. See getAllContentTags for retrieve of tags ids SUBJECTMODE: simple: single subject; bylanguage: based on contact field LINGUA value; conditional: based on a custom condition. SUBJECT_[LANG_ID]: Option valid for subjectmode=bylanguage. For example to specify a subject valid only for italian contacts add the subject in an option with key SUBJECT_ITA CONDITIONSIDS: Option valid for subjectmode=conditional. List of comma separated strings containing the names of each subject cases. For example: Condition 1,cond2 Es. CONDITIONSIDS=Condition 1,cond2 CONDITION_[COND_ID]: Option valid for subjectmode=conditional. Use one of these option for each condition specified in CONDITIONSIDS list to indicate the display condition. Using the example above, you must insert a CONDITION_Condition 1 option and CONDITION_cond2 option SUBJECT_[COND_ID]: Option valid for subjectmode=conditional. Use one of these option for every condition specified in CONDITIONSIDS list option. Using the example above, you must insert a SUBJECT_Condition 1 option and SUBJECT_cond2 option SMSFROM: sender for SMS message version SMSBODY: content of the SMS message version ENABLESMS: enable SMS version ENABLEEMAIL: enable email version EXPECTEDDELIVERYTS: expected date of first delivery. For the format see formatting date-times. EMAILSUBJECTENCODING: email subject encoding (for instance utf-8 or windows-1252) EMAILBODYENCODING: email body encoding (for instance utf-8 or windows-1252) ISNEWSLETTERTEMPLATE: create this communication as a transactional communication IDMESSAGETYPE: message type (id) assigned to transactional messages sent with this communication SMSENCODING: encoding of the SMS body (gsm, unicode) ENABLELONGSMS: enable long SMS (boolean) MAXSMSPARTS: number of message parts, default 1 (only valid if enablelongsms=true) ENABLESMSLINKSTRACKING: enable link tracking (boolean)

Return values: String

Permissions: Manage communications of the journey

createNewsletterFromTemplate

Creates a communication from an existing template.
Returns the ID of the created communication.

Parameter	Type	Description
idTemplate	String	MUST be a valid idTemplate got from getAllNewsletterTemplates(). Use global: or custom: if the template is custom in your account. For example: <idTemplate>custom:32</idTemplate>
idCampaign	String	Indicates the journey to which the communication belongs
name	String
options	List of <Option>	Available options: FROMEMAIL: communication sender address FROMNAME: textual description for from (Display Name) SUBJECT: email subject REPLYTO: email reply-to field CONTACTSDESCRIPTION: description for contacts USERSDESCRIPTION: description for users OVERRIDETEXTVERSION: text fixed version of communication. If set, text version will not be automatically calculated from html version IDWEBSITE: id of the website to be used for links inside the email DEFAULTTARGET: list of id audience to use as default target of communication. If not specified it will be used journey target. If journey target has forceusetarget option active, then each audience of defaulttarget must be a audience or a subaudience of the journey target TAGS: list of integer representing id of tags to use as tags of communication. See getAllContentTags for retrieve of tags ids SUBJECTMODE: simple: single subject; bylanguage: based on contact field LINGUA value; conditional: based on a custom condition. SUBJECT_[LANG_ID]: Option valid for subjectmode=bylanguage. For example to specify a subject valid only for italian contacts add the subject in an option with key SUBJECT_ITA CONDITIONSIDS: Option valid for subjectmode=conditional. List of comma separated strings containing the names of each subject cases. For example: Condition 1,cond2 CONDITION_[COND_ID]: Option valid for subjectmode=conditional. Use one of these option for every condition specified in CONDITIONSIDS list option. Using the example above, you must insert a CONDITION_Condition 1 option and CONDITION_cond2 option SUBJECT_[COND_ID]: Option valid for subjectmode=conditional. Use one of these option for every condition specified in CONDITIONSIDS list option. Using the example above, you must insert a SUBJECT_Condition 1 option and SUBJECT_cond2 option.

Return values: String

Permissions: Manage communications of the journey

getNewsletterWebVersionLink

Returns a link to show the communication on the web.
You can also specify a contact ID (so that it is logged).

E.g. you can use this function to share the link to the communication on Social Networks.

Parameter	Type
idNewsletter	String
idContact	String
options	List of <Option>

Return values: String

Permissions: Export contact data from the database

updateNewsletter

Updates existing communication.

Parameter	Type	Description
idNewsletter	String	ID of the communication to update.
content	Content	Used to update the communication contents using the value of property Content.text (for Content.contentType text/html and text/url) or Content.binaryPayload (for Content.contentType application/zip).
options	List of <Option>	NAME: name for the communication. SUBJECT: email subject. FROMNAME: textual description for from (nickname). FROMEMAIL: communication from. REPLYTO: communication reply to. CONTACTSDESCRIPTION: description of contact. USERSDESCRIPTION: description of user. TAGS: option always rewrite the entire list of communication tags, it does not append only specified tags. Use an empty string if you want to detach all tags from a communication. TAGS option should not be used when updating a sent communication. DEFAULTTARGET: list of id audience to use as default target of communication. If not specified it will be used journey target. If journey target has forceusetarget option active, then each audience of defaulttarget must be a audience or a subaudience of the journey target. SUBJECTMODE: simple: single subject; bylanguage: based on contact field LINGUA value; conditional: based on a custom condition. PROCESSHTMLDOCUMENT: indicates the use of an HTML import (default option is true). TEMPLATE: id template of the communication (ignored whether no content is passed or content.contentType is missing). See getAllNewsletterTemplates. OVERRIDETEXTVERSION: text fixed version of communication. If set, text version will not be automatically calculated from html version. IDWEBSITE: id of the website to be used for links inside the email. SUBJECT_[LANG_ID]: Option valid for subjectmode=bylanguage. For example to specify a subject valid only for italian contacts add the subject in an option with key SUBJECT_ITA. CONDITIONSIDS: Option valid for subjectmode=conditional. List of comma separated strings containing the names of each subject cases. For example: Condition 1,cond2. SUBJECT_[COND_ID]: Option valid for subjectmode=conditional. Use one of these option for every condition specified in CONDITIONSIDS list option. Using the example above, you must insert a SUBJECT_Condition 1 option and SUBJECT_cond2 option. CONDITION_[COND_ID]: Option valid for subjectmode=conditional. Use one of these option for every condition specified in CONDITIONSIDS list option. Using the example above, you must insert a CONDITION_Condition 1 option and CONDITION_cond2 option.

Return values: Void

Permissions: Manage communications of the journey

deleteNewsletter

Deletes (hides) the selected communication.

Parameter	Type
idNewsletter	String

Return values: Void

Permissions: Manage communications of the journey

findNewsletterById

Returns information about a communication (note: templates are considered communications).

Parameter	Type
idnewsletter	String

Return values: MNNewsletter

Permissions: Manage communications of the journey

getNewsletterDetails

Returns information about a communication (note: templates are considered communications).
Unlike findNewsletterById this function also obtained additional information from CMS MagNews, this information is free-form and may change over time.

Parameter	Type
idnewsletter	String
options	List of <Option>

Return values: MNNewsletterDetails

Permissions: Manage communication of the journey

queryNewsletters

Returns a list of communications, selected with a query.
Use fetchNewsletters in order to retrieve the result.
If you want some RowSet's info, see Utility

Parameter	Type
query	String	Some example: SELECT * FROM NEWSLETTERS WHERE idcampaign = 5 SELECT * FROM NEWSLETTERS WHERE idnewsletter = 8 or idnewsletter = 9 SELECT * FROM NEWSLETTERS WHERE sent = true SELECT * FROM NEWSLETTERS WHERE draft = true SELECT * FROM NEWSLETTERS WHERE name LIKE 'myname' SELECT * FROM NEWSLETTERS WHERE name LIKE '%mynameendwith' SELECT * FROM NEWSLETTERS WHERE name LIKE 'mynamestartswith%' SELECT * FROM NEWSLETTERS WHERE name LIKE '%mynamecontains%' SELECT * FROM NEWSLETTERS WHERE sent=true ORDER BY sentdate DESC LIMIT 10 SELECT * FROM NEWSLETTERS WHERE sent=false ORDER BY creationdate DESC LIMIT 10 SELECT * FROM NEWSLETTERS WHERE sentdate > '{ts 2013-02-01 14:30:00.000}' and sentdate < '{ts 2013-02-01 14:30:00.000}' SELECT * FROM NEWSLETTERS WHERE creationDate > '{ts 2013-02-01 14:30:00.000}'
options	List of <Option>

Return values: String

Permissions: Manage communications of all journeys

queryNewslettersByCampaign

This operation is deprecated since API version 18.02, please use queryNewsletters.
Returns the list of communications (drafts, sent, ...) for a specific journey.
Use fetchNewsletters in order to retrieve the result.
If the parameter filterIdeditor is passed, you only get the communication belonging to a certain user (e.g., the one who created them).
If you want some RowSet's info, see Utility

Parameter	Type
idCampaign	String
filterIdEditor	String
options	List of <Option>

Return values: String

Permissions: Manage communications of the journey

fetchNewsletters

Returns a results page of a communications RowSet.

Parameter	Type
idRowSet	String
fromIndex	int
toIndex	int

Return values: List of MNNewsletter

Permissions: Manage communications of the journey

getAllNewsletterTemplates

Returns a list of metadata about available templates to create a communication in a journey.

Parameter	Type
idCampaign	String
options	List of <Option>

Return values: List of MNTemplateInfo

Permissions: Manage communication for journey

saveNewsletterCustomHeaders

Sets custom email headers for a communication.

Parameter	Type
idNewsletter	String
headers	list of FieldValue
options	List of <Option>

Return values: Void

Permissions: Manage communications of the journey

 

 

Contents

createContent

Creates a content (to be included in a communication or a web page).
Returns the id of the created content.
Datetime values and date values must be formatted using international settings of the user that is requesting the operation.

In order to create a content you have to define at least the field designerType as "giotto" and the proper magnewsType (e.g. "article", "link", etc; for more details see Content).
Then, because contents are organized in libraries, you need to define where to save the content: there is a library for each communication/journey/survey, a shared global content library, and therefore a content-private library where all children contents are stored (for a very advanced usage!). To save the content inside a communication you have to specify the field idnewsletter; to put the content inside a journey use the field idcampaign, whereas for a website-content just use the field idwebsite. By leaving all these fields empty the content will be stored in the shared global contents library.

Parameter	Type	Description
content	Content	The content to create. Supported Content properties: designerType = "giotto" magnewsType name values tags idnewsletter idcampaign idwebsite idparent
options	List of <Option>

Return values: String

Permissions: Manage contents

downloadContent

Returns a content, with format dependent on the type of content (e.g. an image will provide the content of the file, a file will return an HTML string).
The object Content contains the field contentType that corresponds to the MIME Type related to the content.
See createContent for a more detailed description.

Parameter	Type
idContent	String
options	List of <Option>

Return values: Content

Permissions: None (every content is always public)

deleteContent

Deletes a content so that it no longer appears in the lists and that if a user clicks to see the main body the page is not found.

Parameter	Type	Description
idContent	String
options	List of <Option>

Return values: Void

Permissions: Manage contents

insertContentInNewsletter

Adds a content to a communication that can be modified with the Designer.

Parameter	Type	Description
idContent	String
idNewsletter	String
block	String	The HTML container where the content will be inserted
position	String	Where to insert the content inside the container (block). Supported values: first, last, the index position
format	String	Used to specify the content type to use to draw the content inside the document. Leave it empty or null in order to let the system choose automatically the content type

Return values: Void

Permissions: Manage contents and manage communications of the journey

createContainerInNewsletter

Adds a container to a communication that can be modified with the Designer.

Parameter	Type	Description
idNewsletter	String
path	String	/idcontainer/#position. For example: /myContainer/#1
position	String	'first' or 'last'
contenttype	String
values	list of FieldValue

Return values: Void

Permissions: Manage communications of the journey

updateContainerValuesInNewsletter

Updates a container filling with all the given values.

Parameter	Type	Description
idNewsletter	String
path	String	/idcontainer/#position. For example: /myContainer/#1
values	list of FieldValue

Return values: Void

Permissions: Manage communications of the journey

clearContainerContentsInNewsletter

Clears a container.

Parameter	Type
idNewsletter	String
path	String

Return values: Void

Permissions: Manage communications of the journey

fillNewsletter

Inserts a list of content inside a communication using a mn:schemedef guide.

Parameter	Type
idNewsletter	String
path	String
schemename	String
data	FillNewsletterData
options	List of <Option>

Return values: Void

Permissions: Manage communications of the journey and manage contents

getContentsInNewsletter

Returns the list of contents/s ID in the communication.
Note: to get the communication content in the SMS format you have to use getNewsletterDetails

Parameter	Type	Description
idNewsletter	String

Return values: List of String

Permissions: Manage communications of the journey and manage contents

queryContents

Returns the list of the contents ids that matches the given query.

To restrict the query to a specific library use option library; to set the context of the library set the value of the idnewsletter, idcampaign or idwebsite.
To execute queries by content fields you need to specify the contenttype option which selects the model for the contents.

Parameter	Type	Description
query	String	It only accepts queries with 'select *', it doesn't accept queries that specify field names. Query examples: SELECT * FROM CONTENTS WHERE name = 'mycontent' SELECT * FROM CONTENTS WHERE name LIKE 'myname' SELECT * FROM CONTENTS WHERE name LIKE '%mynameendwith' SELECT * FROM CONTENTS WHERE name LIKE '%mynamecontains%' ORDER BY lastmodificationdate LIMIT 10 SELECT * FROM CONTENTS WHERE template='mycustomtype'
options	List of <Option>	library: 'newsletter','campaign','website','global' contenttype: model of the objects to query (e.g. 'article', 'link', etc.) idnewsletter: id of the communication used as context idcampaign: id of the journey used as context idwebsite: id of the website used as context

Return values: List of String

Permissions: Manage contents

Medias

uploadMedia

Creates a media (a file sources) for use in a communication or journey.
Note: this operation returns other media structure because the file name could be changed if the system finds another media with the same name in selected library.
Medias are organized in libraries, there is one library for each communication, for each journey, for each content and there is a global media library shared among all contexts.
Inside the Media structure you have to fill idnewsletter field in order to put the media inside the communication media library.

To insert a media in a journey media library, you have to fill the idcampaign field.
If you leave empty idnewsletter, idcampaign, idcontent and idwebsite fields the media will be put on the global media library.

To get the URL of a media you have to use the syntax [image:filename.gif from=newsletter], specifying the library to use in the from parameter (e.g. communication, journey, content or global).
To get the URL of a media that is not an image file type (gif, jpg, png) you have to use [redirect:file name=filename.js from=global]
To get the URL that counts the number of downloads of a media that is not an image file type (gif, jpg, png) you have to use [link:file name=filename.js from=global].

Parameter	Type	Description
media	Media
options	List of <Option>

Return values: Media

Permissions: Manage contents

downloadMedia

Downloads info and contents of a media file.

Parameter	Type	Description
idmedia	String
options	List of <Option>	Boolean content: if set to true the content of the file will be returned, if content=false then only meta data are returned. Use content=false if you are only interested in metadata.

Return values: Media

Permissions: None (every media is always public)

findMediaByName

Downloads info and contents of a media file.

Parameter	Type	Description
name	String
options	List of <Option>	Available options: Boolean content: if set to true the content of the file will be returned, if content=false then only meta data are returned. Use content=false if you are only interested in metadata. Integer idnewsletter: id of the communication which contains the requested media (communication private medias). Integer idcampaign: id of the journey which contains the requested media (for communication private medias fill ONLY idnewsletter, and not idcampaign). Integer idwebsite: id of the website which contains the requested media.Integer idcontent: id of the content which contains the requested media.

Return values: Media

Permissions: None (every media is always public)

Tags

getAllContentTags

Returns the description of all tags for defined contents.

Parameter	Type
options	List of <Option>

Return values: List of MNContentTag

Permissions: None (every tag is always public)

createContentTag

Creates a tag for contents (Objects Properties).

Parameter	Type	Description
name	String
type	String	must be simple or empty
values	List of String
options	List of <Option>

Return values: MNContentTag

Permissions: Manage contents

Journeys

A journey is a set of communication.

When you want to use Web Pages and Surveys of a Journey you have to use as idWebSite the value of the field idWebSite inside the Journey structure.

createCampaign

Creates a new journey.

Since a journey is a set of communications, if you want to create a simple email you should create a communication, not a journey.

Parameter	Type	Description
name	String
field	List of FieldValue	Available fields: subject: default subject for new communications emailfrom: default from email for new communications smsfrom: default SMS sender for new communications emailalias: default (display name) from name for new communications emailreplyto: default email reply to for new communications emailmultipart: sets multipart delivery, default for new communications cssinline: displays inline css, default for new communications emailenabled: enables the email channel, default for new communications smsenabled: enables the SMS channel, default for new communications faxenabled: enables the Fax channel, default for new communications useallmedia: sends on each channel available for contacts, default for new communications ignoreusermediapref: for multichannel delivery sends also on channels for which contacts have not given an explicit consent, default for new communications removedupemails: removes duplicate email addresses during deliveries, default for new communications removedupcells: removes duplicate mobile numbers during deliveries, default for new communications removedupfax: removes duplicate Fax numbers during deliveries, default for new communications defaulttarget: default target for deliveries (comma separated list of audience ids) forceusetarget: restricts target for deliveries to default target (true
options	List of <Option>

Return values: String

Permissions: Create journeys

getAllCampaigns

Returns lists of all journeys.

Return values: List of MNCampaign

Permissions: Manage all journeys

findCampaignById

Returns information about a journey.

Parameter	Type
idCampaign	String

Return values: MNCampaign

Permissions: Manage journey

updateCampaign

Updates a journey.

Parameter	Type	Description
name	String
field	List of FieldValue	options are the same as createCampaign
options	List of <Option>

Return values: void

Permissions: Manage journey

WebDomains

getAllWebDomains

Returns the id and the name for all defined webdomains.

Parameter	Type
options	list of <options>

Return values: List of MNWebDomain

Permissions: None (every webdomain is always public)

Events

getSimpleMessageEvents

Returns all transactional message events matching the given filters.

Parameter	Type	Description
options	list of <options>	Available values
		Integer idsimplemessage: message id Integer idcontact: contact id Integer idmessagetype: type of id message Integer idmessagecategory: catetory id of the message String from: minimum event timestamp (for the format see formatting date-times) String to: max event timestamp (for the format see formatting date-times) String channel: event channel ("email", "sms", "fax" or "*")

Return values: List of Simplemessageevent

Permissions: View statistics details