Vai al contenuto principale
English
Help Desk

Delivering messages and communications

Aggiornato

The following is a description of functions to enable communications delivery and other deliveries.

Batch deliveries

sendNewsletter

It enables a communication delivery according to the options MNSendOptions.
Returns the ID of created delivery.

Parameter Type Description
idnewsletter String  
target List of String If MNSendOptions.trial = true the target parameter is the list of addresses to which you send a test message for a preview If MNSendOptions.trial = false the target parameter is the list of contacts audiences ids to which send the communication  
options MNSendOptions Available MNSendOptions:  
  • Boolean enableEmail=true and Boolean trial=false to execute a final delivery.
  • Boolean trial: execute a trial delivery.
  • DateTime requestedStartDate: you can specify a future date to start the delivery. If this value is empty or in the past, the delivery will start as soon as possible.
    Time and date have to be written according ISO8601 standard (Complete date plus hours, minutes and seconds):
    YYYY-MM-DDThh:mm:ssTZD (eg 2017-07-16T19:20:30+01:00)
  • Boolean enableSendTimeOptimization: the delivery will be sent with "Send Time Optimization" feature. This flag can't be enabled together with partitioned=true or usecontactstimezone=true.
  • Integer speedPerMinute: you can specify a limit to slow down the sending speed, indicating the number of emails per minute (0 means platform default).
advancedOptions List of <Option> Available options:
  • Boolean usenewsletteroptions: use default values from communication instead of what specified here.
  • Boolean cssinline: automatically change the html in order to increase compatibility (default false).
  • Boolean webbug: enable the web bug to allow the detection of HTML openings even if the user does not click (default true).
  • String emailbodyencoding: binary encoding of the body of the email (default windows-1252).
  • String emailsubjectencoding: binary encoding of the subject of the email (default windows-1252).
  • Boolean emailhtmlmultipart: send also a textual copy of the HTML emails with encoding "multipart/alternative" (default false).
  • String emailformat: force the emails delivery for a certain format: "HTML" = all html, "TEXT" = all text, "AUTO" = according to the contact's preferences. Default value is "HTML".
  • Boolean embed: incorporate all the resources (images, CSS) to allow the emails display even with disconnected email clients (default false)
  • String emailreplyto: "reply-to" address of emails (default email of the user who makes the call).
  • Boolean useallchannels: use all available communication channels (in the case of multi-channel communication, e.g. SMS+email; default true).
  • Boolean usecontactsdata: use the contacts' data (valid only for deliveries with trial=true; default true).  
  • Integer iddatabase: if usecontactsdata=true this is the database to use for contacts lookup.
  • Boolean ignoreuserpreferencesonchannels: use the channels of communication without considering the contacts' preferences (default true).
  • Boolean confirm: automatically confirm the launch without sending the launch confirmation email (default true).
  • Boolean sendconfirmationrequest: when option confirm is set to "false", this flag determines whether the confirmation mail should be sent or not (default false).
  • Boolean enablesendreport: send a report as configured in journey settings (default false).
  • Boolean failonemptytarget: for non-trial launches only, launch fails if at least one of the audiences specified in target is empty (default false).
  • Boolean partitioned: used to create a partitioned launch (launch in multiple stages) using parameters: "partitions" and "partitionDelays" (default false).
  • Boolean recall: used to send the communication only to contacts who received the mail in a previous delivery without opening or clicking it before and without recording an hard bounce. If it's a trial delivery this option won't be considered (default false).
  • String partitions: list of integer separated by ';' char representing the percentage of each partition. For example: "10;20;70" means that first partition will be the 10% of target. Sum of partitions must be 100.
  • String partitiondelays: list of integer separated by ';' char representing the deltas in milliseconds between partitions. For example: "0;86400000;172800000", means that first partition will be sent on the requestedStartDate, second partition the day after and third partition the day after that.
  • Boolean usecontactstimezone: if true a launch based on timezone will be created. The "requestedStartDate" of launch will be evaluated using the value of timezone field of each contact (default false).
  • Integer idpolicy: use this option to override the policy to use for this delivery. The sendNewsletter fails if this option is evaluated but the policy mapping feature is not active or if the "Choose a different policy for each delivery" journey option is false. See the getAllDeliveryPolicies for retrieve policies ids. 
  • Boolean ignoremissingunsubscribelink: used to disable the unsubscribe link presence checking. Whether "false" this function will fail if no unsubscribe link has been set in the communication (default true).
  • Boolean ignoreencodingerrors: used to disable the charset compatibility checking. E.g. whether "false", this function will fail if you use "utf-8" characters not supported in "window-1252" encoding and the communication has the encoding set to "windows-1252" (default true).
  • String additionaltargetfilterquery: query to optionally filter delivery target. For example: "SELECT * FROM CONTACTS WHERE status = 'subscribed'". This query will be applied to filter every audience of target
  • Integer emailpriority: set messages delivery priority. Available values: "1" - Highest, "2" - High, "3" - Normal (default, used when not declared), "4" - Low, "5" - Lowest
  • String channels: comma separated list of custom channel identifiers for which to enable the delivery. This channels are added to the enabled channels specified in the options parameter. The custom channels in this list must be defined in the account.
  • Boolean forceusedeliverabilitycluster: if true, the sending policy will be the one in the contact delivery cluster, for contacts that have it valued (default false).
  • Boolean usedatabasepolicysettings: corresponds to the parameter that indicates, when configuring communication sending, whether to use the database delivery policy. If not specified, the journey delivery policy is used.

