3.16.3Sending mail

A widget, script, or UDIX can send three types of message:

A local, transient message. These only exist within the running MyTrader app, and are destroyed when the user logs out of their current trading account or reloads the app.

A remote message to the current device. These are stored permanently until the user chooses to delete them. The widget, script, or UDIX doesn't need to know the ID of the current device.

A remote message to another device. The widget, script, or UDIX must know the ID of the device it is sending to.

Remote messages are subject to a quota, regardless of whether they are being sent to the current device or another device. Your device's ability to send mail will be temporarily blocked if you try to send too many remote messages. If you are using the mailbox as an alerting mechanism, you should make sure that you don't do something such as entering a loop where you generate the same alert over and over again. (In extreme cases, this can even lead to mail from the device being permanently blocked.)

You send mail using Framework.SendMail(). This takes two parameters: a definition of the mail to send, and an asynchronous callback which receives success or failure. For example:

Framework.SendMail({

subject: "A new message"

}, function (Msg) {

if (Msg.success) {

// Mail successfully sent

} else {

// Mail failed. Error reason will be in Msg.error

}

});

The mail request can have the following properties. The subject is the only compulsory property:

Property

Description

subject

Subject of the message (max 200 characters)

body

Optional body content for the message. Limited to 4KB.

to

The ID of the device to send to. Only required when sending to another device. Can be omitted when sending mail to the current device's mailbox.

local

If local:true, identifies a local message as described above. If a local message is specified, any recipient to value is ignored.

priority

Not available on messages to other devices. Only available on messages to the current device, either locally or remotely. See below. Defaults to 0 if omitted.

noPush

By default, if the mail is not local and the receiving device is a mobile/tablet then the message will generate an iOS/Android push notification. You can turn this off by setting noPush:true (or any value for noPush, actually including noPush:false. It is the presence of a noPush key in the JSON which disables the push, not the key's value.)

The priority level - only available on messages to the current device - can be one of the following values between 0 and 3:

priority

Description

0

Normal priority

1

Message is marked in red in the mailbox

2

A new-mail icon is displayed in the platform's banner (until the message has been read)

3

The mail is forced to open immediately in the platform, without user interaction/request

The optional body of a message can be three things (subject to the 4KB limit):

Plain text

HTML - a full HTML document with <html> and </html> opening and closing nodes

The URL of a web page, subject to the usual browser security restrictions

An HTML document or web page is displayed in a sandboxed iframe, and has no framework access.