@MailSend (Formula Language)

There are two ways to use @MailSend:

  • When used with no parameters, @MailSend mails the current document (the one being processed when the @function is evaluated) to the recipient designated in the document's SendTo field. The document must have a SendTo field.
  • When used with one or more parameters, @MailSend composes a new mail memo based on the information you supply in the arguments list, and sends it to the recipients listed in the sendTo, copyTo, and blindcopyTo arguments.

Syntax

@MailSend( sendTo ; copyTo ; blindCopyTo ; subject ; remark ; bodyFields ; [ flags ] )

Parameters

sendTo

Text or text list. The primary recipient(s) of the mail memo.

copyTo

Text or text list. Optional. The copy recipient(s) of the mail memo.

blindCopyTo

Text or text list. Optional. The blind copy recipient(s) of the mail memo.

subject

Text. Optional. The text you want displayed in the Subject field. This is equivalent to the Subject field on a mail memo; the message is displayed in the Subject column in the views in the recipients' mail databases. If this parameter is a list, only the first element is used; use @Implode as necessary to reduce a list to text.

remark

Text. Optional. Any text you want at the beginning of the body field of the memo. If this parameter is a list, only the first element is used; use @Implode as necessary to reduce a list to text.

bodyFields

Text list. The names of one or more fields from the current document that you want included in the mail memo. The fields must be of type text, text list, or rich text, and are appended to the memo in the order in which you list them. (You can store @Text of a numeric field in a variable and use the variable name as a field name.) Enclose each field name in quotation marks. If you want to list multiple fields, use the list format: "description":"issues":"resolution." If you store the name of the field in a variable, omit the quotation marks here.

When you use the [IncludeDocLink] flag (described in the following) to include a link to the current document, you should set the bodyFields parameter to null (""). If Notes/Domino cannot locate a field by name, it uses the string literal instead.

[ flags ]

Keyword. One or more flags indicating the priority and security of the memo. If you specify multiple flags, format them as a list, as in [SIGN]:[PRIORITYHIGH]:[RETURNRECEIPT]. Enclose each flag in brackets, as shown.

The available flags are:

[SIGN]

Electronically sign the memo when mailing it, using information from the user's ID. Signing does not occur unless you include this flag. This flag cannot be used in Web applications.

[ENCRYPT]

Encrypt the document using the recipient's public key, so that only the recipient whose private key matches can read the document. Encryption does not occur unless you include this flag. This flag cannot be used in Web applications.

[PRIORITYHIGH]

Immediately routes the message to the next-hop server, as defined by the combination of Mail Connection records and server records. If a phone call has to be made in order to route the message, then the call is placed immediately, regardless of the schedule set in the Remote Connection record. If you omit this flag, the priority defaults to Normal.

[PRIORITYNORMAL]

Routes the message to the next-hop server based on the schedule defined in the Mail Connect records. If the recipient's mail file resides on a server on the same Domino® network, then delivery occurs immediately. If you omit this flag, the priority defaults to Normal.

[PRIORITYLOW]

Routes the message overnight if the recipient's mail file does not reside on a server on the same Notes/Domino network. If the recipient's mail file does reside on a server on the same Notes/Domino network, then delivery occurs immediately. Low Priority mail can also be controlled by a Notes/Domino environment variable called MailLowPriorityTime=x, where x is equal to a number from 0 to 23. When placed in the server notes.ini file, this variable tells the server when to route Low Priority mail. If you omit this flag, the priority defaults to Normal.

[RETURNRECEIPT]

Notify the sender when each recipient reads the message. No receipt is returned unless you include this flag.

[DELIVERYREPORTCONFIRMED]

Notify the sender whether delivery of the memo was successful or not. By default, the Basic delivery report is used, which notifies the sender only when a delivery failure occurs.

[INCLUDEDOCLINK]

Include a link pointing to the document that was open or selected when @MailSend was used. You must include this flag if you want that document linked to the mail memo. A new document must be saved.

Note: This option will only work if the database contains a default view.

Usage

Use @MailSend in agents, form actions, form events, view actions, view events, and toolbar buttons. @MailSend is especially useful with scheduled agents as a means of sending mail at a predetermined interval; for example, to send reminders about a departmental meeting. One view from the database must be selected as the Default when database is first opened for the scheduled agent to work correctly. This function does not work in column, selection, hide-when, or window title formulas.

If the MailOptions field on the form is set to 0, @MailSend is disabled, and the formula fails to execute.

If the user's notes.ini file includes the statement

NoExternalApps=1

then any formula involving @MailSend is disabled. The user doesn't see an error message; the formula fails to execute.

When the [IncludeDocLink] option is used, the database must have a default view defined, and the linked document must be in it. Otherwise, @MailSend will fail.

When sending to multiple recipients within the SendTo, CopyTo, or BlindCopyTo arguments, the names must be supplied as a list with a separate list value for each recipient. For example, to send mail to both Sam and Martha at Big Company, the SendTo parameter would be "sam@bigcompany.com" : "martha@bigcompany.com", not "sam@bigcompany.com, martha@bigcompany.com".

Sending rich text fields

You can specify a rich text field as one of the bodyfields in an agent formula only.

Mail-related fields in a document

When you use @MailSend with no parameters, the current document may contain one or more mail-related fields; if it does, those fields are used when routing the document.

  • If the document contains the CopyTo or BlindCopyTo fields, it is routed to those recipients at the same time.
  • If the document contains the DeliveryPriority, DeliveryReport, or ReturnReceipt fields, they are used to control the delivery priority, generation of a delivery report, and generation of a return receipt, just as they are used in the Actions - Send Document command. If the document doesn't contain these fields, they default to normal priority, no delivery report, and no return receipt, respectively.

Examples

  1. This formula sends a memo to David Lee with a blind copy to Joseph Smith in Support. The memo is titled "Status Report," and its body contains the message "Sorry it's late!" plus the contents of the STATUS and PLANS fields from the current document. The document is mailed with the following options: it is signed, delivery confirmation is requested, and a return receipt will be sent when each recipient reads the memo. The recipients are listed using distinguished naming syntax (available to Release 3 users only). The copyTo information was omitted, and was replaced with the null string because additional arguments follow. 
    @MailSend("David Lee/";"";"Joseph Smith/Support";"Status Report"; "Sorry it's late!"; "STATUS":"PLANS"; [SIGN] : [DELIVERYREPORTCONFIRMED] : [RETURNRECEIPT])
  2. This formula sends a memo to Mary Tsen and to Joseph Smith in Support. The subject uses the text stored in the current document's TOPIC field, and the body of the memo draws from the COMMENTS field. The copyTo, blindCopyTo, and remark arguments were omitted, and were replaced with null strings because additional arguments still followed. The flags were omitted, but because no arguments followed their position, the null string was not needed.
    @MailSend("Mary Tsen/":"Joseph Smith/Support";"";"";TOPIC;""; "COMMENTS")
  3. This formula sends a memo to Mary Tsen with the message "Follow this link" in the Subject field, and a link to the original document in the Body field.
    @MailSend("Mary Tsen/";"";"";"Follow this link";"";"";[IncludeDocLink])
  4. This agent formula sends Martha O'Connell the contents of the Comments rich text field in a memo with the subject Feedback. The agent is triggered on an Action menu selection event and its target is the selected documents. The formula implodes the multi-value Items field to include it as the remarks parameter.
    @MailSend("Martha O'Connell/MA/Acme"; ""; ""; "Feedback"; @Implode(Items; ", "); "Comments")