Return values: String

Permissions: Send communication for the journey and send communications and send communication to contacts of the database for each audience

getDeliveryStatus

Returns the delivery status.
The delivery has completed the first launch to all contacts when it passes to status MNDeliveryStatus.status = "FINISHING" or "FINISHED".
Delivery is active in the system if MNDeliveryStatus.active=true.

Parameter Type
idDeliveryStatus String

Return values: MNDeliveryStatus

Permissions: Send communication for the journey and send communications

getDeliveryStatusForNewsletter

Returns a status page for each communication's delivery.

Parameter Type
idNewsletter String
options List of <Option>

Return values: MNDeliveryStatus

Permissions: Send communication for the journey and send communications

requestDeliveryStatusAction

Requires the modification of a delivery status.
Notes: a delivery change of status might not be immediate. If some messages have been queued for delivery they may still be sent, besides the delivery stop request. The system automatically removes deliveries that are in "pause" for too long.

Parameter Type Description
idDeliveryStatus String  
action String values of actions:  
stop: requires to stop delivery  
pause: requires to temporarily suspend delivery  
resume: requires to resume delivery  

Return values: MNDeliveryStatus

Permissions: Send communication for the journey and send communications

getActiveDeliveryStatus

Returns a status page for each active delivery of a journey.

Parameter Type
idCampaign String

Return values: List of MNDeliveryStatus

Permissions: Send communication for the journey and send communications

queryDeliveryStatus

Returns a status page for deliveries of a given journey. The result is a RowSet to be downloaded using fetchDeliveryStatus

Parameter Type Description
idCampaign String

Return values: String

Permissions:

queryDeliveries

Returns a status page for deliveries. The result is a RowSet to be downloaded using fetchDeliveryStatus

Parameter Type  
option List of <Option> Available options:  
  • Int idCampaign: return only deliveries of communications of the given journey  
  • Int idNewsletter: return only deliveries of communications of the given communication  
  • String channel: filter delivery channels, this is a list of strings delimited with comma, valid values are 'email','sms' and 'fax', Default = email,sms,fax  
  • String startDateFrom: return only deliveries which have startDate >= the given timestamp. For the format see formatting date-times.
  • String startDateTo: return only deliveries which have startDate < the given timestamp. For the format see formatting date-times.
  • trials
trials Boolean If true (or not specified), they will be returned the test deliveries too. If false, the test deliveries will be discarded

Return values: String

Permissions:

fetchDeliveryStatus

Returns a status page for deliveries.

Parameter Type
idRowSet String
fromIndex int
toIndex int

Return values: List of MNDeliveryStatus

Permissions: Send communication for the journey and send communications

