Difference between revisions of "360Works Email/Documentation"
WikiEditTask (talk | contribs) m (Auto-upload documentation) |
WikiEditTask (talk | contribs) m (Auto-upload documentation) |
||
Line 64: | Line 64: | ||
Note: Email is sent from whichever machine the plugin is being used on, be sure to open up port 25 for outgoing SMTP access on those machines. | Note: Email is sent from whichever machine the plugin is being used on, be sure to open up port 25 for outgoing SMTP access on those machines. | ||
<h4>Displaying a name instead of the FROM address</h4> | <h4>Displaying a name instead of the FROM address</h4> | ||
− | The "from" field can be either an email " | + | The "from" field can be either an email address "you@yourdomain.com" or a name and email address |
like "FirstName LastName <you@yourdomain.com>" instead. Most email clients will then display the name in the from field instead of the address. | like "FirstName LastName <you@yourdomain.com>" instead. Most email clients will then display the name in the from field instead of the address. | ||
However, if the address is already in address book, most clients are configured to preempt with that associated name instead. | However, if the address is already in address book, most clients are configured to preempt with that associated name instead. | ||
<h4>Sending Attachments</h4> | <h4>Sending Attachments</h4> | ||
− | The [[#EmailAttachFile|EmailAttachFile]] accepts several different types of arguments. You can pass in a container | + | The [[#EmailAttachFile|EmailAttachFile]] accepts several different types of arguments. You can pass in a container field URL, or a path. |
A URL can be to a resource on the web, or can be a file url pointing to a local file (e.g. <code>file:///path/to/attachment.jpg</code>). | A URL can be to a resource on the web, or can be a file url pointing to a local file (e.g. <code>file:///path/to/attachment.jpg</code>). | ||
+ | |||
+ | <h3>Bulk Mail</h3> | ||
+ | When sending to multiple recipients, instead of creating a new message for each recipient, you can create a single message, connect once to your server, and then send the | ||
+ | same message multiple times, switching the subject, recipients, and message body for each recipient. | ||
+ | |||
+ | // First connect to the SMTP server and create the message. | ||
+ | Set Variable [ $msgCreate = | ||
+ | EmailConnectSMTP( "mail.example.com" ) and | ||
+ | EmailCreate( Email::from ; Email::to ; Email::subject ) and | ||
+ | EmailSetBody( GetAsCSS( Email::body ); "html" ) | ||
+ | ] | ||
+ | Go To Record/Request [ First ] | ||
+ | Loop | ||
+ | Set Variable [ $setRecipients = EmailRecipients [ Email::to ] ] | ||
+ | Set Variable [ $msgSend = EmailSend ] | ||
+ | Go To Record/Request [ Next ; Exit After Last ] | ||
+ | End Loop | ||
+ | // We've sent the same message to all recipients. Now disconnect | ||
+ | Set Variable [ $disconnect = EmailDisconnect ] | ||
<h3>Reading Mail</h3> | <h3>Reading Mail</h3> | ||
Line 102: | Line 121: | ||
// which was created by the EmailReadMessages function | // which was created by the EmailReadMessages function | ||
Import records [$$importUrl ; Update Matching] | Import records [$$importUrl ; Update Matching] | ||
− | // disconnect from the IMAP server | + | // Now disconnect from the IMAP server |
− | + | Set Variable [ $disconnect = EmailDisconnect ] | |
If [$disconnect = "ERROR"] | If [$disconnect = "ERROR"] | ||
Show Custom Dialog [EmailLastError] | Show Custom Dialog [EmailLastError] | ||
Line 127: | Line 146: | ||
Set Field[ImportedMessage::messageId ; EmailReadMessageValue( "messageId" )] | Set Field[ImportedMessage::messageId ; EmailReadMessageValue( "messageId" )] | ||
End Loop | End Loop | ||
+ | |||
+ | <h4>Microsoft Exchange Server</h4> | ||
+ | To read mail from a Microsoft Exchange Server, you'll need to enable IMAP access on your exchange server. | ||
+ | <a href="http://technet.microsoft.com/en-us/library/bb124489.aspx?ppud=4">This article</a> covers the steps for doing so. | ||
+ | You may need to restart your server for this change to take effect. | ||
+ | Once IMAP access is enabled, you can connect normally as described above. | ||
<h3>Modifying Mail Messages</h3> | <h3>Modifying Mail Messages</h3> | ||
Line 162: | Line 187: | ||
*[[#EmailBodySubstitute|EmailBodySubstitute]] ( searchString ; replaceString ) — Perform a substitute operation an the HTML or plain-text portion of the current HTML message. | *[[#EmailBodySubstitute|EmailBodySubstitute]] ( searchString ; replaceString ) — Perform a substitute operation an the HTML or plain-text portion of the current HTML message. | ||
*[[#EmailCCRecipients|EmailCCRecipients]] ( cc_addresses { ; append } ) — Set the CC (carbon copy) recipients for the current message. | *[[#EmailCCRecipients|EmailCCRecipients]] ( cc_addresses { ; append } ) — Set the CC (carbon copy) recipients for the current message. | ||
− | *[[#EmailConnect|EmailConnect]] ( host_address_deprecated { ; user_deprecated ; password_deprecated } ) — Connect to | + | *[[#EmailChooseFile|EmailChooseFile]] ( { initialPath ; fileType ; title } ) — Shows a file chooser dialog where a user can browse her local hard drive. |
− | *[[#EmailConnectIMAP|EmailConnectIMAP]] ( host ; username ; password { ; | + | *[[#EmailConnect|EmailConnect]] ( host_address_deprecated { ; user_deprecated ; password_deprecated } ) — Use {@link #EmailConnectSMTP} instead. |
− | *[[#EmailConnectPOP|EmailConnectPOP]] ( host ; username ; password { ; | + | *[[#EmailConnectAmazon|EmailConnectAmazon]] ( accessKey; secretKey ) — Connect to the Amazon Simple Email Service (SES) servers for sending email. |
− | *[[#EmailConnectSMTP|EmailConnectSMTP]] ( host { ; username ; password ; | + | *[[#EmailConnectIMAP|EmailConnectIMAP]] ( host ; username ; password { ; ssl=true ; forceTrust=true ; tls=true ; ... } ) — Connect to an incoming IMAP mail server. |
+ | *[[#EmailConnectPOP|EmailConnectPOP]] ( host ; username ; password { ; ssl=true ; forceTrust=true ; tls=true ; ... } ) — Connect to an incoming POP mail server. | ||
+ | *[[#EmailConnectSMTP|EmailConnectSMTP]] ( host { ; username ; password ; ssl=true ; forceTrust=true ; tls=true ; timeout=10 ; ... } ) — Connect to an outgoing SMTP mail server. | ||
*[[#EmailCreate|EmailCreate]] ( from ; to ; subject ) — Create a new email message, clearing any previous recipients and attachments. | *[[#EmailCreate|EmailCreate]] ( from ; to ; subject ) — Create a new email message, clearing any previous recipients and attachments. | ||
− | *[[#EmailDisconnect|EmailDisconnect]] — Close any open connections to email servers established via the EmailConnect. | + | *[[#EmailDisconnect|EmailDisconnect]] ( ) — Close any open connections to email servers established via the EmailConnect. |
*[[#EmailGetMessageCount|EmailGetMessageCount]] ( { flag1 ; flag2 ; ... } ) — Returns a count of messages in a particular mailbox, INBOX is used if no mailbox is specified. | *[[#EmailGetMessageCount|EmailGetMessageCount]] ( { flag1 ; flag2 ; ... } ) — Returns a count of messages in a particular mailbox, INBOX is used if no mailbox is specified. | ||
− | *[[#EmailGetNextMessage|EmailGetNextMessage]] — Loads a single message which was fetched in a previous call to the <code>EmailReadMessages</code> function. | + | *[[#EmailGetNextMessage|EmailGetNextMessage]] ( ) — Loads a single message which was fetched in a previous call to the <code>EmailReadMessages</code> function. |
*[[#EmailLastError|EmailLastError]] — Returns detailed information about the last error generated by this plugin. | *[[#EmailLastError|EmailLastError]] — Returns detailed information about the last error generated by this plugin. | ||
*[[#EmailLicenseInfo|EmailLicenseInfo]] — Retrieve information about the Email plugin licensing and version. | *[[#EmailLicenseInfo|EmailLicenseInfo]] — Retrieve information about the Email plugin licensing and version. | ||
*[[#EmailListMailboxes|EmailListMailboxes]] ( { ; parent ; recursive } ) — Gets a return-separated list of mailboxes in a specific folder on the currently connected inbound mail server (Note: this is only useful for IMAP mailboxes, not POP). | *[[#EmailListMailboxes|EmailListMailboxes]] ( { ; parent ; recursive } ) — Gets a return-separated list of mailboxes in a specific folder on the currently connected inbound mail server (Note: this is only useful for IMAP mailboxes, not POP). | ||
*[[#EmailMessageSetFlag|EmailMessageSetFlag]] ( flag { ; value } ) — Applies a flag to the current message, as retrieved by the function {@link #EmailGetNextMessage()}. | *[[#EmailMessageSetFlag|EmailMessageSetFlag]] ( flag { ; value } ) — Applies a flag to the current message, as retrieved by the function {@link #EmailGetNextMessage()}. | ||
− | *[[#EmailOutgoingMessageId|EmailOutgoingMessageId]] — Returns the Message-ID of the last message sent using the Emailer plugin. | + | *[[#EmailMoveCurrentMessage|EmailMoveCurrentMessage]] ( folder ) — Moves a message on an IMAP mailbox. |
+ | *[[#EmailOutgoingMessageId|EmailOutgoingMessageId]] ( ) — Returns the Message-ID of the last message sent using the Emailer plugin. | ||
*[[#EmailQuickSend|EmailQuickSend]] ( from ; to ; subject ; body {; attachment } ) — Convenient way to send a single simple message to one or more recipients. | *[[#EmailQuickSend|EmailQuickSend]] ( from ; to ; subject ; body {; attachment } ) — Convenient way to send a single simple message to one or more recipients. | ||
*[[#EmailReadAttachment|EmailReadAttachment]] ( path ) — Read a downloaded attachment into a FileMaker container field. | *[[#EmailReadAttachment|EmailReadAttachment]] ( path ) — Read a downloaded attachment into a FileMaker container field. | ||
*[[#EmailReadMessages|EmailReadMessages]] ( { flag1 ; flag2 ; ... } ) — Reads messages from the currently connected inbound mail server. | *[[#EmailReadMessages|EmailReadMessages]] ( { flag1 ; flag2 ; ... } ) — Reads messages from the currently connected inbound mail server. | ||
+ | *[[#EmailReadMessagesFromFile|EmailReadMessagesFromFile]] ( file { ; charset=UTF-8 } ) — This reads messages from an non-directory <code>MBOX</code> file or raw message content file (<code>. | ||
*[[#EmailReadMessageValue|EmailReadMessageValue]] ( key ) — Retrieves information about the last message which was gotten by the <code>EmailGetNextMessage</code> function. | *[[#EmailReadMessageValue|EmailReadMessageValue]] ( key ) — Retrieves information about the last message which was gotten by the <code>EmailGetNextMessage</code> function. | ||
*[[#EmailRecipients|EmailRecipients]] ( to_addresses { ; append } ) — Set the TO recipients for the current message. | *[[#EmailRecipients|EmailRecipients]] ( to_addresses { ; append } ) — Set the TO recipients for the current message. | ||
*[[#EmailRegister|EmailRegister]] ( licenseKey ; registeredTo ) — Registers the Email Plugin. | *[[#EmailRegister|EmailRegister]] ( licenseKey ; registeredTo ) — Registers the Email Plugin. | ||
− | *[[#EmailSend|EmailSend]] — Send the current email, as | + | *[[#EmailSend|EmailSend]] ( { progress=true ; progressLocation=100,200 ; ... } ) — Send the current email, as defined in the {@link #EmailCreate}, {@link #EmailSetSubject}, {@link #EmailSetBody}, and other functions. |
*[[#EmailSetBody|EmailSetBody]] ( body { ; contentType ; characterSet } ) — Sets a body part of the current message. | *[[#EmailSetBody|EmailSetBody]] ( body { ; contentType ; characterSet } ) — Sets a body part of the current message. | ||
*[[#EmailSetBodyFile|EmailSetBodyFile]] ( url ; embedResources ) — This is used to load an HTML document as the email body part. | *[[#EmailSetBodyFile|EmailSetBodyFile]] ( url ; embedResources ) — This is used to load an HTML document as the email body part. | ||
− | *[[#EmailSetErrorCapture|EmailSetErrorCapture]] ( errorCapture ) — | + | *[[#EmailSetErrorCapture|EmailSetErrorCapture]] ( errorCapture ) — Toggles error dialogs on or off. |
*[[#EmailSetHeader|EmailSetHeader]] ( header ; value ) — Set a custom header in the message. | *[[#EmailSetHeader|EmailSetHeader]] ( header ; value ) — Set a custom header in the message. | ||
*[[#EmailSetSubject|EmailSetSubject]] ( subject ) — This allows you to customize the subject of the current outgoing email message, as specified in the {@link #EmailCreate} function. | *[[#EmailSetSubject|EmailSetSubject]] ( subject ) — This allows you to customize the subject of the current outgoing email message, as specified in the {@link #EmailCreate} function. | ||
+ | *[[#EmailSuppressErrorDialogs|EmailSuppressErrorDialogs]] ( trueOrFalse ) — To suppress all error dialogs for this plugin, call <code>EmailSuppressErrorDialogs(true)</code>. | ||
*[[#EmailVersion|EmailVersion]] — Returns the version number of the Email plugin. | *[[#EmailVersion|EmailVersion]] — Returns the version number of the Email plugin. | ||
+ | *[[#IM_Disconnect|IM_Disconnect]] ( { service ; login } ) — Disconnects user from all connected services. | ||
+ | *[[#IM_GetBuddyIcon|IM_GetBuddyIcon]] ( service ; login ; password ; buddy ) — Returns a buddy's icon. | ||
+ | *[[#IM_GetBuddyList|IM_GetBuddyList]] ( service ; login ; password ) — Connects to the messaging service (if necessary) and retrieves the user's buddy list. | ||
+ | *[[#IM_GetBuddyStatusMessage|IM_GetBuddyStatusMessage]] ( service ; login ; password ; buddy ) — Returns a buddy's status. | ||
+ | *[[#IM_GetBuddyStatusType|IM_GetBuddyStatusType]] ( service ; login ; password ; buddy ) — Returns a buddy's status type as one of the following: "online", "idle", "away", "mobile", or "offline". | ||
+ | *[[#IM_SendMessage|IM_SendMessage]] ( service ; login ; password ; recipient ; message ) — Connects to the messaging service (if necessary) and sends a plain text message to the recipient recipient. | ||
*[[#IsValidEmail|IsValidEmail]] ( email ) — Convenience function for validating an email address. | *[[#IsValidEmail|IsValidEmail]] ( email ) — Convenience function for validating an email address. | ||
</div> | </div> | ||
Line 215: | Line 251: | ||
If called on a machine running Mac OS X, a file URL is created from a path by prepending the directory <code>/Volumes</code> to the supplied path, since FileMaker includes the hard drive name in paths. | If called on a machine running Mac OS X, a file URL is created from a path by prepending the directory <code>/Volumes</code> to the supplied path, since FileMaker includes the hard drive name in paths. | ||
For example, <code>/MacintoshHD/Users/John Smith/Documents/</code> is converted to the file URL <code>file:///Volumes/MacintoshHD/Users/John Smith/Documents/</code>. | For example, <code>/MacintoshHD/Users/John Smith/Documents/</code> is converted to the file URL <code>file:///Volumes/MacintoshHD/Users/John Smith/Documents/</code>. | ||
+ | |||
+ | <h3>Auto-zip of attached directories</h3> | ||
+ | If the path points to a directory/folder instead of a file, the email plugin will automatically zip the contents of the folder into a temporary file and send that as the attachment. This allows sending of Mac OS X bundles such as <code>.pages</code> files, etc. | ||
<div class="parameters"><strong>Parameters:</strong> | <div class="parameters"><strong>Parameters:</strong> | ||
− | <dl><dt><code>data</code> <dd>a path to a file, or a URL pointing to a file to attach to the message. | + | <dl><dt><code>data</code> <dd>a container, path to a file, or a URL pointing to a file to attach to the message. |
</dl></div> | </dl></div> | ||
<div class="see"><strong>Returns:</strong> 1 on success, ERROR on error. | <div class="see"><strong>Returns:</strong> 1 on success, ERROR on error. | ||
Line 292: | Line 331: | ||
</dl></div> | </dl></div> | ||
<div class="see"><strong>Returns:</strong> 1 on success, ERROR if one or more addresses are invalid. | <div class="see"><strong>Returns:</strong> 1 on success, ERROR if one or more addresses are invalid. | ||
+ | </div> | ||
+ | |||
+ | <div id="EmailChooseFile"></div> | ||
+ | ==EmailChooseFile ( { initialPath ; fileType ; title } ) == | ||
+ | Shows a file chooser dialog where a user can browse her local hard drive. When the user selects a file or directory and clicks "OK" on the file chooser, | ||
+ | this function returns the path to the selected file or directory. If the user hits the cancel button, nothing is returned. | ||
+ | |||
+ | <h3>File Type</h3> | ||
+ | By supplying a <code>fileType</code> parameter, you can allow the user to just select files, just select directories, or select both files and directories. The default behavior is to only allow file selection. | ||
+ | |||
+ | |||
+ | Note: specifying a fileType of "directories" or "files + directories" will cause a non-native file dialog to be used on some platforms, as the native dialogs may not support directory selection. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>initialPath</code> <dd>optional path to set the initial dialog selection to. If empty, will default to the user's home directory. | ||
+ | <dt><code>fileType</code> <dd>whether to allow <code>"files"</code>, <code>"directories"</code>, or both <code>"files + directories"</code> | ||
+ | <dt><code>title</code> <dd>optional title string to display as the title of the FileChooser dialog | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> Path to the selected file, nothing if no file was selected, or "ERROR" if an error occurred. | ||
</div> | </div> | ||
<div id="EmailConnect"></div> | <div id="EmailConnect"></div> | ||
==EmailConnect ( host_address_deprecated { ; user_deprecated ; password_deprecated } ) == | ==EmailConnect ( host_address_deprecated { ; user_deprecated ; password_deprecated } ) == | ||
− | + | Use [[#EmailConnectSMTP|EmailConnectSMTP]] instead. The username and password are optional, and may not be required for sending mail. | |
This establishes a connection to the email server. When you are finished getting/sending email, you should call [[#EmailDisconnect|EmailDisconnect]] to close the connection. | This establishes a connection to the email server. When you are finished getting/sending email, you should call [[#EmailDisconnect|EmailDisconnect]] to close the connection. | ||
Line 305: | Line 363: | ||
</dl></div> | </dl></div> | ||
<div class="see"><strong>See also:</strong> [[#EmailConnectSMTP|EmailConnectSMTP]], [[#EmailConnectPOP|EmailConnectPOP]], [[#EmailConnectIMAP|EmailConnectIMAP]] | <div class="see"><strong>See also:</strong> [[#EmailConnectSMTP|EmailConnectSMTP]], [[#EmailConnectPOP|EmailConnectPOP]], [[#EmailConnectIMAP|EmailConnectIMAP]] | ||
+ | </div> | ||
+ | |||
+ | <div id="EmailConnectAmazon"></div> | ||
+ | ==EmailConnectAmazon ( accessKey; secretKey ) == | ||
+ | Connect to the Amazon Simple Email Service (SES) servers for sending email. Communication happens via HTTPS protocol instead of SMTP, this can be especially useful when using the plugin in environments that only allow communication over HTTP/HTTPS. | ||
+ | |||
+ | You can sign up for this service at http://aws.amazon.com/ses/. You will need to follow the Amazon sign-up steps to get your keys and register your email address before you can send emails using this service. | ||
+ | |||
+ | Example: <code>EmailConnectAmazon( "nf298nrc23r"; "208chr29-hrc-29hr1983f")</code> | ||
+ | |||
+ | It's also possible to use Amazon SES via SMTP. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>accessKey</code> <dd> | ||
+ | <dt><code>secretKey</code> <dd> | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> successValue | ||
</div> | </div> | ||
<div id="EmailConnectIMAP"></div> | <div id="EmailConnectIMAP"></div> | ||
− | ==EmailConnectIMAP ( host ; username ; password { ; | + | ==EmailConnectIMAP ( host ; username ; password { ; ssl=true ; forceTrust=true ; tls=true ; ... } ) == |
Connect to an incoming IMAP mail server. This function (or <code>EmailConnectPOP</code>) must be called before reading email messages from the server. | Connect to an incoming IMAP mail server. This function (or <code>EmailConnectPOP</code>) must be called before reading email messages from the server. | ||
This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call [[#EmailDisconnect|EmailDisconnect]] to close the connection. | This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call [[#EmailDisconnect|EmailDisconnect]] to close the connection. | ||
Line 325: | Line 400: | ||
<h3>SSL Encryption</h3> | <h3>SSL Encryption</h3> | ||
Use the optional arguments to enable SSL encryption by passing <code>"ssl=1"</code>. If you are connecting to GMail, SSL encryption is required. | Use the optional arguments to enable SSL encryption by passing <code>"ssl=1"</code>. If you are connecting to GMail, SSL encryption is required. | ||
− | Here is an example of connecting to google mail (gmail) with SSL encryption: | + | Here is an example of connecting to google mail (gmail) with SSL encryption, and expunge set to true: |
Set Variable[$result = | Set Variable[$result = | ||
Line 332: | Line 407: | ||
"username" ; | "username" ; | ||
"password" ; | "password" ; | ||
− | '''"ssl=1"''' | + | '''"ssl=1"''' ; |
+ | '''"expunge=true"''' | ||
) | ) | ||
] | ] | ||
+ | <h3>Optional Flags</h3> | ||
+ | The following can be passed as additional parameters to the EmailConnectIMAP function: | ||
+ | <dl> | ||
+ | <dt>ssl<dd>pass <code>true</code> to enable SSL encryption. Some mail services (like gmail) require this. | ||
+ | <dt>expunge<dd>pass <code>true</code> or <code>false</code> to determine whether flagging a message for deletion permanently removes the message from your mail server. If unspecified, messages are only removed/expunged if the server does not support deleted flags. | ||
+ | </dl> | ||
<div class="parameters"><strong>Parameters:</strong> | <div class="parameters"><strong>Parameters:</strong> | ||
Line 341: | Line 423: | ||
<dt><code>username</code> <dd>The authentication username | <dt><code>username</code> <dd>The authentication username | ||
<dt><code>password</code> <dd>The authentication password | <dt><code>password</code> <dd>The authentication password | ||
− | <dt><code>args</code> <dd>Additional optional arguments (ssl). | + | <dt><code>args</code> <dd>Additional optional arguments (ssl, forceTrust, tls). |
</dl></div> | </dl></div> | ||
<div class="see"><strong>See also:</strong> [[#EmailDisconnect|EmailDisconnect]] | <div class="see"><strong>See also:</strong> [[#EmailDisconnect|EmailDisconnect]] | ||
Line 348: | Line 430: | ||
<div id="EmailConnectPOP"></div> | <div id="EmailConnectPOP"></div> | ||
− | ==EmailConnectPOP ( host ; username ; password { ; | + | ==EmailConnectPOP ( host ; username ; password { ; ssl=true ; forceTrust=true ; tls=true ; ... } ) == |
Connect to an incoming POP mail server. This function (or <code>EmailConnectIMAP</code>) must be called before reading email messages from the server. | Connect to an incoming POP mail server. This function (or <code>EmailConnectIMAP</code>) must be called before reading email messages from the server. | ||
This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call [[#EmailDisconnect|EmailDisconnect]] to close the connection. | This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call [[#EmailDisconnect|EmailDisconnect]] to close the connection. | ||
+ | <b>Note:</b> We strongly recommend using IMAP instead of POP with Gmail due to possible confusion over Gmail's labels and tags. | ||
+ | <p /> | ||
Here is an example of connecting to a regular mail server: | Here is an example of connecting to a regular mail server: | ||
Line 382: | Line 466: | ||
<dt><code>username</code> <dd>The authentication username | <dt><code>username</code> <dd>The authentication username | ||
<dt><code>password</code> <dd>The authentication password | <dt><code>password</code> <dd>The authentication password | ||
− | <dt><code>args</code> <dd>Additional optional arguments (ssl). | + | <dt><code>args</code> <dd>Additional optional arguments (ssl, forceTrust, tls). |
</dl></div> | </dl></div> | ||
<div class="see"><strong>See also:</strong> [[#EmailDisconnect|EmailDisconnect]] | <div class="see"><strong>See also:</strong> [[#EmailDisconnect|EmailDisconnect]] | ||
Line 389: | Line 473: | ||
<div id="EmailConnectSMTP"></div> | <div id="EmailConnectSMTP"></div> | ||
− | ==EmailConnectSMTP ( host { ; username ; password ; | + | ==EmailConnectSMTP ( host { ; username ; password ; ssl=true ; forceTrust=true ; tls=true ; timeout=10 ; ... } ) == |
Connect to an outgoing SMTP mail server. This function must be called before sending mail. The username and password are optional, and may not be required for sending mail, depending on your SMTP server's setup. | Connect to an outgoing SMTP mail server. This function must be called before sending mail. The username and password are optional, and may not be required for sending mail, depending on your SMTP server's setup. | ||
This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call [[#EmailDisconnect|EmailDisconnect]] to close the connection. | This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call [[#EmailDisconnect|EmailDisconnect]] to close the connection. | ||
+ | |||
+ | |||
+ | <b>Note:</b> By default, Gmail will set the "from" address to the email address used with EmailConnectSMTP for all outbound messages. If you want to set the "from" address to a different email address, you must | ||
+ | add the desired email address manually in Gmail Settings. | ||
Here is an example of connecting to a regular mail server: | Here is an example of connecting to a regular mail server: | ||
Line 406: | Line 494: | ||
<h3>SSL Encryption</h3> | <h3>SSL Encryption</h3> | ||
− | Use the optional arguments to enable SSL encryption by passing <code>"ssl=1"</code>. If you are connecting to | + | Use the optional arguments to enable SSL encryption by passing <code>"ssl=1"</code>. If you are connecting to Gmail, SSL encryption is required. |
− | Here is an example of connecting to | + | Here is an example of connecting to Gmail with SSL encryption: |
Set Variable[$result = | Set Variable[$result = | ||
Line 423: | Line 511: | ||
<dt><code>username</code> <dd>The optional SMTP authentication username | <dt><code>username</code> <dd>The optional SMTP authentication username | ||
<dt><code>password</code> <dd>The optional SMTP authentication password | <dt><code>password</code> <dd>The optional SMTP authentication password | ||
− | <dt><code>args</code> <dd>Additional optional arguments (ssl). | + | <dt><code>args</code> <dd>Additional optional arguments (ssl=true, forceTrust=true, tls=true, timeout=<<seconds>>). |
</dl></div> | </dl></div> | ||
<div class="see"><strong>See also:</strong> [[#EmailDisconnect|EmailDisconnect]] | <div class="see"><strong>See also:</strong> [[#EmailDisconnect|EmailDisconnect]] | ||
− | </div><div class="see"><strong>Returns:</strong> 1 on successful connection, or "ERROR" if an error occurred (use | + | </div><div class="see"><strong>Returns:</strong> 1 on successful connection, or "ERROR" if an error occurred (use EmailLastError in this case) |
</div> | </div> | ||
Line 434: | Line 522: | ||
<div class="parameters"><strong>Parameters:</strong> | <div class="parameters"><strong>Parameters:</strong> | ||
− | <dl><dt><code>from</code> <dd>the FROM address for the new message. Use "Name <you@domain.com>" for displaying the name instead. | + | <dl><dt><code>from</code> <dd>the FROM address for the new message. Use "Name <you@domain.com>" for displaying the name instead. |
<dt><code>to</code> <dd>the TO address for the new message | <dt><code>to</code> <dd>the TO address for the new message | ||
<dt><code>subject</code> <dd>the SUBJECT of the new message | <dt><code>subject</code> <dd>the SUBJECT of the new message | ||
Line 442: | Line 530: | ||
<div id="EmailDisconnect"></div> | <div id="EmailDisconnect"></div> | ||
− | ==EmailDisconnect== | + | ==EmailDisconnect ( ) == |
Close any open connections to email servers established via the EmailConnect... functions. | Close any open connections to email servers established via the EmailConnect... functions. | ||
Line 460: | Line 548: | ||
<div id="EmailGetNextMessage"></div> | <div id="EmailGetNextMessage"></div> | ||
− | ==EmailGetNextMessage== | + | ==EmailGetNextMessage ( ) == |
Loads a single message which was fetched in a previous call to the <code>EmailReadMessages</code> function. | Loads a single message which was fetched in a previous call to the <code>EmailReadMessages</code> function. | ||
Line 522: | Line 610: | ||
</dl></div> | </dl></div> | ||
<div class="see"><strong>Returns:</strong> 1 on successful delete, or "ERROR" if an error occurred (use EMailLastError in this case) | <div class="see"><strong>Returns:</strong> 1 on successful delete, or "ERROR" if an error occurred (use EMailLastError in this case) | ||
+ | </div> | ||
+ | |||
+ | <div id="EmailMoveCurrentMessage"></div> | ||
+ | ==EmailMoveCurrentMessage ( folder ) == | ||
+ | Moves a message on an IMAP mailbox. This operates either on the current message queued for delivery in FileMaker, or on the most recently fetched message from the IMAP server. | ||
+ | <h3>Saving Outgoing Messages</h3> | ||
+ | |||
+ | To save a copy of an outgoing message in your "Sent" mailbox, you can do something like the following: | ||
+ | |||
+ | EmailCreate( "my@mydomain.com" ; "bob@example.com" ; "Moving a test message" ) and | ||
+ | EmailSetBody( "Hi Bob! I'm saving a copy of this in my 'Sent' folder" ) and | ||
+ | EmailSend and | ||
+ | EmailMoveCurrentMessage( "Sent" ) | ||
+ | |||
+ | The above example assumes that you are already connected both to your IMAP server and your SMTP server. | ||
+ | First we create a message and set the message body. | ||
+ | Next, we deliver the message by calling EmailSend. | ||
+ | Finally, If the message was delivered successfully, we save it to the "Sent" folder on our IMAP mailbox. | ||
+ | <h3>Moving Existing Messages</h3> | ||
+ | |||
+ | To move existing messages on your IMAP mailbox, call <code>EmailMoveCurrentMessage</code> after fetching the message with [[#EmailGetNextMessage|EmailGetNextMessage]]. | ||
+ | This will copy the message to the destination mailbox, creating the mailbox if it doesn't exist. If the original mailbox has <code>readonly=false</code> specified, the message is flagged for deletion from the original mailbox. | ||
+ | This can be useful for processing all messages in a certain folder, then moving them to a "processed" folder on the mailserver, for example. | ||
+ | |||
+ | Set Variable [ $result = EmailReadMessages( "readonly=false" ) ] | ||
+ | If [$result = "ERROR"] | ||
+ | # Handle Error Here... | ||
+ | End If | ||
+ | Loop | ||
+ | Exit Loop If [not EmailGetNextMessage] | ||
+ | // DO SOMETHING INTERESTING WITH THE MESSAGE HERE... | ||
+ | Set Variable [ $moveResult = EmailMoveCurrentMessage ("Processed") ] | ||
+ | End Loop | ||
+ | |||
+ | The above script fetches all messages in the INBOX, then loops through them, performing some action on each message, then moving the message to the "Processed" mailbox. | ||
+ | NOTE: the <code>readonly=false</code> is required for the processed messages to be removed from the mailbox. If not specified, the messages will still remain in the original mailbox. | ||
+ | |||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>folder</code> <dd>the name of the folder to move the message to | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> 1 on success, "ERROR" on error (use EmailLastError to get a detailed error message) | ||
</div> | </div> | ||
<div id="EmailOutgoingMessageId"></div> | <div id="EmailOutgoingMessageId"></div> | ||
− | ==EmailOutgoingMessageId== | + | ==EmailOutgoingMessageId ( ) == |
Returns the Message-ID of the last message sent using the Emailer plugin. | Returns the Message-ID of the last message sent using the Emailer plugin. | ||
Line 538: | Line 668: | ||
<div class="parameters"><strong>Parameters:</strong> | <div class="parameters"><strong>Parameters:</strong> | ||
− | <dl><dt><code>from</code> <dd>The "from" email address. Use "Name <you@domain.com> | + | <dl><dt><code>from</code> <dd>The "from" email address. Use "Name <you@domain.com> for displaying the name instead. |
<dt><code>to</code> <dd>A comma-separated list of "to" email addresses | <dt><code>to</code> <dd>A comma-separated list of "to" email addresses | ||
<dt><code>subject</code> <dd>The subject of the message | <dt><code>subject</code> <dd>The subject of the message | ||
Line 579: | Line 709: | ||
The Email plugin supports reading messages from POP and IMAP mailboxes. Typically, you're interested in only fetching new messages from your mailbox. There are several approaches to doing this. | The Email plugin supports reading messages from POP and IMAP mailboxes. Typically, you're interested in only fetching new messages from your mailbox. There are several approaches to doing this. | ||
− | <h4>Option 1: Search by UID (IMAP | + | <h4>Option 1: Search by UID (IMAP or POP3)</h4> |
− | IMAP mailboxes assign each message a unique UID. When reading messages from an IMAP mailbox, you can get the value for this UID with the following function: | + | <b>Note:</b> POP3 mail servers are not required to support UIDs. Please check with the server administrator about UID support. |
+ | IMAP and POP3 mailboxes assign each message a unique UID. When reading messages from an IMAP or POP3 mailbox, you can get the value for this UID with the following function: | ||
Set Field[ImportedMessage::uid ; EmailReadMessageValue( "uid" ) ] | Set Field[ImportedMessage::uid ; EmailReadMessageValue( "uid" ) ] | ||
Line 592: | Line 723: | ||
] | ] | ||
− | This fetches only the messages whose UID is greater than the most recently fetched message. This is the preferred way to fetch new messages from | + | This fetches only the messages whose UID is greater than the most recently fetched message. This is the preferred way to fetch new messages from a mailbox, as it is very efficient, doesn't modify any messages, and will work even if another email client accesses the mailbox. |
Line 642: | Line 773: | ||
<dt>progress | <dt>progress | ||
<dd>Whether to show a cancellable progress bar (default is false). | <dd>Whether to show a cancellable progress bar (default is false). | ||
+ | <dt>progressLocation | ||
+ | <dd>Location of the progress bar, e.g. "<code>100,200</code>". Default is centered on-screen. | ||
<dt>mailbox | <dt>mailbox | ||
<dd>The name of the mailbox to read messages from (Note: this is only useful for IMAP accounts). The default behavior is to read messages from the <code>INBOX</code>. | <dd>The name of the mailbox to read messages from (Note: this is only useful for IMAP accounts). The default behavior is to read messages from the <code>INBOX</code>. | ||
<dt>attachments | <dt>attachments | ||
− | <dd>Boolean flag indicating whether to download attachment data. The default value is <code> | + | <dd>Boolean flag indicating whether to download attachment data. The default value is <code>true</code>, which enables attachment downloading. Setting this to <code>false</code> will disable downloading attachments, which can be significantly faster. |
If attachment downloading is disabled, you can still retrieve a list of the attachments in a message using the <code>EmailReadMessageValue ( "attachments" )</code> function. You can the re-read the message at a later time to download the attachments (see the EmailClient.fp7 example file). | If attachment downloading is disabled, you can still retrieve a list of the attachments in a message using the <code>EmailReadMessageValue ( "attachments" )</code> function. You can the re-read the message at a later time to download the attachments (see the EmailClient.fp7 example file). | ||
Line 653: | Line 786: | ||
<dd>Do not return more than this many records in the import | <dd>Do not return more than this many records in the import | ||
<dt>uid | <dt>uid | ||
− | <dd>( | + | <dd>(<b>Note:</b> not all POP3 mail servers support UIDs) only fetch messages whose <code>uid</code> is newer than the one passed in. This is very useful for only fetching new messages from IMAP mailboxes. When looping through new messages, call <code>EmailReadMessageValue("uid")</code> on the last message and save this to a field in your database. Then when fetching new messages, pass this <code>uid</code> in as a filter argument. Only newer messages will be returned. <strong>Note:</strong> if you specify this option and the mailbox is an IMAP mailbox, all other search filters (skip, max, to, from, date, etc) will be ignored. |
+ | <dt>dateFrom | ||
+ | <dd>Filter messages to only return messages sent on or after a certain date (some IMAP mailboxes require an additional flag of "deleted=any" for EmailReadMessages to read emails using this parameter). | ||
+ | <dt>dateTo | ||
+ | <dd>Filter messages to only return messages sent on or before a certain date (some IMAP mailboxes require an additional flag of "deleted=any" for EmailReadMessages to read emails using this parameter). | ||
<dt>from | <dt>from | ||
<dd>Filter messages by <code>from</code> address | <dd>Filter messages by <code>from</code> address | ||
Line 669: | Line 806: | ||
<dd>Filter messages by their flagged status. Pass <code>true</code> to return only flagged messages, <code>false</code> to return only non-flagged messages. | <dd>Filter messages by their flagged status. Pass <code>true</code> to return only flagged messages, <code>false</code> to return only non-flagged messages. | ||
<dt>deleted | <dt>deleted | ||
− | <dd>Filter messages by their deleted status. Pass <code>true</code> to return only deleted messages, <code>false</code> to return only non-deleted messages. | + | <dd>Filter messages by their deleted status. Pass <code>true</code> to return only deleted messages, <code>false</code> to return only non-deleted messages The default is <code>false</code>, meaning deleted message will be excluded. |
<dt>readonly | <dt>readonly | ||
<dd>Whether to open the mailbox folder as readonly or read-write. The default is <code>true</code> (read-only). | <dd>Whether to open the mailbox folder as readonly or read-write. The default is <code>true</code> (read-only). | ||
Line 692: | Line 829: | ||
<div class="see"><strong>See also:</strong> [[#EmailConnectIMAP|EmailConnectIMAP]], [[#EmailConnectPOP|EmailConnectPOP]], [[#EmailGetNextMessage|EmailGetNextMessage]], [[#EmailReadMessageValue|EmailReadMessageValue]] | <div class="see"><strong>See also:</strong> [[#EmailConnectIMAP|EmailConnectIMAP]], [[#EmailConnectPOP|EmailConnectPOP]], [[#EmailGetNextMessage|EmailGetNextMessage]], [[#EmailReadMessageValue|EmailReadMessageValue]] | ||
</div><div class="see"><strong>Returns:</strong> The URL of the local XML file. This URL can be passed to FileMaker as the XML data source location. | </div><div class="see"><strong>Returns:</strong> The URL of the local XML file. This URL can be passed to FileMaker as the XML data source location. | ||
+ | </div> | ||
+ | |||
+ | <div id="EmailReadMessagesFromFile"></div> | ||
+ | ==EmailReadMessagesFromFile ( file { ; charset=UTF-8 } ) == | ||
+ | This reads messages from an non-directory <code>MBOX</code> file or raw message content file (<code>.eml</code>), and stores the parsed messages in an FMPXML file, suitable for import into FileMaker. | ||
+ | In addition, you can use the [[#EmailGetNextMessage|EmailGetNextMessage]] function after calling this to loop over the messages and programatically read individual values using the [[#EmailReadMessageValue|EmailReadMessageValue]]. | ||
+ | <h3>Flags</h3> | ||
+ | The following is a description of the available flags: | ||
+ | <dl> | ||
+ | <dt>charset | ||
+ | <dd>Character set of the file. Leave this blank to use the default for your locale. | ||
+ | </dl> | ||
+ | |||
+ | Note: this will disconnect from your current mail server if there is an active connection. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>file</code> <dd>path to an MBOX file | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> URL to an FMPXML file containing the parsed messages in the file | ||
</div> | </div> | ||
Line 712: | Line 868: | ||
<li>sent (The timestamp the message was sent)</li> | <li>sent (The timestamp the message was sent)</li> | ||
<li>messageID (The unique message ID for the email message)</li> | <li>messageID (The unique message ID for the email message)</li> | ||
− | <li>attachments (A return-separated list of attachments for the message. Each line is either the attachment file path, or the name, depending on the value of the <code>attachments</code> parameter in <code>EmailReadMessages</code>)</li> | + | <li>attachments (A return-separated list of attachments for the message. Each line is either the attachment file path, or the name, depending on the value of the <code>attachments</code> parameter in <code>EmailReadMessages</code>). Note: inlined attachments are excluded from this list. Use <code>attachmentsAll</code> to get all attachments including inlined ones.</li> |
<li>text (The plain-text message content, if available)</li> | <li>text (The plain-text message content, if available)</li> | ||
− | <li>html (The HTML body part, if one is available)</li> | + | <li>html (The HTML body part, if one is available. If attachments are set to download, inline attachment images will be converted to base64 data URLs automatically. If you don't want this behavior, use <code>htmlRaw</code> instead, or set <code>attachments=false</code> when fetching messages.)</li> |
− | <li>uid ( | + | <li>htmlRaw (The HTML body part unaltered, if one is available.)</li> |
+ | <li>uid (returns the IMAP or POP3 folder uid <b>Note:</b> not all POP3 mail servers support UIDs)</li> | ||
<li>viewed (1 or empty to indicate whether the message has been read (1) or is unread)</li> | <li>viewed (1 or empty to indicate whether the message has been read (1) or is unread)</li> | ||
<li>flagged (1 or empty to indicate whether the message is flagged)</li> | <li>flagged (1 or empty to indicate whether the message is flagged)</li> | ||
Line 722: | Line 879: | ||
<li>header:<em>HEADER_NAME</em> (any header value, replace <em>HEADER_NAME</em> with the name of the header to retrieve) | <li>header:<em>HEADER_NAME</em> (any header value, replace <em>HEADER_NAME</em> with the name of the header to retrieve) | ||
<li>headers (a return-separated list of all message headers)</li> | <li>headers (a return-separated list of all message headers)</li> | ||
+ | <li>raw: (the raw source of the entire message)</li> | ||
</ul> | </ul> | ||
<h3>Reading Message Headers</h3> | <h3>Reading Message Headers</h3> | ||
Line 758: | Line 916: | ||
<div id="EmailSend"></div> | <div id="EmailSend"></div> | ||
− | ==EmailSend== | + | ==EmailSend ( { progress=true ; progressLocation=100,200 ; ... } ) == |
− | Send the current email, as | + | Send the current email, as defined in the [[#EmailCreate|EmailCreate]], [[#EmailSetSubject|EmailSetSubject]], [[#EmailSetBody|EmailSetBody]], and other functions. |
+ | <h3>Optional Parameters</h3> | ||
+ | <dl> | ||
+ | <dt>progress | ||
+ | <dd>Whether to show a progress bar. Default = <code>true</code>. | ||
+ | <dt>progressLocation | ||
+ | <dd>Location of the progress bar, e.g. "<code>100,200</code>". Default is centered on-screen. | ||
+ | </dl> | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>options</code> <dd>optional parameters | ||
+ | </dl></div> | ||
<div class="see"><strong>Returns:</strong> 1 on success, ERROR if something went wrong with sending the message | <div class="see"><strong>Returns:</strong> 1 on success, ERROR if something went wrong with sending the message | ||
</div> | </div> | ||
Line 806: | Line 975: | ||
<div id="EmailSetErrorCapture"></div> | <div id="EmailSetErrorCapture"></div> | ||
==EmailSetErrorCapture ( errorCapture ) == | ==EmailSetErrorCapture ( errorCapture ) == | ||
− | + | Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call EmailSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user. | |
<div class="parameters"><strong>Parameters:</strong> | <div class="parameters"><strong>Parameters:</strong> | ||
− | <dl></dl></div> | + | <dl><dt><code>errorCapture</code> <dd>set to true to suppress the default popups. |
+ | </dl></div> | ||
Line 816: | Line 986: | ||
Set a custom header in the message. This is not needed for the majority of cases. A list of header fields can be found | Set a custom header in the message. This is not needed for the majority of cases. A list of header fields can be found | ||
[http://en.wikipedia.org/wiki/Email#Header_fields here]. These should be modified by advanced users only. | [http://en.wikipedia.org/wiki/Email#Header_fields here]. These should be modified by advanced users only. | ||
+ | For Example (below is a short list of the more commonly used headers): | ||
+ | |||
+ | EmailSetHeader( "reply-to" ; "reply@example.com" ) | ||
+ | EmailSetHeader( "bcc" ; "blind@example.com" ) | ||
+ | EmailSetHeader( "subject" ; "List of Example Headers" ) | ||
+ | |||
<div class="parameters"><strong>Parameters:</strong> | <div class="parameters"><strong>Parameters:</strong> | ||
Line 833: | Line 1,009: | ||
</dl></div> | </dl></div> | ||
<div class="see"><strong>Returns:</strong> 1 on success | <div class="see"><strong>Returns:</strong> 1 on success | ||
+ | </div> | ||
+ | |||
+ | <div id="EmailSuppressErrorDialogs"></div> | ||
+ | ==EmailSuppressErrorDialogs ( trueOrFalse ) == | ||
+ | To suppress all error dialogs for this plugin, call <code>EmailSuppressErrorDialogs(true)</code>. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>trueOrFalse</code> <dd>1 or 0 | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> 1 on success, "ERROR" if an invalid parameter is passed | ||
</div> | </div> | ||
Line 840: | Line 1,026: | ||
<div class="see"><strong>Returns:</strong> a text version number | <div class="see"><strong>Returns:</strong> a text version number | ||
+ | </div> | ||
+ | |||
+ | <div id="IM_Disconnect"></div> | ||
+ | ==IM_Disconnect ( { service ; login } ) == | ||
+ | Disconnects user from all connected services. If login information is passed it, only that specific account is | ||
+ | disconnected. If only partial login info is passed it, all accounts are disconnected. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>service</code> <dd>optional parameter to disconnect from only the specific messaging service; currently only "AIM" is | ||
+ | supported | ||
+ | <dt><code>login</code> <dd>optional parameter to disconnect only the specific login/account name for the service | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> @return 1 on success, ERROR on failure | ||
+ | </div> | ||
+ | |||
+ | <div id="IM_GetBuddyIcon"></div> | ||
+ | ==IM_GetBuddyIcon ( service ; login ; password ; buddy ) == | ||
+ | Returns a buddy's icon. If the buddy doesn't have an icon set, a default one will be returned corresponding to the | ||
+ | buddy's messaging service. Note that if a connection is made shortly before the function is called, the returned | ||
+ | icon be the default even if the buddy does have one set. A subsequent call will return the appropriate icon after it | ||
+ | has been retrieved and cached by the plugin. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>service</code> <dd>the messaging service to use; currently only "AIM" is supported | ||
+ | <dt><code>login</code> <dd>login/account name for the service | ||
+ | <dt><code>password</code> <dd>the password for service account | ||
+ | <dt><code>buddy</code> <dd>the buddy whose icon to get | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> the buddy's icon as a container | ||
+ | </div> | ||
+ | |||
+ | <div id="IM_GetBuddyList"></div> | ||
+ | ==IM_GetBuddyList ( service ; login ; password ) == | ||
+ | Connects to the messaging service (if necessary) and retrieves the user's buddy list. The list is return-separated | ||
+ | and can easily be parsed using FileMaker's built-in <code>GetValue()</code> function. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>service</code> <dd>the messaging service to use; currently only "AIM" is supported | ||
+ | <dt><code>login</code> <dd>login/account name for the service | ||
+ | <dt><code>password</code> <dd>the password for service account | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> return-separated list of buddies | ||
+ | </div> | ||
+ | |||
+ | <div id="IM_GetBuddyStatusMessage"></div> | ||
+ | ==IM_GetBuddyStatusMessage ( service ; login ; password ; buddy ) == | ||
+ | Returns a buddy's status. If the buddy doesn't have a status set, an empty string is returned instead. Note that if | ||
+ | a connection is made shortly before the function is called, the returned status may still be blank even if the buddy | ||
+ | does have one set. A subsequent call will return the status after it has been retrieved and cached by the plugin. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>service</code> <dd>the messaging service to use; currently only "AIM" is supported | ||
+ | <dt><code>login</code> <dd>login/account name for the service | ||
+ | <dt><code>password</code> <dd>the password for service account | ||
+ | <dt><code>buddy</code> <dd>the buddy whose status to get | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> the buddy's current status; if no status is set, an empty string is returned | ||
+ | </div> | ||
+ | |||
+ | <div id="IM_GetBuddyStatusType"></div> | ||
+ | ==IM_GetBuddyStatusType ( service ; login ; password ; buddy ) == | ||
+ | Returns a buddy's status type as one of the following: "online", "idle", "away", "mobile", or "offline". If the | ||
+ | buddy doesn't have a status set, an empty string is returned instead. Note that if a connection is made shortly | ||
+ | before the function is called, the returned status type may still be blank even if the buddy does have one set. A | ||
+ | subsequent call will return the status type after it has been retrieved and cached by the plugin. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>service</code> <dd>the messaging service to use; currently only "AIM" is supported | ||
+ | <dt><code>login</code> <dd>login/account name for the service | ||
+ | <dt><code>password</code> <dd>the password for service account | ||
+ | <dt><code>buddy</code> <dd>the buddy whose status type to get | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> the buddy's current status type | ||
+ | </div> | ||
+ | |||
+ | <div id="IM_SendMessage"></div> | ||
+ | ==IM_SendMessage ( service ; login ; password ; recipient ; message ) == | ||
+ | Connects to the messaging service (if necessary) and sends a plain text message to the recipient recipient. This | ||
+ | function can also send SMS messages if used with AIM as the service. The recipient recipient in this case would be a | ||
+ | phone number, prefixed with "+1". For example, to send a SMS to 555-123-4567, enter "+15551234567" as the recipient. | ||
+ | |||
+ | <div class="parameters"><strong>Parameters:</strong> | ||
+ | <dl><dt><code>service</code> <dd>the messaging service to use; currently only "AIM" is supported | ||
+ | <dt><code>login</code> <dd>login/account name for the service | ||
+ | <dt><code>password</code> <dd>the password for service account | ||
+ | <dt><code>recipient</code> <dd>the recipient of the message; can be phone number if sending SMS through AIM | ||
+ | <dt><code>message</code> <dd>the message to send | ||
+ | </dl></div> | ||
+ | <div class="see"><strong>Returns:</strong> 1 on success, ERROR on failure | ||
</div> | </div> | ||
Revision as of 21:37, 15 December 2014
360Works Email User Guide
Every program attempts to expand until it can read mail. Those programs which cannot so expand are replaced by ones which can.
-Jamie Zawinski's Law of Software Envelopment
The 360Works Email Plugin offers the following advantages over FileMaker's built-in mail functionality:
- Read messages from a mailbox (POP, IMAP)
- Works with Instant Web Publishing / Schedules Server Scripts
- Send multiple attachments in a single message
- Send formatted (HTML, etc) emails
- Speedy delivery of many messages by re-using a single connection to the server
- Set custom email headers
Example Usages
EmailQuickSend, the easiest way to fire off a single email:
Set Variable [ $result = EmailRegister( "mylicensekey", "My Company" ) and EmailConnectSMTP( "mail.example.com" ) and EmailQuickSend( Email::from ; // required "from" address Email::to ; // comma-separated list of addresses Email::subject ; // subject of the message Email::body ; // message body Email::attach // path or URL or container to attach ) and EmailDisconnect ]
Sending a plain-text email with one attachment:
Set Variable [ $result = EmailRegister("myLicenseKey"; "My Company") and EmailConnectSMTP( "mail.example.com" ) and EmailCreate( Email::from ; Email::to ; Email::subject ) and EmailSetBody( Email::body ; "plain" ) and EmailAttachFile( $attachment ) and EmailSend and EmailDisconnect ]
Sending an HTML-formatted email (converts formatted FileMaker text to HTML using the GetAsCSS
function):
Set Variable [ $result = EmailRegister("myLicenseKey"; "My Company") and EmailConnectSMTP( "mail.example.com" ) and EmailCreate( Email::from ; Email::to ; Email::subject ) and EmailSetBody( GetAsCSS( Email::body ); "html" ) and EmailSend and EmailDisconnect ]
Sending a single message multiple times to different recipients can be done by creating a message using EmailCreate, then calling
EmailRecipients and EmailSend multiple times. If you are sending large messages with attachments, this avoids the overhead of
creating a separate message for each recipient.
You can also send a single message to multiple TO, CC, or BCC recipients by passing a comma-separated list of addresses.
Note: Email is sent from whichever machine the plugin is being used on, be sure to open up port 25 for outgoing SMTP access on those machines.
Displaying a name instead of the FROM address
The "from" field can be either an email address "you@yourdomain.com" or a name and email address like "FirstName LastName <you@yourdomain.com>" instead. Most email clients will then display the name in the from field instead of the address. However, if the address is already in address book, most clients are configured to preempt with that associated name instead.
Sending Attachments
The EmailAttachFile accepts several different types of arguments. You can pass in a container field URL, or a path.
A URL can be to a resource on the web, or can be a file url pointing to a local file (e.g. file:///path/to/attachment.jpg
).
Bulk Mail
When sending to multiple recipients, instead of creating a new message for each recipient, you can create a single message, connect once to your server, and then send the same message multiple times, switching the subject, recipients, and message body for each recipient.
// First connect to the SMTP server and create the message. Set Variable [ $msgCreate = EmailConnectSMTP( "mail.example.com" ) and EmailCreate( Email::from ; Email::to ; Email::subject ) and EmailSetBody( GetAsCSS( Email::body ); "html" ) ] Go To Record/Request [ First ] Loop Set Variable [ $setRecipients = EmailRecipients [ Email::to ] ] Set Variable [ $msgSend = EmailSend ] Go To Record/Request [ Next ; Exit After Last ] End Loop // We've sent the same message to all recipients. Now disconnect Set Variable [ $disconnect = EmailDisconnect ]
Reading Mail
Version 1.3 of the Email Plugin introduced support for reading messages from a mailbox. The API for reading messages was revised in version 1.6.
- First call EmailConnectPOP or EmailConnectIMAP to connect to a server. If you will be reading emails, you must specify a username & password.
- Next, use the EmailListMailboxes function to get a list of mailboxes for the account.
- Then, you can call EmailReadMessages to get a list of messages in a certain mailbox.
- Create records for the email messages. You can either import the messages as XML data or iterate over them using the EmailGetNextMessage and EmailReadMessageValue functions
- Finally, it's a good idea to call EmailDisconnect to close the connection to the server when you no longer need it.
Here is a brief example of how to read the first 25 unread messages from the server:
set variable $registerResult = EmailRegister ( license ; company ) // check for registration success here set variable $connectResult = EmailConnectIMAP( server ; username ; password ) // check for connection success here set variable $$importUrl = EmailReadMessages ( "mailbox=INBOX" ; "viewed=false" ; "max=25" ; "attachments=true" ) // check for import success here If [$$importUrl = "ERROR"] Show Custom Dialog [EmailLastError] Exit Script End If // Import the email messages from the local XML file // which was created by the EmailReadMessages function Import records [$$importUrl ; Update Matching] // Now disconnect from the IMAP server Set Variable [ $disconnect = EmailDisconnect ] If [$disconnect = "ERROR"] Show Custom Dialog [EmailLastError] Exit Script End If
If you're running on FileMaker server or via IWP/CWP, you'll need to iterate over the messages, since [Import XML] is not a web-safe script step. The general pattern looks like this:
set variable $$importUrl = EmailReadMessages ( "mailbox=INBOX" ; "viewed=false" ; "max=25" ; "attachments=true" // check for import success here Loop Exit Loop If [not EmailGetNextMessage] New Record/Request Set Field[ImportedMessage::date ; EmailReadMessageValue( "dateSent" )] Set Field[ImportedMessage::from ; EmailReadMessageValue( "from" )] Set Field[ImportedMessage::to ; EmailReadMessageValue( "to" )] Set Field[ImportedMessage::subject ; EmailReadMessageValue( "subject" )] Set Field[ImportedMessage::body ; EmailReadMessageValue( "body" )] Set Field[ImportedMessage::messageId ; EmailReadMessageValue( "messageId" )] End Loop
Microsoft Exchange Server
To read mail from a Microsoft Exchange Server, you'll need to enable IMAP access on your exchange server. <a href="http://technet.microsoft.com/en-us/library/bb124489.aspx?ppud=4">This article</a> covers the steps for doing so. You may need to restart your server for this change to take effect. Once IMAP access is enabled, you can connect normally as described above.
Modifying Mail Messages
Version 1.6 of the Email Plugin provided the ability to modify messages on a remote mailbox. To do this, you must read the messages using the EmailReadMessages function as described above, being sure to include the flag
readonly=false
.
Note: setting readonly=false
will cause any fetched messages to be marked as "viewed"! Then iterate to a message using the EmailGetNextMessage function.
Finally, use the EmailMessageSetFlag function to apply flags to a message (such as deleted, flagged, viewed, etc).
Here is an example of how to fetch any unread messages from a mailbox, marking them all as viewed
(by setting readonly=false
).
Additionally, any messages from a certain address are marked as deleted
:
Set Variable [ $result = EmailReadMessages( "viewed=false" ; "readonly=false" ) ] If [$result = "ERROR"] # Handle Error Here... End If Loop Exit Loop If [not EmailGetNextMessage] Set Variable[$result ; EmailMessageSetFlag("viewed") If [EmailReadMessageValue("from") = "deleteme@example.com"] Set Variable[$result ; EmailMessageSetFlag("deleted") End If End Loop
360Works Plugin Setup Guides
See Plugins_101 for Error reporting, installation, registration, and more.
Function Summary
- EmailAttachFile ( data ) — Attach a file at a URL to an email message, from either a URL, container, or file path.
- EmailAttachFileInline ( data ; contentId ) — Add an inline attachment to an HTML message.
- EmailBCCRecipients ( bcc_addresses { ; append } ) — Set the BCC (blank carbon copy) recipients for the current message.
- EmailBodySubstitute ( searchString ; replaceString ) — Perform a substitute operation an the HTML or plain-text portion of the current HTML message.
- EmailCCRecipients ( cc_addresses { ; append } ) — Set the CC (carbon copy) recipients for the current message.
- EmailChooseFile ( { initialPath ; fileType ; title } ) — Shows a file chooser dialog where a user can browse her local hard drive.
- EmailConnect ( host_address_deprecated { ; user_deprecated ; password_deprecated } ) — Use {@link #EmailConnectSMTP} instead.
- EmailConnectAmazon ( accessKey; secretKey ) — Connect to the Amazon Simple Email Service (SES) servers for sending email.
- EmailConnectIMAP ( host ; username ; password { ; ssl=true ; forceTrust=true ; tls=true ; ... } ) — Connect to an incoming IMAP mail server.
- EmailConnectPOP ( host ; username ; password { ; ssl=true ; forceTrust=true ; tls=true ; ... } ) — Connect to an incoming POP mail server.
- EmailConnectSMTP ( host { ; username ; password ; ssl=true ; forceTrust=true ; tls=true ; timeout=10 ; ... } ) — Connect to an outgoing SMTP mail server.
- EmailCreate ( from ; to ; subject ) — Create a new email message, clearing any previous recipients and attachments.
- EmailDisconnect ( ) — Close any open connections to email servers established via the EmailConnect.
- EmailGetMessageCount ( { flag1 ; flag2 ; ... } ) — Returns a count of messages in a particular mailbox, INBOX is used if no mailbox is specified.
- EmailGetNextMessage ( ) — Loads a single message which was fetched in a previous call to the
EmailReadMessages
function. - EmailLastError — Returns detailed information about the last error generated by this plugin.
- EmailLicenseInfo — Retrieve information about the Email plugin licensing and version.
- EmailListMailboxes ( { ; parent ; recursive } ) — Gets a return-separated list of mailboxes in a specific folder on the currently connected inbound mail server (Note: this is only useful for IMAP mailboxes, not POP).
- EmailMessageSetFlag ( flag { ; value } ) — Applies a flag to the current message, as retrieved by the function {@link #EmailGetNextMessage()}.
- EmailMoveCurrentMessage ( folder ) — Moves a message on an IMAP mailbox.
- EmailOutgoingMessageId ( ) — Returns the Message-ID of the last message sent using the Emailer plugin.
- EmailQuickSend ( from ; to ; subject ; body {; attachment } ) — Convenient way to send a single simple message to one or more recipients.
- EmailReadAttachment ( path ) — Read a downloaded attachment into a FileMaker container field.
- EmailReadMessages ( { flag1 ; flag2 ; ... } ) — Reads messages from the currently connected inbound mail server.
- EmailReadMessagesFromFile ( file { ; charset=UTF-8 } ) — This reads messages from an non-directory
MBOX
file or raw message content file (.
- EmailReadMessageValue ( key ) — Retrieves information about the last message which was gotten by the
EmailGetNextMessage
function. - EmailRecipients ( to_addresses { ; append } ) — Set the TO recipients for the current message.
- EmailRegister ( licenseKey ; registeredTo ) — Registers the Email Plugin.
- EmailSend ( { progress=true ; progressLocation=100,200 ; ... } ) — Send the current email, as defined in the {@link #EmailCreate}, {@link #EmailSetSubject}, {@link #EmailSetBody}, and other functions.
- EmailSetBody ( body { ; contentType ; characterSet } ) — Sets a body part of the current message.
- EmailSetBodyFile ( url ; embedResources ) — This is used to load an HTML document as the email body part.
- EmailSetErrorCapture ( errorCapture ) — Toggles error dialogs on or off.
- EmailSetHeader ( header ; value ) — Set a custom header in the message.
- EmailSetSubject ( subject ) — This allows you to customize the subject of the current outgoing email message, as specified in the {@link #EmailCreate} function.
- EmailSuppressErrorDialogs ( trueOrFalse ) — To suppress all error dialogs for this plugin, call
EmailSuppressErrorDialogs(true)
. - EmailVersion — Returns the version number of the Email plugin.
- IM_Disconnect ( { service ; login } ) — Disconnects user from all connected services.
- IM_GetBuddyIcon ( service ; login ; password ; buddy ) — Returns a buddy's icon.
- IM_GetBuddyList ( service ; login ; password ) — Connects to the messaging service (if necessary) and retrieves the user's buddy list.
- IM_GetBuddyStatusMessage ( service ; login ; password ; buddy ) — Returns a buddy's status.
- IM_GetBuddyStatusType ( service ; login ; password ; buddy ) — Returns a buddy's status type as one of the following: "online", "idle", "away", "mobile", or "offline".
- IM_SendMessage ( service ; login ; password ; recipient ; message ) — Connects to the messaging service (if necessary) and sends a plain text message to the recipient recipient.
- IsValidEmail ( email ) — Convenience function for validating an email address.
Function Detail
EmailAttachFile ( data )
Attach a file at a URL to an email message, from either a URL, container, or file path. For example:
EmailAttachFile("http://localhost:8080/SuperContainer/123/RawData");
-or-
EmailAttachFile("file:///path/to/invoice.pdf");
-or-
EmailAttachFile("/Macintosh HD/path/to/invoice.pdf");
-or-
EmailAttachFile(myTable::myContainerField);
You can call this multiple times to attach multiple files to a message.
Note on paths vs urls: This function can also accept a path (/path/to/file) instead of a file URL (file://path/to/file). This is handy for attaching PDFs generated by FileMaker.
If called on a machine running Mac OS X, a file URL is created from a path by prepending the directory /Volumes
to the supplied path, since FileMaker includes the hard drive name in paths.
For example, /MacintoshHD/Users/John Smith/Documents/
is converted to the file URL file:///Volumes/MacintoshHD/Users/John Smith/Documents/
.
Auto-zip of attached directories
If the path points to a directory/folder instead of a file, the email plugin will automatically zip the contents of the folder into a temporary file and send that as the attachment. This allows sending of Mac OS X bundles such as .pages
files, etc.
Parameters:
data
- a container, path to a file, or a URL pointing to a file to attach to the message.
Returns: 1 on success, ERROR on error.
EmailAttachFileInline ( data ; contentId )
Add an inline attachment to an HTML message. If you are sending HTML email with embedded images or other resources, use this function to embed the resource files in the message.
For example:
EmailCreate("to@example.com"; "from@example.com"; "My Newsletter") and
EmailSetBody(
"<html><body><img src=\"cid:headergif123\">" &
"This is an HTML message with embedded images" &
"<img src=\"cid:footergif456\">" &
"</body></html>";
"html"
) and
EmailAttachFileInline( Globals::headerContainer ; "headergif123" ) and
EmailAttachFileInline( Globals::footerContainer ; "footergif456" ) and
EmailSend
Content IDs
When creating your HTML email message, reference inline containers using cid:contentid
, where contentid
is an arbitrary unique string you create for each inline attachment.
Your contentIds should be globally unique for a given image/file resource, as mail clients will use this to cache the contents of the message.
You should only use letters and numbers for your content ids, some mail clients have trouble with other characters.
Parameters:
data
- a path to a file, or a URL pointing to a file to attach to the message (see EmailAttachFile for valid arguments).
contentId
- contentId of the attachment.
See also: EmailAttachFile
Returns: 1 on success, ERROR on error.
EmailBCCRecipients ( bcc_addresses { ; append } )
Set the BCC (blank carbon copy) recipients for the current message.
This can be called multiple times before sending, to build up a list of recipients (set append
to true if doing this).
Parameters:
bcc_addresses
- comma-separated list of addresses
append
- whether to append the new addresses to existing ones, or overwrite them.
Returns: 1 on success, ERROR if one or more addresses are invalid.
EmailBodySubstitute ( searchString ; replaceString )
Perform a substitute operation an the HTML or plain-text portion of the current HTML message. You can call this multiple times on the same message, using the same searchString
each time.
Once a message is sent, the replaced values are reset to their original values.
This is useful if you are using EmailSetBodyFile to load static HTML content as the body part, but want to insert dynamic content in the body. Or, if you are sending many emails and want to merge data into a static body text field.
Parameters:
searchString
- the text to replace
replaceString
- the replacement text
Returns: 1 on success, or "ERROR" on failure.
EmailCCRecipients ( cc_addresses { ; append } )
Set the CC (carbon copy) recipients for the current message.
This can be called multiple times before sending, to build up a list of recipients (set append
to true if doing this).
Parameters:
cc_addresses
- comma-separated list of addresses
append
- whether to append the new addresses to existing ones, or overwrite them.
Returns: 1 on success, ERROR if one or more addresses are invalid.
EmailChooseFile ( { initialPath ; fileType ; title } )
Shows a file chooser dialog where a user can browse her local hard drive. When the user selects a file or directory and clicks "OK" on the file chooser,
this function returns the path to the selected file or directory. If the user hits the cancel button, nothing is returned.
File Type
By supplying a fileType
parameter, you can allow the user to just select files, just select directories, or select both files and directories. The default behavior is to only allow file selection.
Note: specifying a fileType of "directories" or "files + directories" will cause a non-native file dialog to be used on some platforms, as the native dialogs may not support directory selection.
Parameters:
initialPath
- optional path to set the initial dialog selection to. If empty, will default to the user's home directory.
fileType
- whether to allow
"files"
, "directories"
, or both "files + directories"
title
- optional title string to display as the title of the FileChooser dialog
Returns: Path to the selected file, nothing if no file was selected, or "ERROR" if an error occurred.
EmailConnect ( host_address_deprecated { ; user_deprecated ; password_deprecated } )
Use EmailConnectSMTP instead. The username and password are optional, and may not be required for sending mail.
This establishes a connection to the email server. When you are finished getting/sending email, you should call EmailDisconnect to close the connection.
Parameters:
host_address
- the SMTP host address. This parameter may contain a port number using a colon syntax, e.g.
smtp.example.com:2525
user
- The optional SMTP authentication username
password
- The optional SMTP authentication password
EmailConnectAmazon ( accessKey; secretKey )
Connect to the Amazon Simple Email Service (SES) servers for sending email. Communication happens via HTTPS protocol instead of SMTP, this can be especially useful when using the plugin in environments that only allow communication over HTTP/HTTPS.
You can sign up for this service at http://aws.amazon.com/ses/. You will need to follow the Amazon sign-up steps to get your keys and register your email address before you can send emails using this service.
Example: EmailConnectAmazon( "nf298nrc23r"; "208chr29-hrc-29hr1983f")
It's also possible to use Amazon SES via SMTP.
Parameters:
accessKey
-
secretKey
-
Returns: successValue
EmailConnectIMAP ( host ; username ; password { ; ssl=true ; forceTrust=true ; tls=true ; ... } )
Connect to an incoming IMAP mail server. This function (or EmailConnectPOP
) must be called before reading email messages from the server.
This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call EmailDisconnect to close the connection.
Here is an example of connecting to a regular mail server:
Set Variable[$result =
EmailConnectIMAP(
"my_email_host" ;
"username" ;
"password"
)
]
SSL Encryption
Use the optional arguments to enable SSL encryption by passing "ssl=1"
. If you are connecting to GMail, SSL encryption is required.
Here is an example of connecting to google mail (gmail) with SSL encryption, and expunge set to true:
Set Variable[$result =
EmailConnectIMAP(
"imap.gmail.com" ;
"username" ;
"password" ;
"ssl=1" ;
"expunge=true"
)
]
Optional Flags
The following can be passed as additional parameters to the EmailConnectIMAP function:
- ssl
- pass
true
to enable SSL encryption. Some mail services (like gmail) require this.
- expunge
- pass
true
or false
to determine whether flagging a message for deletion permanently removes the message from your mail server. If unspecified, messages are only removed/expunged if the server does not support deleted flags.
Parameters:
host
- the IMAP host address. This parameter may contain a port number using a colon syntax, e.g.
imap.example.com:2525
username
- The authentication username
password
- The authentication password
args
- Additional optional arguments (ssl, forceTrust, tls).
See also: EmailDisconnect
Returns: 1 on successful connection, or "ERROR" if an error occurred (use EMailLastError in this case)
EmailConnectPOP ( host ; username ; password { ; ssl=true ; forceTrust=true ; tls=true ; ... } )
Connect to an incoming POP mail server. This function (or EmailConnectIMAP
) must be called before reading email messages from the server.
This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call EmailDisconnect to close the connection.
Note: We strongly recommend using IMAP instead of POP with Gmail due to possible confusion over Gmail's labels and tags.
Here is an example of connecting to a regular mail server:
Set Variable[$result =
EmailConnectPOP(
"my_email_host" ;
"username" ;
"password"
)
]
SSL Encryption
Use the optional arguments to enable SSL encryption by passing "ssl=1"
. If you are connecting to GMail, SSL encryption is required.
Here is an example of connecting to google mail (gmail) with SSL encryption:
Set Variable[$result =
EmailConnectPOP(
"pop.gmail.com" ;
"username" ;
"password" ;
"ssl=1"
)
]
Parameters:
host
- the POP host address. This parameter may contain a port number using a colon syntax, e.g.
pop.example.com:2525
username
- The authentication username
password
- The authentication password
args
- Additional optional arguments (ssl, forceTrust, tls).
See also: EmailDisconnect
Returns: 1 on successful connection, or "ERROR" if an error occurred (use EMailLastError in this case)
EmailConnectSMTP ( host { ; username ; password ; ssl=true ; forceTrust=true ; tls=true ; timeout=10 ; ... } )
Connect to an outgoing SMTP mail server. This function must be called before sending mail. The username and password are optional, and may not be required for sending mail, depending on your SMTP server's setup.
This establishes a connection to the email server. When you are finished getting/sending email, it is a good idea to call EmailDisconnect to close the connection.
Note: By default, Gmail will set the "from" address to the email address used with EmailConnectSMTP for all outbound messages. If you want to set the "from" address to a different email address, you must
add the desired email address manually in Gmail Settings.
Here is an example of connecting to a regular mail server:
Set Variable[$result =
EmailConnectSMTP(
"my_email_host" ;
"username" ;
"password"
)
]
SSL Encryption
Use the optional arguments to enable SSL encryption by passing "ssl=1"
. If you are connecting to Gmail, SSL encryption is required.
Here is an example of connecting to Gmail with SSL encryption:
Set Variable[$result =
EmailConnectSMTP(
"smtp.gmail.com:465" ;
"username" ;
"password" ;
"ssl=1"
)
]
Parameters:
host
- the SMTP host address. This parameter may contain a port number using a colon syntax, e.g.
smtp.example.com:2525
username
- The optional SMTP authentication username
password
- The optional SMTP authentication password
args
- Additional optional arguments (ssl=true, forceTrust=true, tls=true, timeout=<<seconds>>).
See also: EmailDisconnect
Returns: 1 on successful connection, or "ERROR" if an error occurred (use EmailLastError in this case)
EmailCreate ( from ; to ; subject )
Create a new email message, clearing any previous recipients and attachments.
Parameters:
from
- the FROM address for the new message. Use "Name <you@domain.com>" for displaying the name instead.
to
- the TO address for the new message
subject
- the SUBJECT of the new message
Returns: 1 on success
EmailDisconnect ( )
Close any open connections to email servers established via the EmailConnect... functions.
See also: EmailConnectSMTP
Returns: 1 on success
EmailGetMessageCount ( { flag1 ; flag2 ; ... } )
Returns a count of messages in a particular mailbox, INBOX is used if no mailbox is specified.
Parameters:
flags
- optional flags which control how messages are counted
Returns: number of messages in the mailbox
EmailGetNextMessage ( )
Loads a single message which was fetched in a previous call to the EmailReadMessages
function.
To use this function, first call EmailReadMessages
with the appropriate parameters.
Next, call EmailGetNextMessage
, which returns 1 or 0 depending on whether a message was loaded.
Finally, call EmailReadMessageValue
to get individual properties of the currently loaded message.
See also: EmailReadMessageValue, EmailReadMessages
Returns: 1 if a message is loaded, 0 if there are no more messages, or ERROR if an error occurred.
EmailLastError
Returns detailed information about the last error generated by this plugin. If another plugin function returns the
text "ERROR", call this function to get a user-presentable description of what went wrong.
Returns: Error text, or ""
if there was no error.
EmailLicenseInfo
Retrieve information about the Email plugin licensing and version.
Returns: version, type, registeredTo values.
EmailListMailboxes ( { ; parent ; recursive } )
Gets a return-separated list of mailboxes in a specific folder on the currently connected inbound mail server (Note: this is only useful for IMAP mailboxes, not POP).
Parameters:
parent
- optional mailbox to traverse. If not specified/empty, the root mailbox is used.
recursive
- optional parameter for whether to traverse sub-folders recursively. Default is false.
See also: EmailConnectIMAP, EmailConnectPOP
Returns: a return-separated list of mailboxes. If recursion is enabled, nested mailboxes will be separated by a slash (/
) character.
EmailMessageSetFlag ( flag { ; value } )
Applies a flag to the current message, as retrieved by the function EmailGetNextMessage.
Note that you must call EmailReadMessages with a parameter of readonly=false
to use this function.
The allowed flags are:
- deleted
- replied (IMAP only)
- draft (IMAP only)
- flagged (IMAP only)
- viewed (IMAP only)
- recent (IMAP only)
POP vs IMAP. POP accounts typically do not support persistent flags, so if you flag a message as deleted
in a POP account,
it will be permanently deleted
when you disconnect from the server.
Parameters:
flag
- one of the named flags to set
value
- the optional value to set the flag to. Default is
1
(or true
).
Returns: 1 on successful delete, or "ERROR" if an error occurred (use EMailLastError in this case)
EmailMoveCurrentMessage ( folder )
Moves a message on an IMAP mailbox. This operates either on the current message queued for delivery in FileMaker, or on the most recently fetched message from the IMAP server.
Saving Outgoing Messages
To save a copy of an outgoing message in your "Sent" mailbox, you can do something like the following:
EmailCreate( "my@mydomain.com" ; "bob@example.com" ; "Moving a test message" ) and
EmailSetBody( "Hi Bob! I'm saving a copy of this in my 'Sent' folder" ) and
EmailSend and
EmailMoveCurrentMessage( "Sent" )
The above example assumes that you are already connected both to your IMAP server and your SMTP server.
First we create a message and set the message body.
Next, we deliver the message by calling EmailSend.
Finally, If the message was delivered successfully, we save it to the "Sent" folder on our IMAP mailbox.
Moving Existing Messages
To move existing messages on your IMAP mailbox, call EmailMoveCurrentMessage
after fetching the message with EmailGetNextMessage.
This will copy the message to the destination mailbox, creating the mailbox if it doesn't exist. If the original mailbox has readonly=false
specified, the message is flagged for deletion from the original mailbox.
This can be useful for processing all messages in a certain folder, then moving them to a "processed" folder on the mailserver, for example.
Set Variable [ $result = EmailReadMessages( "readonly=false" ) ]
If [$result = "ERROR"]
# Handle Error Here...
End If
Loop
Exit Loop If [not EmailGetNextMessage]
// DO SOMETHING INTERESTING WITH THE MESSAGE HERE...
Set Variable [ $moveResult = EmailMoveCurrentMessage ("Processed") ]
End Loop
The above script fetches all messages in the INBOX, then loops through them, performing some action on each message, then moving the message to the "Processed" mailbox.
NOTE: the readonly=false
is required for the processed messages to be removed from the mailbox. If not specified, the messages will still remain in the original mailbox.
Parameters:
folder
- the name of the folder to move the message to
Returns: 1 on success, "ERROR" on error (use EmailLastError to get a detailed error message)
EmailOutgoingMessageId ( )
Returns the Message-ID of the last message sent using the Emailer plugin.
Returns: a Message-ID value, or "" if there was no available message.
EmailQuickSend ( from ; to ; subject ; body {; attachment } )
Convenient way to send a single simple message to one or more recipients.
See EmailAttachFile for more information about how to attach a file.
Parameters:
from
- The "from" email address. Use "Name <you@domain.com> for displaying the name instead.
to
- A comma-separated list of "to" email addresses
subject
- The subject of the message
body
- The message body. If the body starts with
<html
it is assumed to be an HTML-formatted message.
attachment
- A container holding an attachment to include with the email, or a URL or path to a file to attach.
Returns: 1 on success, or "ERROR" if something went wrong
EmailReadAttachment ( path )
Read a downloaded attachment into a FileMaker container field. To download attachments, you must pass attachments=true
as a parameter to the EmailReadMessages function.
After importing an email message into FileMaker, pass any attachment paths to this function to get container data for the attachment path.
For example, you might pass the following argument:
EmailReadAttachment(
"/Macintosh HD/private/tmp/4545776.01203682301836.JavaMail.root@pluto.local/text.html"
)
The supplied path should not begin with file:
, image:
, or any other prefix - just the path.
Note that this will actually work for any file, it doesn't need to be an email attachment.
Parameters:
path
- The path as returned in the email import
Returns: container data for the file at path
, or "ERROR" if an error occurred (use EmailLastError in this case)
EmailReadMessages ( { flag1 ; flag2 ; ... } )
Reads messages from the currently connected inbound mail server.
After calling this function, you will typically use the EmailGetNextMessage function to iterate over the messages which were fetched.
As an alternate approach, you can perform an XML import of the fetched message data, using the value returned from this function as the XML file path.
If an error occurs, this function will return "ERROR". Use the EmailLastError function to get more information about the error.
Fetching Unread Messages
The Email plugin supports reading messages from POP and IMAP mailboxes. Typically, you're interested in only fetching new messages from your mailbox. There are several approaches to doing this.
Option 1: Search by UID (IMAP or POP3)
Note: POP3 mail servers are not required to support UIDs. Please check with the server administrator about UID support.
IMAP and POP3 mailboxes assign each message a unique UID. When reading messages from an IMAP or POP3 mailbox, you can get the value for this UID with the following function:
Set Field[ImportedMessage::uid ; EmailReadMessageValue( "uid" ) ]
Once you have the UID of the most recently fetched message, you can pass that in as an argument to subsequent calls to EmailReadMessages, for example:
Go To Record/Request/Page [Last]
Set Variable [ $result = EmailReadMessages (
"uid=" & ImportedMessage::uid
)
]
This fetches only the messages whose UID is greater than the most recently fetched message. This is the preferred way to fetch new messages from a mailbox, as it is very efficient, doesn't modify any messages, and will work even if another email client accesses the mailbox.
Option 2: Search for Unread Messages
You can specify a filter option to only search for unread messages:
Set Variable [ $result = EmailReadMessages (
"viewed=false" ;
"readonly=false"
)
]
After fetching unread messages, you should then set the "viewed" flag to true
for each message, so subsequent reads will skip these messages. This is outlined in the following section "Reading Individual Messages"
Note: searching for unread messages will not work correctly if other email clients are accessing the same mailbox and marking messages as viewed.
Option 3: Skipping messages
This is similar to option 2, except you don't need to modify the messages on the server. Simple count how many messages have been fetched from the mailbox, and pass a skip
parameter to the EmailReadMessages
function whose value is this number.
Note: If messages are deleted from the mailbox, local messages should be deleted as well, so the local count
matches the number of fetched messages on the server.
Reading Individual Messages
After successfully calling EmailReadMessages, you can iterate over the fetched messages using the EmailGetNextMessage function. This pattern typically looks like this:
Loop
Exit Loop If [not EmailGetNextMessage]
New Record/Request
Set Field[ImportedMessage::from ; EmailReadMessageValue( "from" )]
Set Field[ImportedMessage::to ; EmailReadMessageValue( "to" )]
Set Field[ImportedMessage::subject ; EmailReadMessageValue( "subject" )]
Set Field[ImportedMessage::body ; EmailReadMessageValue( "body" )]
Set Field[ImportedMessage::messageId ; EmailReadMessageValue( "messageId" )]
// OPTIONAL: mark this messages as "viewed"
// (You must pass readonly=false during EmailReadMessages to do this)
Set Variable[$result ; EmailMessageSetFlag("viewed")]
End Loop
Importing Messages via XML
To import email data into FileMaker via XML, use the "Import Records" script step, and specify an XML data source, passing the file URL returned from this function.
Use the "messageId" field in the resulting XML as a match field when defining import options.
Note: XML import is not a web-safe script. Use the method described in "Reading Individual Messages" if your script is running in IWP or on the server, or if you need to modify individual messages on the server.
Flags
This function accepts a variety of flags which allow you to fine-tune how the messages are read.
Flags should be entered as key=value
arguments. You can specify any number of flags you wish.
The following is a description of the available flags:
- progress
- Whether to show a cancellable progress bar (default is false).
- progressLocation
- Location of the progress bar, e.g. "
100,200
". Default is centered on-screen.
- mailbox
- The name of the mailbox to read messages from (Note: this is only useful for IMAP accounts). The default behavior is to read messages from the
INBOX
.
- attachments
- Boolean flag indicating whether to download attachment data. The default value is
true
, which enables attachment downloading. Setting this to false
will disable downloading attachments, which can be significantly faster.
If attachment downloading is disabled, you can still retrieve a list of the attachments in a message using the EmailReadMessageValue ( "attachments" )
function. You can the re-read the message at a later time to download the attachments (see the EmailClient.fp7 example file).
- skip
- Skip this many records before reading results. This is useful for fetching messages in batches, if you know that messages will not be deleted from a mailbox during reading.
- max
- Do not return more than this many records in the import
- uid
- (Note: not all POP3 mail servers support UIDs) only fetch messages whose
uid
is newer than the one passed in. This is very useful for only fetching new messages from IMAP mailboxes. When looping through new messages, call EmailReadMessageValue("uid")
on the last message and save this to a field in your database. Then when fetching new messages, pass this uid
in as a filter argument. Only newer messages will be returned. Note: if you specify this option and the mailbox is an IMAP mailbox, all other search filters (skip, max, to, from, date, etc) will be ignored.
- dateFrom
- Filter messages to only return messages sent on or after a certain date (some IMAP mailboxes require an additional flag of "deleted=any" for EmailReadMessages to read emails using this parameter).
- dateTo
- Filter messages to only return messages sent on or before a certain date (some IMAP mailboxes require an additional flag of "deleted=any" for EmailReadMessages to read emails using this parameter).
- from
- Filter messages by
from
address
- to
- Filter messages by
to
address
- subject
- Filter messages by
subject
- messageId
- Filter messages by
messageId
- body
- Filter messages by
body
- viewed
- Filter messages by their read/unread status. Pass
true
to return only previously viewed messages, false
to return only unread messages.
- flagged
- Filter messages by their flagged status. Pass
true
to return only flagged messages, false
to return only non-flagged messages.
- deleted
- Filter messages by their deleted status. Pass
true
to return only deleted messages, false
to return only non-deleted messages The default is false
, meaning deleted message will be excluded.
- readonly
- Whether to open the mailbox folder as readonly or read-write. The default is
true
(read-only).
If you plan on deleting, moving, or flagging any messages, use false
in this parameter.
Note: setting readonly=false
will cause any fetched messages to be marked as "viewed"!
For example, you might use the following to fetch the first 25 unread messages from your inbox:
EmailReadMessages(
"mailbox=INBOX" ;
"attachments=false" ;
"max=25" ;
"attachments=false" ;
"viewed=false"
)
Parameters:
flags
- optional flags which control how messages are read.
Returns: The URL of the local XML file. This URL can be passed to FileMaker as the XML data source location.
EmailReadMessagesFromFile ( file { ; charset=UTF-8 } )
This reads messages from an non-directory MBOX
file or raw message content file (.eml
), and stores the parsed messages in an FMPXML file, suitable for import into FileMaker.
In addition, you can use the EmailGetNextMessage function after calling this to loop over the messages and programatically read individual values using the EmailReadMessageValue.
Flags
The following is a description of the available flags:
- charset
- Character set of the file. Leave this blank to use the default for your locale.
Note: this will disconnect from your current mail server if there is an active connection.
Parameters:
file
- path to an MBOX file
Returns: URL to an FMPXML file containing the parsed messages in the file
EmailReadMessageValue ( key )
Retrieves information about the last message which was gotten by the EmailGetNextMessage
function.
If there are multiple values for a key, each value will be on a separate line.
The parameter must be one of the following values (case-insensitive):
- count (The total number of messages fetched from the server)
- from (The FROM address)
- to (The TO addresses, comma-separated)
- cc (The CC addresses, comma-separated)
- bcc (The BCC addresses, comma-separated)
- replyTo (The reply-to address)
- subject
- messageNumber (the integer index of the message on the server. 1 is the first message in the mailbox)
- sent (The timestamp the message was sent)
- messageID (The unique message ID for the email message)
- attachments (A return-separated list of attachments for the message. Each line is either the attachment file path, or the name, depending on the value of the
attachments
parameter in EmailReadMessages
). Note: inlined attachments are excluded from this list. Use attachmentsAll
to get all attachments including inlined ones.
- text (The plain-text message content, if available)
- html (The HTML body part, if one is available. If attachments are set to download, inline attachment images will be converted to base64 data URLs automatically. If you don't want this behavior, use
htmlRaw
instead, or set attachments=false
when fetching messages.)
- htmlRaw (The HTML body part unaltered, if one is available.)
- uid (returns the IMAP or POP3 folder uid Note: not all POP3 mail servers support UIDs)
- viewed (1 or empty to indicate whether the message has been read (1) or is unread)
- flagged (1 or empty to indicate whether the message is flagged)
- replied (1 or empty)
- deleted (1 or empty)
- header:HEADER_NAME (any header value, replace HEADER_NAME with the name of the header to retrieve)
- headers (a return-separated list of all message headers)
- raw: (the raw source of the entire message)
Reading Message Headers
You can retrieve any message header by using this function. For example, to get information about the mail application which sent the message, you can use EmailReadMessageValue("header:X-Mailer")
.
If a header has multiple values, they will be returned as a return-separated list.
Parameters:
key
- The key to retrieve, must be one of the above listed keys.
See also: EmailGetNextMessage, EmailReadMessages
Returns: The value for that key in the current message.
EmailRecipients ( to_addresses { ; append } )
Set the TO recipients for the current message.
This can be called multiple times before sending, to build up a list of recipients (set append
to true if doing this).
Parameters:
to_addresses
- comma-separated list of addresses
append
- whether to append the new addresses to existing ones, or overwrite them.
Returns: 1 on success, ERROR if one or more addresses are invalid.
EmailRegister ( licenseKey ; registeredTo )
Registers the Email Plugin.
Parameters:
licenseKey
- a valid license key string.
registeredTo
- the company name for the license key used.
Returns: 1 on success, or "ERROR" on failure.
EmailSend ( { progress=true ; progressLocation=100,200 ; ... } )
Send the current email, as defined in the EmailCreate, EmailSetSubject, EmailSetBody, and other functions.
Optional Parameters
- progress
- Whether to show a progress bar. Default =
true
.
- progressLocation
- Location of the progress bar, e.g. "
100,200
". Default is centered on-screen.
Parameters:
options
- optional parameters
Returns: 1 on success, ERROR if something went wrong with sending the message
EmailSetBody ( body { ; contentType ; characterSet } )
Sets a body part of the current message. Common content types are "plain" and "html". You can call this multiple times for a single message to provide an HTML body part with a plaintext alternative part.
To send formatted FileMaker text as HTML email, use the FileMaker GetAsCSS
function to generate the HTML, e.g.
EmailCreate( "from@example.com", "to@example.com", "A multipart message" ) and
EmailSetBody( Email::body ; "plain" ) // this is used for mail clients which don't display HTML
and
EmailSetBody( GetAsCSS( Email::body ); "html" ) // HTML version with formatting
and
EmailSend
Parameters:
body
- text to be displayed in the message
contentType
- type of formatting used in the body, e.g. "plain", "html", "rtf".
characterSet
- optional character set
Returns: 1 on success
EmailSetBodyFile ( url ; embedResources )
This is used to load an HTML document as the email body part. You can use the EmailBodySubstitute function to perform substitute/replace operations on the body content loaded by this function.
Embedding Resources
If you pass true
as the embedResources
parameter, any images or stylesheets referenced in the email message will be included as inline attachments in the email message.
This means that users will not need to load the resources from the central server, but it can increase the email message size considerably.
If you pass false
as the embedResources
parameter, any referenced image URLs will be rewritten as absolute URLs.
MHTML Files
This function also accepts .mhtml html archive files, which have the advantage of already having all images embedded in the file. The embedResources
parameter is always effectively true
for .mhtml files.
Parameters:
url
- URL to the HTML document.
embedResources
- whether resources should be embedded in the HTML email or rewritten as absolute URLs.
Returns: 1 on success, "ERROR" on failure (use the EmailLastError function to get more information)
EmailSetErrorCapture ( errorCapture )
Toggles error dialogs on or off. When something unexpected happens, the plug-in will pop up a dialog displaying the error message. This makes it easy to see what went wrong. However, in some cases, you (the developer) may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call EmailSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user.
Parameters:
errorCapture
- set to true to suppress the default popups.
EmailSetHeader ( header ; value )
Set a custom header in the message. This is not needed for the majority of cases. A list of header fields can be found
here. These should be modified by advanced users only.
For Example (below is a short list of the more commonly used headers):
EmailSetHeader( "reply-to" ; "reply@example.com" )
EmailSetHeader( "bcc" ; "blind@example.com" )
EmailSetHeader( "subject" ; "List of Example Headers" )
Parameters:
header
- the header name
value
- the header value
Returns: 1 on success, or ERROR on failure
EmailSetSubject ( subject )
This allows you to customize the subject of the current outgoing email message, as specified in the EmailCreate function.
This can be useful if you are sending the same message to multiple recipients, with a custom subject for each recipient.
Parameters:
subject
- the email message subject
Returns: 1 on success
EmailSuppressErrorDialogs ( trueOrFalse )
To suppress all error dialogs for this plugin, call EmailSuppressErrorDialogs(true)
.
Parameters:
trueOrFalse
- 1 or 0
Returns: 1 on success, "ERROR" if an invalid parameter is passed
EmailVersion
Returns the version number of the Email plugin.
Returns: a text version number
IM_Disconnect ( { service ; login } )
Disconnects user from all connected services. If login information is passed it, only that specific account is
disconnected. If only partial login info is passed it, all accounts are disconnected.
Parameters:
service
- optional parameter to disconnect from only the specific messaging service; currently only "AIM" is
supported
login
- optional parameter to disconnect only the specific login/account name for the service
Returns: @return 1 on success, ERROR on failure
IM_GetBuddyIcon ( service ; login ; password ; buddy )
Returns a buddy's icon. If the buddy doesn't have an icon set, a default one will be returned corresponding to the
buddy's messaging service. Note that if a connection is made shortly before the function is called, the returned
icon be the default even if the buddy does have one set. A subsequent call will return the appropriate icon after it
has been retrieved and cached by the plugin.
Parameters:
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
buddy
- the buddy whose icon to get
Returns: the buddy's icon as a container
IM_GetBuddyList ( service ; login ; password )
Connects to the messaging service (if necessary) and retrieves the user's buddy list. The list is return-separated
and can easily be parsed using FileMaker's built-in GetValue()
function.
Parameters:
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
Returns: return-separated list of buddies
IM_GetBuddyStatusMessage ( service ; login ; password ; buddy )
Returns a buddy's status. If the buddy doesn't have a status set, an empty string is returned instead. Note that if
a connection is made shortly before the function is called, the returned status may still be blank even if the buddy
does have one set. A subsequent call will return the status after it has been retrieved and cached by the plugin.
Parameters:
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
buddy
- the buddy whose status to get
Returns: the buddy's current status; if no status is set, an empty string is returned
IM_GetBuddyStatusType ( service ; login ; password ; buddy )
Returns a buddy's status type as one of the following: "online", "idle", "away", "mobile", or "offline". If the
buddy doesn't have a status set, an empty string is returned instead. Note that if a connection is made shortly
before the function is called, the returned status type may still be blank even if the buddy does have one set. A
subsequent call will return the status type after it has been retrieved and cached by the plugin.
Parameters:
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
buddy
- the buddy whose status type to get
Returns: the buddy's current status type
IM_SendMessage ( service ; login ; password ; recipient ; message )
Connects to the messaging service (if necessary) and sends a plain text message to the recipient recipient. This
function can also send SMS messages if used with AIM as the service. The recipient recipient in this case would be a
phone number, prefixed with "+1". For example, to send a SMS to 555-123-4567, enter "+15551234567" as the recipient.
Parameters:
service
- the messaging service to use; currently only "AIM" is supported
login
- login/account name for the service
password
- the password for service account
recipient
- the recipient of the message; can be phone number if sending SMS through AIM
message
- the message to send
Returns: 1 on success, ERROR on failure
IsValidEmail ( email )
Convenience function for validating an email address.
This checks for conformance to RFC 822, but does not actually check that an active email account exists at this address.
Parameters:
email
- one or more email addresses to validate (comma-separated).
Returns: 1 if the all emails are valid, 0 if any address is invalid, or "" if email
is empty.