360Works CloudMail 4.01 User Guide

Installation

Requirements

FileMaker version 12 or higher.

When 360Plugins are intialized for the first time, they will automatically download all required support files

Install Steps for FileMaker Pro

Drag the plugin from the MAC or WIN folder into your FileMaker extensions, and restart FileMaker.

If the plugin does not load correctly, please send an email to support@360works.com

WebDirect Install (FMS 13+)

Install plug-ins for use with WebDirect by dragging the appropriate plugin to FileMaker Server/Web Publishing/publishing-engine/cwpc/Plugins

Install steps for Instant Web Publishing

You do not need to do this step unless you plan on using the plugin with Instant Web Publishing with FileMaker Server Advanced. You will need an Enterprise license to use this feature.

For installing into the Web Publishing Engine with FileMaker Server or FileMaker Server Advanced, drag the plugin from the MAC or WIN(.fmx) folder into the FileMaker Server/Web Publishing/publishing-engine/wpc/Plugins folder. If there is no Plugins folder inside the wpc folder, then create it manually. Restart FileMaker Web Publishing, and now the plugins should be ready to go.

The easiest way to test whether the plugin is working is to call the version function of the plugin, and display that on an IWP layout. If it shows "?", then the plugin is not working. If it shows a number, then the plugin has been installed successfully.

Install steps for Custom Web Publishing

If you are using FileMaker Server 12.0v1, you can follow the same procedure as detailed above for custom web publishing. However, in FileMaker Server 12.0v2 and later, custom web publishing now runs as a 64-bit application and requires the 64-bit version of the plugin You will need an Enterprise license to use this feature.

For Mac, the single plug-in file in the MAC directory contains both 32-bit and 64-bit versions. For Windows, look for the plug-in that has the extension .fmx64 and use it in exclusively in custom web publishing.

To install 64-bit plug-ins, install either the .fmx64 or the .fmplugin to the following directory:

FileMaker Server / Web Publishing / publishing-engine / cwpc / Plugins

If it does not exist, create the Plugin folder manually. Restart FileMaker Web Publishing, and then you can then test a script that contains a plug-in and see if it returns the correct values.

Install steps for server scheduled scripts

You do not need to do this step unless you plan on using the plugin with scheduled script triggering. You will need an Enterprise license to use this feature.

  1. Drag the plugin from the MAC (.fmplugin file) or WIN (.fmx64 file) folder into the FileMaker Server extensions folder. On Mac OS X, this is located at /Library/FileMaker Server/Database Server/Extensions folder. On Windows, this is at C:\Program Files\FileMaker\FileMaker Server\Database Server\Extensions.
  2. Restart the FileMaker Script Engine by opening Terminal (Mac) or CMD (Windows) and type the command: fmsadmin restart fmse -y . Note: On Windows you may need to change directories to where the fmsadmin utility is located in order to run this command. By default this is located at "C:\Program Files\FileMaker\FileMaker Server\Database Server" This step is not necessary if using Powershell
  3. Go to Configuration -> Database Server->Server Plug-ins and check the box that says 'Enable FileMaker Server to use plug-ins'(if it is not already checked), and then check the 'enabled' box for this plugin. Click the 'save' button and wait a few seconds to make sure that the 'enabled' check box stays checked. If it does not, then there was an error loading the plugin and you should contact us for help troubleshooting. You should now be able to write schedules that trigger scripts which use the plugin.

Auto Update

360Works has created an AutoUpdate helper database which makes setting up AutoUpdate much easier. This file includes pre-configured plugin files which you can place on your server, and an AutoUpdate script for each of our plugins which you can paste into your own solution.

You can get the AutoUpdate360Works file here Follow the instructions included in the file to either host your own Auto Update server or pull the files from ours.

Uninstalling the plugin

Uninstall the plugin by quitting FileMaker Pro or stopping FileMaker Server and removing the plugin file from your Extensions directory.

Demo mode and Registering the plugin

Plugins will run in demo mode until they are registered. While running in Demo mode, the product will run for 2 hours every time you launch FileMaker / FileMaker Server / FileMaker Web Publishing Engine. The 2 hour time limit will reset every time you relaunch FileMaker. There is no expiration date when Demo mode stops working. There are no feature differences between the Demo version and the licensed version.

Once you have purchased the plugin, you can register it with the license key. Once a valid license key is entered, the product will run for as long as FileMaker is running. After FileMaker starts up with the plugin installed, open FileMaker preferences, click on the Plug-ins tab, select the plugin from the list, and click the Configure button. Enter your license key and company name in this dialog. You will only need to do this once on a given machine. Alternately, you can use the registration function to register the plugin during a startup script.

Note: If you are running the plugin with FileMaker Server / FileMaker Web Publishing Engine, you must use the registration function to register the plugin, since there is no preferences dialog on FileMaker Server to enter the license key and company name. You will need to call the register function at the beginning of any script that is going to call plugin functions. This will ensure that you do not get demo mode errors.

Product Wiki