Notification messages

sendEmailMessage

Sends a notification email (transactional message).

Parameter Type Description
message EmailMessage  
option List of <Option> Available options:  
  • Int idcontact: looks up for contact's profile data using the internal id of the contact
  • Int iddatabase: if the contact is not recognized this values is used to render the email as it was sent to a contact of a database  
  • String contactprimarykey: looks up for contact's profile data searching for a contact with the given primary key, in the given database (see iddatabase option)
  • Boolean contactprimarykeyoptional: If the contact isn't found, use the to field in the message values as recipient address instead of failing the delivery.
    Note: when no contact is found, no statistics are recorded, since the message is sent but there's no contact on any database to associate the message against.  
  • Boolean usecontactemail: uses the email of the given contact as the recipient address of the message (overriding message.to). Default = false
  • Boolean cssinline: apply css inline to the html content of the message. Default = false
  • Boolean embbeddedimages: download and embed all the images founded in the html content of the message (attaching them at the message). Default = false
  • Int idwebsite: specifies the website to use when rendering absolute URLs (for example image urls or [link:ununsubscribe] urls..). Default = id of the default website
  • Boolean usenewsletterastemplate: indicates to use a communication template (or notification message template, which is a special type of communication) as the message body. Default = false
  • Boolean renderatsend: indicates to render the message during the delivery and not while serving the API call. This option must be used in conjunction with usenewsletterastemplate. This option will result in faster API calls and in less resources usage. This is the preferred way of sending messages using usenewsletterastemplate option. Default = false. With 'renderAtSend' option, message body will never be persisted on db, even if 'messageRetention' level is set to 'full'  
  • Boolean usehtmlcodeastemplate: indicates to use html code as the message body. In this case for example you can use mn:if conditions and EmailMessage.tempvars. Default = false
  • Int idnewsletter: the communication whose template is used to draw the message (usenewsletterastemplate must be set to true).
  • String newsletterkey: the key for sending by API of the communication whose template is used to draw the message (usenewsletterastemplate must be set to true). If idnewsletter and newsletterkey are both valued, idnewsletter will be used.
  • String format: the format of the email (default is 'html', admitted values are 'html', 'text' and 'multipart').  
  • Timestamp expectedDeliveryTs: requests to send the message at a given time. If empty it means 'as soon as possible'.   This field must be formatted according to the formatting options of the user who runs the request. The timestap is always the user timestamp.
  • String messageRetention: Specify a retention policy for the given message between "minimal" (discard the message body), "full" (keep the whole message and headers) and "reserved" (discard the recipient).
  • String idlanguage: language of the notification message if the contact is not subscribed in any database
  • Boolean nospool: indicates to attempt to avoid message spooling and send messages directly. This option can be helpful to send a message in a timely manner. Default = false  

Return values: MNSimpleMessageStatus

Permissions: Send communications and send communications to contacts of the database

sendSmsMessage

Sends a notification SMS text message (transactional).

Parameter Type Description
message SmsMessage  
option List of <Option> Available options:
  • Int idcontact: looks up for contact's profile data using the internal id of the contact
  • Int iddatabase: if the contact is not recognized this values is used to render the email as it was sent to a contact of a database  
  • String contactprimarykey: looks up for contact's profile data searching for a contact with the given primary key, in the given database (see iddatabase option)
  • Boolean contactprimarykeyoptional: If the contact isn't found, use the to field in the message values as recipient address instead of failing the delivery.
    Note: when no contact is found, no statistics are recorded, since the message is sent but there's no contact on any database to associate the message against.  
  • Boolean usecontactcell: uses the phone number (field 'cell') of the given contact as the recipient address of the message (overriding message.to). Default = false
  • Boolean usenewsletterastemplate: indicates to use a communication template (or notification message template, which is a special type of communication) as the message body. Default = false
  • Int idnewsletter: the communication whose template is used to draw the message (usenewsletterastemplate must be set to true)
  • String newsletterkey: the key for sending by API of the communication whose template is used to draw the message (usenewsletterastemplate must be set to true). If idnewsletter and newsletterkey are both valued, idnewsletter will be used.
  • Int idwebsite: specifies the website to use when rendering absolute URLs (for example [link:ununsubscribe] urls..). Default = id of the default website
  • Boolean validatesmslength: If true the number of sms parts will be validated according to the maxsmsparts option together with the account settings. Default = true
  • Timestamp expectedDeliveryTs: requests to send the message at a given time. If empty it means 'as soon as possible'
  • Int maxsmsparts: specifies the maximum number of parts of sms message. Messages splitted in a number of parts exceeding this limit will not be sent. Default = system maximum number of sms parts
  • String messageRetention: Specify a retention policy for the given message between "minimal" (discard the message body), "full" (keep the whole message and headers) and "reserved" (discard the recipient)
  • Boolean nospool: indicates to attempt to avoid message spooling and send messages directly. This option can be helpful to send a message in a timely manner. Default = false
  • String smsencoding: encoding of the SMS body (gsm, unicode)

