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.