Description

Updates or creates a MAPI message.

Syntax

status = MAPISaveMail([session][, parent][, id][, flags], message)

Parameters

The MAPISaveMail function has the following parameters.

ParameterDescription
sessionContains a MAPI session handle returned by MAPILogon. If not specified and if a new message is to be created a system default session will be initiated, if possible, or a sign-in dialog box will be displayed. In any case, MAPI will return to its previous state upon completion of the function.
parentContains the name of an OpenInsight parent window. If not specified any dialog box displayed will be application modal.
idContains the id of the message which is to be updated or which has been created. To update an existing message specify a valid session handle returned from MAPILogon and the message's id. To create a new message the session handle is optional and a message id should not be specified on input.
flagsContains information about session initiation. It could be MAPI_LOGON_UI$, MAPI_NEW_SESSION$, or a combination of these flags.
  • MAPI_LOGON_UI$ indicates that MAPI should display a sign-in dialog box, if necessary. If the session parameter is specified this flag is ignored.
  • MAPI_NEW_SESSION$ indicates that MAPI should establish a new session and not attempt to share another MAPI client's session or the default session. If the session parameter is specified this flag is ignored. The insert record MAPI_EQUATES contains these flags. You may combine flags by adding them together with an addition sign (+).
messageContains the record for the message which is to be saved. The message record structure is detailed in the following table. The from field and the MAPI_SENT$ flag are ignored when saving a message.

After the function completes successfully the id parameter will contain the identifier of the updated or newly created message.

Use the MAPI_EQUATES insert record for access to the values in the following table.

Column positionNamePurpose
1subjectThe subject of the message.
2fromThe sender of the message.
3to@VM-delimited list of the message's To: recipients.
4cc@VM-delimited list of the message's CC: recipients.
5bcc@VM-delimited list of the message's BCC: recipients.
6dateThe date the message was received.
7textThe text of the message.
8type'The type of the message.
9flagsThe attributes of the message. It could be MAPI_UNREAD$, MAPI_RECEIPT_REQUESTED$, MAPI_SENT$, or a combination of these flags.
  • MAPI_UNREAD$ indicates that the message has not been read.
  • MAPI_RECEIPT_REQUESTED$ indicates that the sender should be notified when the message is received.
  • MAPI_SENT$ indicates that the message has been sent.

The insert record MAPI_EQUATES contains these flags. You may combine flags by adding them together with an addition sign (+).

10files@VM-delimited list of the names of files to be attached to the message.
11paths@VM-delimited list of the paths to files to be attached to the message.
12positions@VM-delimited list of the positions within the text of files to be attached to the message.

Returns

1 for successful execution or 0 for failure.

If function execution fails, you can retrieve a text error message by calling the Get_Status function. For example, to display an error message on the screen, include the following error handling routine in your code:

Get_Status(ErrMsg)

Msg(@window, ErrMsg)

See also

Get_Status(), MAPILogon(), MAPIOpenMail()

Example

Subroutine DemoMAPISaveMail(var)
*      Create a new message and save it in the outbox
$INSERT MAPI_EQUATES
Declare Function MAPISaveMail
Declare Subroutine Msg, Get_Status
flags   = MAPI_LOGON_UI$
id      = ""
message = ""
message<POS_SUBJECT$> = "MAPI Demo"
message<POS_FROM$   > = "Trudy Jones"
message<POS_TO$     > = "Alice Smith"
message<POS_TEXT$   > = "This is a test of the emergency..."
message<POS_TYPE$   > = "IPM.Outbox"
message<POS_FLAGS$  > = MAPI_RECEIPT_REQUESTED$
if MAPISaveMail(0, 0, id, flags, message) then
  Msg(@window, "Message successfully saved")
end else
  Get_Status(display)
  Msg(@window, display)
end
return
  • No labels