Return values: MNSimpleMessageStatus

Permissions: Send communications and send communications to contacts of the database

getSimpleMessageStatus

Returns the delivery status of a notification message.

Parameter Type
idMessage String

Return values: MNSimpleMessageStatus

Permissions: If referred to a database contact, database data export permissions for the specific database.
If not referred to a database contact, database data export permissions for all the databases.
Always the Send communication permissions.

batchGetSimpleMessageStatus

Returns the delivery status for notification messages.

Parameter Type
idMessages List of String

Return values: List of MNSimpleMessageStatus

Permissions: If referred to a database contact, database data export permissions for the specific database.
If not referred to a database contact, database data export permissions for all the databases.
Always the Send communication permissions.

batchCancelSimpleMessages

Stops the delivery of a batch of notification messages.

Parameter Type
idMessages List of String

Return values: List of SendSimpleMessageOperation

Permissions: Send communications

batchSendEmailMessage

Sends multiple email messages.

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).
Parameter Type
message A list of BatchEmailMessage objects

Return values: List of BatchEmailMessageOperation

Permissions: Send communications

batchSendSmsMessage

Sends multiple sms messages.

Notes
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).
Parameter Type
message A list of BatchSmsMessage objects

Return values: List of BatchSmsMessageOperation

Permissions: Send communications

Utility functions

describeBounceCategories

Describes all available bounce categories.
Notes: the list of bounce categories is updated not very frequently (once a month), you should cache this list

Parameter Type  
advancedOptions List of <Option> Available options: none for current version 

Return values: List of BounceCategory

Permissions: None (public data)

getAllDeliveryPolicies

Describes all available policies for this account.
Notes: if the policy mapping feature is not active in this account, it will be returned an empty list

Parameter Type Description
options List of <Option> No available options  

Return values: List of MNDeliveryPolicy

Permissions: None (public data)

getAllSimpleMessageCategories

Describes all available transactional message categories for this account. 

Parameter Type Description
option List of <Option> No available options  

Return values: List of MNSimpleMessageCategory

Permissions: None (public data)

getAllSimpleMessageTypes

Describes all available transactional message types within a category for this account. 

Parameter Type Description
idMessageCategory String Message category  
option List of <Option> No available options  

Return values: List of MNSimpleMessageType

Permissions: None (public data)

findSimpleMessageTypeById

Returns the definition of a transactional message type

Parameter Type Description
idMessageType String  

Return values: MNSimpleMessageType

Permissions: None (public data)

createSimpleMessageType

Creates a new transactional message type

Parameter Type Description
idMessageCategory String Id of the containing category  
name String  
option List of <Option> No available options  

Return values: String (id of the new created type)

Permissions: None (public data)

updateSimpleMessageType

Update metadata of a transactional message type

Parameter Type Description
idMessageType String Id of the message type  
option List of <Option> Available options:  
String name: modify the name of the message type  

Return values: String (id of the updated type)

Permissions: None (public data)

findSimpleMessageCategoryById

Returns the definition of a transactional message category

Parameter Type Description
idMessageCategory String  

Return values: MNSimpleMessageCategory