This is the main documentation for the plugin. However, we also maintain a documentation Wiki that contains additional information for a lot of our products. You can find that page here

Feedback

We love to hear your suggestions for improving our products! If you are experiencing problems with this plugin, or have a feature request, or are happy with it, we'd appreciate hearing about it. Send us a message on our website, or email us!

Error Handling/Reporting

When calling plugin functions as script steps, you will handle errors in the same manner you would any other FileMaker script step. Please see the FileMaker documentation for how to handle errors appropriately. Generally, if there is an error, our plugins will return an error code of 1552 when Get(LastError) is called. However, some plugin functions will return different error codes. If a function can return an error code other than a 1552, it will be documented with the description of the function below. In addition to the error code, you can also get the description of the error by calling Get(LastExternalErrorDetail)

You can also call our functions in a calculation dialog. In this case, error handling is done differently. If you decide to call plugin functions in a calculation dialog and you want to capture errors, see this page page for instruction on how to do so

Examples

360Works CloudMail is a plug-in for sending outbound e-mail messages and monitoring e-mail interactions using Amazon Web Services.

This documentation lists the plug-in API reference. For a guide to getting started with CloudMail, go to the CloudMail documentation wiki.

Function Summary

Function Detail

CMAddRecipient ( recipient )

Call this function once for each e-mail recipient before calling the CMQueueMessage function. This list will be cleared out after CMQueueMessage runs.

Parameters:
recipient - emaill address being added to recipient list

CMAddToBlacklist ( address; date; campaignName )

Use this function to manually add e-mail address to your blacklist / unsubscribe list. Anybody added to the blacklist will never receive e-mails from CloudMail, even if they are added as a recipient. CloudMail will automatically add recipients to the blacklist if they use the unsubscribe link in an e-mail that they receive, so you only need to call this function if somebody requests to be unsubscribed without using the automatic unsubscribe link. Please note that this is different from the suppression list that is maintained by AWS. Email addresses that cause repeated hard bounces will be automatically added to this list. These will still be reported as part of the "bounce" metric.
 CMAddToBlackList[Address: "Someone@360Works.com"; Date: "12-31-1999"; Campaign Name: "CloudMailTest"]

Parameters:
address - The email address being added to the black list
date - The date the email is added to the blacklist. Must be in MM-DD-YYYY format
campaignName - name of the campaign

CMClearRecipients

This clears all previously added recipients. This happens automatically when CMQueueMessage is called, but it's a good idea to always call this function before starting a new batch of recipients, just to make sure that you're not appending to some previous unsent email list.

Returns: 1 on success, 'ERROR' on failure.

CMDeleteResource ( url )

This deletes an item that was previously uploaded to Amazon S3 using the CMUploadResource function.

Parameters:
resourceUrl - the URL to the resource to delete

CMGetResultInfo ( columnName )

Call this function once for each piece of data that you want to retrieve about the activity record. The columnName parameter depends on what type of activity this is. Here is a list of valid column names for each type of activity:
Please see CMNextResult for example usage

Parameters:
columnName - name of data that you want to retrieve for a certain activity

CMIsProductionMode

This function will return '0' if the SES account is in sandbox mode, or '1' if it is in production mode. An account that is in sandbox mode has low sending limits and can only be used to send to pre-verified e-mail addresses. See thispage for instructions on how to move your account into production mode.
   If[ not CMIsProductionMode]
   # show a custom dialog to tell the user the account is in sandbox mode
   End If

CMLastError

Returns the last plugin related error which occurred. This should be called any time that a plugin function returns "ERROR" to get a user-readable description of the error. If you are calling plugin functions as script steps then you should not use this function. Instead capture errors the same way you would with native script steps. See the Error Handling/Reporting section above for more explanation

Returns: Error text, or

CMNextResult ( type )

Use this function to retrieve e-mail related activity. Call this function with the type of activity you're interested in, and it will either return a '0' indicating that there is no activity of that type, or a '1' indicating that there is activity of that type. If a '1' is returned, then use the CMGetResultInfo function to retrieve the details for that activity, and then continue calling this function until it returns a '0', indicating that there are no more activity records of this type at this time. Email activity can be retrieved up to 14 days after the activity occurs, and after that, it will be lost.
 Loop
   Exit Loop If [not CMNextResult("delivery")]
   Set Field[Deliveries::Campaign name; CMGetResultInfo("campaign")]
   Set Field(Deliveries::Email address("destination")]
   Set Field(Deliveries::Source address("source")]
   Set Field(Deliveries::TimeStamp("timestamp")]
   Set Field(Deliveries::MessageID("messageId")]
   Set Field(Deliveries::ProcessingTime("processingTimeMillis")]
   Set Field(Deliveries::SmtpResponse("smtpResponse")]
   Set Field(Deliveries::ReportingMTA("reportingMTA")]
 End Loop

Parameters:
type - The type of activity to retrieve. This can be 'unsubscribe', 'view', 'click', 'delivery', 'complaint', or 'bounce'