Permissions: None (public data)

createSimpleMessageCategory

Creates a new transactional message category

Parameter Type Description
name String  
option List of <Option> No available options  

Return values: String (id of the new created category)

Permissions: None (public data)

updateSimpleMessageCategory

Update metadata of a transactional message category

Parameter Type Description
idMessageCatgory String Id of the message category  
option List of <Option> Available options:  
String name: modify the name of the message category  

Return values: Void

Permissions: None (public data)

getSimpleMessageTypeReport

Calculates a report on the status of transactional messages of a given message type.

This report considers only messages created inside a given time range.

Parameter Type Description
idMessageType String  
from Datetime Start of the time range (required)
to Datetime Start of the time range (required)
option List of <Option> Available options:  
String queryContacts: filter messages using a query on the contacts bound to the messages in the time range  

Return values: MNSimpleMessageTypeReport

Permissions: None (public data)

getAccountCreditAmount

Returns the residual credit for the given channel.

  • For the account with 'flat' plan: it returns residual credit plus automatic credit
  • For the account with 'final balance' plan: it returns always -1
Parameter Type Description
channel String Possible values: email, sms
option List of <Option>  

Return values: Number.
It returns a value approximated to the nearest thousand rounding down if credit is 1000; it returns 0 if credit is 0 or negative.

Permissions: None (public data)

batchGetSimpleMessageStatusByExternalId

Returns the status of N transactional messages by their external ID

Parameter Type Description
externalId String The external assigned ID of the message

Return values: MNSimpleMessageCategory

Permissions: If referred to a database contact, database data export permissions for the specific database.
If not referred to a database contact, database data export permissions for all the databases.

Legacy functions

sendSimpleMessage (Legacy)

Sends a notification email (transactional) to a contact.
This operation is deprecated since API version 18.02, please use sendEmailMessage or sendSmsMessage
The message is defined by MessageTemplate. Contact's data can be used in the message by using placeholders.
Return value is id for a notification message, whose status is accessible through getSimpleMessageStatus

Parameter Type Description
address String  
idDatabase String  
contactPrimaryKey String  
messageTemplate MessageTemplate PlaceHolder placeHolders: requests the message resending  
Some default placeholders are defined: "[PASSWORD]", "[USERNAME]", "[EMAIL]" , "[CELL]".  

Return values: String

Permissions: Send communications and send communications to contacts of the database

batchSendSimpleMessage (Legacy)

Sends a list of notification emails to the contact defined in every SendSimpleMessageValues
The message is sent to the address indicated in address, not to the contact's email address
The message is defined by MessageTemplate. Contact's data can be used in the message by using placeholders.
Return value is a list of SendSimpleMessageOperation that contains information such as notification messages' id, whose status is accessible by batchGetSimpleMessageStatus

Parameter Type Description
message SendSimpleMessageValues PlaceHolder placeHolders: requests the message resending  
Some default placeholders are defined: "[PASSWORD]", "[USERNAME]", "[EMAIL]" , "[CELL]".  

Return values: List of SendSimpleMessageOperation

Permissions: Send communications and send communications to contacts of the database

batchSendSingleNewsletter (Legacy)

Sends a communication copy to a generic address (that could even not be in the database) for every SendSingleNewsletterValues that is passed.
Return value is a list of SendSimpleMessageOperation that contains information such as notification messages' id, whose status is accessible by batchGetSimpleMessageStatus

Parameter Type Description
messages SendSingleNewsletterValues Available options:  
Boolean lookupReader: to use a contact data  
String forceReaderId: to force the use of a specific contact  

Return values: List of SendSingleNewsletterOperation

Permissions: Send newsletters and send newsletter to contacts of the database

getMessageStatus (Legacy)

Returns a message delivery status.

Parameter Type
idLaunch String
idMessage String
options List of <Option>

Return values: MNMessageStatus

Permissions: Send communications

batchGetMessageStatus (Legacy)

Returns the delivery status for a series of messages.

Parameter Type
idLaunch String
idMessage List of String
options List of <Option>

Return values: List of MNMessageStatus

Permissions: Send communications