CMQueueMessage ( htmlMessage; plainTextMessage; subject; fromAddress; campaignName {; options...} )

This function will send an e-mail message to each recipient added using the CMAddRecipient function. Insert the word [UNSUBSCRIBE] in the place where you want CloudMail to insert an unsubscribe URL.
 CMQueueMessage[HTML Message: myTable::HTML;
                Plaint Text Message: myTable::PlainText;
                Subject:"CloudMail is so awesome!";
                From Address: "someone@360Works.com";
                Campaign Name: "CloudMail Example Campaign"]

If you would like for the from address to show as "Name" then pass in that information in that format for the "fromAddress" parameter
 CMQueueMessage[HTML Message: myTable::HTML;
                Plaint Text Message: myTable::PlainText;
                Subject:"CloudMail is so awesome!";
                From Address: "John Smith";
                Campaign Name: "CloudMail Example Campaign"]

You can specify options in the form "key=value" to access advanced configuration options. Currently, the only supported option is "dnsName=yourserver.yourdomain.com", which will cause the specified DNS name to be used for all clickable links in the e-mail. 


Set Variable[$send;Value: CMQueueMessage(HTML Message: myTable::HTML;
                                         Plaint Text Message: myTable::PlainText;
                                         Subject:"CloudMail is so awesome!";
                                         From Address: "someone@360Works.com";
                                         Campaign Name: "CloudMail Example Campaign";
                                         "dnsName=yourserver.yourdomain.com")]

Parameters:
htmlMessage - The HTML version of your message should be specified in this parameter. You may leave this empty to send a plain text only message, but CloudMail will not be able to tell whether an e-mail was viewed.
plainTextMessage - The plain text version of your message should be specified in this parameter. Some e-mail clients (very few) which do not support HTML messages will display the plain text version instead.
subject - The subject of your message.
fromAddress - The validated e-mail address to send from. You can validate e-mails using the SES section of the AWS Web Console. If you send an e-mail using an unvalidated from address, CloudMail will cancel the message and automatically send a validation e-mail to your from address.
campaignName - You can specify any name or ID that you want here. This name or ID will be stamped on all activity results.
options - See documentation above for more info about this parameter.
Returns: '1' on success, or 'ERROR' in case of an error.

CMRegister ( licenseKey; registeredTo )

Registers the plugin with the licenseKey provided.

Parameters:
licenseKey - The encrypted license key.
registeredTo - the company name for the license key used.
Returns: 1 on success, or

CMRemoveFromBlackList ( emailAddress )

This removes email addresses from the blacklist so that CloudMail will resume sending e-mails to them in the future.

Parameters:
emailAddress - address that you want to remove from the CloudMail blacklist

CMReportProblem ( emailAddress ; problemDescription )

Send a problem report to 360Works.

Parameters:
emailAddress - The user's email address to allow for support contact
problemDescription - A description of the current issue
Returns: Always returns 1

CMSetAmazonCredentials ( accessKey; secretKey )

Call this function before you call any other e-mail sending-related functions. This will validate that your AWS credentials are correct, and will then start an EC2 t4g.micro instance running (if it is not already running).
 CMSetAmazonCredentials[Access Key: "AccessKeyHere"; Secret Key:"Secret Key Here"]

Parameters:
accessKey - Acccess Key for IAM user
secretKey - Secret Key for IAM user
Returns: A status message showing the IP address of the CloudMail server at EC2.

CMSetErrorCapture ( isErrorCaptureEnabled )

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 may prefer to show your own message to the user, or possibly not show a message at all. In that case, you can call CMSetErrorCapture with a parameter of true. That will suppress the error dialog from appearing to the user. This is a boolean value so make sure you do not put the parameter in "". NOTE:This will only suppress error dialogs when plugin functions are called as part of a calculation. If you are calling plugin functions as script steps ( available in FM 16+) then you will need to use the native FileMaker function Set Error Capture On/Off 
  Set Variable[$errCap; Value: EmailSetErrorCapture(True)]

Parameters:
errorCapture - set to true to suppress the default popups.

CMSetUnsubscribeTemplates ( unsubscribeConfirmTemplate; unsubscribeHtmlTemplate )

This function is not implemented yet, but will added in a future update to allow you to use your own custom HTML template for the unsubscribe page.

Parameters:

CMUploadResource ( resourcePathOrContainer; uploadName )

This function allows you to upload resources such as graphics, PDF files, or other file types that can then be hyperlinked to your e-mail message. Be aware that anybody can download any resource if they know the name of the file, so if you are using this for confidential information, include random characters as part of the uploadName, so that it cannot be guessed. This will overwrite an existing resource if it has the same uploadName. You can include slashes in the uploadName to create a directory structure.
 CMUploadResource[Select;Resource Path or Container:Resources::Attachments;UploadName: VeryUniqueName.txt]

Parameters:
resource - file to be uploaded, can be file path or container field reference
Returns: URL to resource

CMVersion

Returns the plug-in version number. You can check to see whether the plug-in is installed or not by checking to see if this function returns a '?' (which means it is not installed).