EmailPlugin

The email plugin page is here: http://360works.com/email-plugin/
Plugin documentation page: http://static.360works.com/plugins/EMAILPLUG/documentation.html

SMS/Text Message Sending

The Email plugin leverages Amazon AWS / SNS to send SMS messages world wide. To do so, use the function EmailSMSSend. Please note that 2-way communication is currently not supported

Requirements

Origination Number

An origination number is a numeric string that identifies an SMS message sender's phone number. When you send an SMS message using an origination number, the recipient's device shows the origination number as the sender's phone number. You can specify different origination numbers by use case. You will need to have an origination number associated with your AWS account in order to use the SMS functionality of the Email plugin. There are 3 types of origination numbers that can be used: short codes, 10DLC, and toll-free (there are also sender-IDs if you are in a country that supports and/or requires them). For most use cases , a 10-DLC or Toll Free number is probably the best choice. Short codes are comparatively more expensive (in the US a $650 set up fee and $995 per month for each short code, cost varies by country) and it can take several weeks for short codes to become active on all carrier networks. There are stipulations and processes in regards to 10DLC and Toll Free numbers as well. To make the best decision on which origination number type is best for your use case you can find information about them and how to provision them here:
Short codes
10DLC
Toll-free

NOTE: While P2P long codes associated with your account may work, effective June 1, 2021, US telecom providers no longer support using person-to-person (P2P) long codes for application-to-person (A2P) communications to US destinations.

Production Mode

By default the SNS module's SMS functionality will be in SMS sandbox. SMS sandbox has the following restrictions:

-You can send SMS messages only to verified destination phone numbers (up to 10 verified destination phone numbers).

-You can delete destination phone numbers only after 24 or more hours have passed since verification or the last verification attempt.

When your account is moved out of the sandbox, these restrictions are removed, and you can send SMS messages to any recipient. While you can still use the SMS functionality of the Email plugin while in sandbox, we recommend that you move into production mode. Documentation for how to do so can be found here. Please note that moving into production mode is done on a per region basis. Make sure that you set the correct region prior to submitting the support request.

Access Keys

The SMS functionality of the plugin requires that you have an AWS account and have generated an access key and secret key. Directions for creating these keys can be found here. The IAM user associated with these keys will specifically need the Simple Notification Service (SNS) permissions CreateTopic, Subscribe, and Publish. It is best practice to create a dedicated user with these permissions only and then use the key set for this user in the EmailSMSSend function

Phone Number Formatting

Recipient numbers need to have the phone number's country code in front of it. For example the country code for the United States is +1 so any number that originates in the US needs to have "1" in front of it like so: 17702349293. The plugin will strip out any other characters besides 0-9 so phone numbers could also be put in the format +1(770)234-9293. If you want to send to multiple numbers, separate them with commas like so "17702349293,16781234567,...."

Example

Your function call should look something like this:

EmailSMSSend("AccessKeyHere";"SecretKeyHere";"17702349293";"Your Message Here"]

Some carriers may break long messages into separate, shorter messages.

Opting Out

AWS also has a mechanism for recipients to opt out of receiving messages from you. By replying "stop" to the message sent, AWS will put their number on the opt-out list and they will no longer receive any messages from you even if they are sent. This list can be managed in your AWS account in the SNS section at Text messaging (SMS)->View opted-out phone numbers . This will show a list of numbers that have opted out from receiving SMS messages. If a recipient decides to opt back in, you can select their number and click "opt in" so they can receive messages from you again. This functionality does not currently support 2-way SMS other than when recipients opt out.

Pricing

Pricing for messages will vary. The first 100 messages sent to US numbers are free. Messages after 100 sent and any non-US numbers incur a per message charge that can be found here.

Sender ID

In the AWS SNS console you can add up to 11 character alphanumeric sender ID that will appear in your messages. However, support for sender IDs varies by country and/or region. For example, messages delivered to U.S. phone numbers will not display the sender ID. For the countries and regions that support sender IDs, see Supported Regions and Countries.

Promotional vs Transactional messages

You can set a default message type in the SMS section of the SNS module. These are defined as:
Promotional (default) – Non-critical messages (for example, marketing). Amazon SNS optimizes message delivery to incur the lowest cost.

Transactional – Critical messages that support customer transactions, such as one-time passcodes for multi-factor authentication.

Pick the message type that best matches your use case

Sending with Amazon Web Services Simple Email Service

The Email plugin is capable of connecting to Amazon Web Services Simple Email Service by using the function EmailConnectAmazon. Sending emails with AWS SES is a great way to send emails. Here are a few reason why:

• Less coordination with IT - There is no SMTP server required so there is no need to contact your IT department to open sending ports in a firewall or other IT related tasks normally associated with setting up and sending with an SMTP server. SES communicates over HTTPS and uses the standard port 443. Also, you do not need to know the requirements for connecting (username, password, ssl/tls requirements, host name and required ports, etc.)
• High Deliverability - Emails sent using SES are sent from AWS IP addresses that maintain good reputation among mailbox providers which means it is less likely your emails will be marked as spam.
• High sending limits - Most email providers will impose pretty low sending limits on the amount of emails you can send in a day and how fast you can send them. AWS allows for you to request sending limits that will fit your needs.
• Low cost, only pay what you use - there are no upfront costs and no minimum commitments. See this page for pricing information.

Requirements

• Access Keys and Secret Keys - These are the required parameters for the EmailConnectAmazon function. These keys are generated per user in your AWS account. The user that the keys are generated for also needs to have the proper permissions to send with SES. This video will give simple instructions on how to generate your access key and secret key and the proper permissions needed.
• Email Address verification - AWS SES will allow you to send from any email address once you verify that you own it. Verification is done via the SES console. Here is a short video showing the verification process.
• Removal from Sandbox mode- New AWS accounts are put into a sandbox. This means that AWS limits what email address you can send to as well as limits the amount of and how fast emails are sent. When in sandbox mode, you can only send to/from addresses that have been verified with your account. In order to get into production mode, you must submit an SES sending limit increase. See this video on how to submit this request. Once AWS has reviewed your request, they will contact you typically within one business day but in some cases might request additional information. Once your sending limits have been approved, you will still need to verify "from" addresses but you will be able to send to any email address/domain.

Example

EmailConnectAmazon("accessKeyHere";"secretKeyHere")
EmailCreate(Email::from;Email::To;Email::Subject)
EmailSetBody(Email::body;"html")
EmailAttachFile(Email::Attachment) //AWS limits message size to 10MB
EmailSend
EmailDisconnect

Optionally you can use the EmailQuickSend function as well

EmailConnectAmazon("accessKeyHere";"secretKeyHere")
EmailQuickSend(Email::from ; Email::to ; Email::subject ; Email::body ; Email::attachment)
EmailSend
EmailDisconnect

Working with Gmail

Pre-requisite: Sending email programatically with Google requires OAuth tokens. Fetching OAuth tokens requires a Google Developer Account. See how to create a Google Developer Account, and get the required client_id and client_secret needed to fetch OAuth tokens here:

Google - Set up OAuth Consent Screen

Note: The client_id and client_secret are required to use the Gmail functions in the Email Plugin.

OAuth Workflow integration adds a lot of security, but also adds complexity to you Email plugin workflows. Here are some examples of how you can utilize these new functions to get through the OAuth workflow so you can connect and send emails.

To better understand how the OAuth workflow works, let's walk through the most manual and straightforward OAuth workflow:

Google OAuth Workflow: Manual Example

• Get the login url: Use the EmailGoogleGetLoginUrl function to get the Google login url: EmailGoogleGetLoginUrl

• Copy that big url, and paste it in your browser. This will take you to the Google login page:

• Log in to your Google account, the one you will want to send email from (or receive email). After logging in, you will likely see a warning about this app not being verified. This is expected, and you should click "Continue" to proceed with the authentication.

• Follow the prompts to allow this app to have access to your Google account.

• If the login is successful, you should see the success page:

• Behind the scenes, Google has given 360Works a token that you need. Fetch the token now with the function EmailGoogleConnectIMAP:

• Now, you may be wondering: Do I have to log in every time? No. The token you got back is good for 200 days. Store the token, and re-use it in future connection statements without having to log in first:

• You may notice that the token is returned every time you call EmailGoogleConnectIMAP or EmailGoogleConnectSMTP. It is recommended to store the token that is retrieved every time you log in.

Google OAuth Worflow: Automated Example

• Now for a more example of how you would see this workflow in a real FileMaker database, check out the demo file included with the 360Works Email Plugin download. Specifically, look at the script: 'Google IMAP - Fetch Token And Connect'

To better understand how these functions work, see the functions documentation here: Email Plugin Function Documentation

Working with Office 365

Office 365 Mail servers are moving away from basic authentication, and will soon require OAuth tokens in order to make a connection and send or receive email. The 360Works Email plugin now provides functions that will enable users to fetch OAuth tokens, and use those OAuth tokens to connect to Office 365 Mail servers.

OAuth Workflow integration adds a lot of security, but also adds complexity to you Email plugin workflows. Here are some examples of how you can utilize these new functions to get through the OAuth workflow so you can connect and send emails.

To better understand how the OAuth workflow works, let's walk through the most manual and straightforward OAuth workflow:

Office 365 OAuth Workflow: Manual Example

• Get the login url: Use the EmailOffice365GetLoginUrl function to get the Office 365 login url

• Copy that big url, and paste it in your browser. This will take you to the Office 365 login page:

• Log in to your Office 365 account, the one you will want to send email from (or receive email). If the login is successful, you should see the success page:

• Behind the scenes, Office 365 has given 360Works a token that you need. Fetch the token now with the function EmailOffice365ConnectIMAP:

• Now, you may be wondering: Do I have to log in every time? No. The token you got back is good for 90 days. Store the token, and re-use it in future connection statements without having to log in first:

• You may notice that the token is returned every time you call EmailOffice365ConnectIMAP or EmailOffice365ConnectSMTP. It is recommended to store the token that is retrieved every time you log in.

Office 365 OAuth Worflow: Automated Example

• Now for a more example of how you would see this workflow in a real FileMaker database, check out the demo file included with the 360Works Email Plugin download. Specifically, look at the script: 'Office365 SMTP - Fetch Token And Connect'

To better understand how these functions work, see the functions documentation here: Email Plugin Function Documentation

Troubleshooting

Too many errors on this connection

Some mail servers (typically IIS) have a configuration setting for how many messages can be sent across a single session. To solve this issue:

• Close the connection at the end of the loop, and re-open it at the beginning. This will slow down sending significantly, but is probably the easiest way to fix the problem
• Configure your SMTP server to remove any limitations on maximum number of messages, maximum message size, maximum number of failures allowed per connection. This might only be an option if you're hosting your own SMTP server
• Switch to a different SMTP server that has no limits on number of messages you can send.

EmailSend error: "Invalid Addresses"

It appears there is an issue sending messages using the plugin with some OS X. The EmailConnect works fine as do many of the other functions. But the EmailSend function returns the "Invalid Address(es)" error. The stack trace shows the following exception:

SMTPAddressFailedException: 504 5.5.2 <10.0.1.13>: Helo command rejected: need fully-qualified hostname

This is due to the spam settings on the mail server. A fix can be found here:

http://support.apple.com/kb/TS3023

EmailConnectX method error: "PKIX path building failed"

This error can occur when the underlying Java process for the Email plugin cannot establish a "secure" connection to the given mail server. This error can occur even if the mail server does not require any kind of secure connection such as SSL or TLS.

The Avast! antivirus Mail Shield can cause this error, so disable Mail Shield if you have Avast! antivirus installed.

There is a special parameter that can be passed to the EmailConnectX method (EmailConnectIMAP, EmailConnectSMTP, etc.) that will force the Java process to trust the connection it makes without regard to any warning/error messages. Pass an additional parameter to the EmailConnectX method of "forceTrust=true" to force the process to ignore an unverifiable connection. E.g., EmailConnectIMAP( "mail.server.com" ; "myUsername" ; "myPassword" ; "forceTrust=true" )

We strongly recommend you verify the IP address or DNS name of the mail server to ensure that you are connecting to the proper machine!

Downloaded emails are not decoded properly

When emails are decoded improperly, the resulting email body may either appear to be a very long string of various text characters or it may contain equals signs ("=") scattered throughout. Either of these issues is due to a decoding error where the machine running the plugin lacks the libraries required to decode the email properly.

v2.12 of the Email plugin incorporates a fix for this issue. Pass an additional parameter of "alternateDecoding=1" to the EmailReadMessages function to enable an alternate decoding method. Please contact support@360works.com for additional support regarding this issue.

Text justification issues in HTML

FileMaker's GetAsCSS function combines the <div> and <span> tags when it converts formatted text to HTML. This can cause spacing issues in the resulting HTML code due to how each tag is treated as a different kind of element (block vs inline). Most text ends up with a <span> tag which is treated as an inline element, and inline HTML elements do not treat spacing or text-justification in a common-sense manner when combined with the <div> tag. You can fix most spacing issues you may run into by adding the following HTML code to the email header

<style>span {display: block;} </style>

Gmail Compatibility

Google considers 3rd party apps to be "less secure" if they do not use the same encryption method for transmitting sign in credentials as they do. If you are having problems connecting to the Gmail mail servers please be sure to check in your account that you have "allow less secure apps" enabled. This setting is located in My Account->Sign-in&Security .

NOTE: GMail now only supports OAuth authentication so the above information is no longer valid. If you are using Gmail servers, you will need to have Email 4 or later and implement OAuth authentication.

Office365 Authentication unsuccessful

If you get an error message that says "535 5.7.3 Authentication unsuccessful" when trying to authenticate with Office365 servers, the issue is most likely that SMTP Auth needs to be turned on for your account. Please see the Microsoft documentation here for instructions.

Guidelines

Overview: Adding HTML with Inline Attachments

You can natively send plain text emails using the Send Mail script step in FileMaker, but what about emails that you need to be more graphically appealing? This is where 360Works Email Plugin meets a mission critical need by extending FileMaker’s existing email functionality, allowing you to send better email.

The email plugin allows you to include HTML formatting, inline attachments, and multiple attachments per email. Additionally, it is capable of receiving email via IMAP/POP and sending SMS text messages to phone numbers, all from your FileMaker solution. This section will show how you can send emails with HTML content and inline attachments with ease.

The email plugin example file provides a simple form layout to test the sending and receiving.

Select ‘Demo Examples’ in the left panel, and select the tab ‘Send HTML Email’.

Let’s take a look at the underlying script. The email plugin is simple to integrate into FileMaker. It takes just 4 lines of scripts to call the plugin! There are also comments included to help you define what the script does and what it affects.

The following image shows the 4 scripts it took to call the plugin to set the HTML body and inline attachments.

Finally, you can see the HTML and inline attachment has been rendered in the email message body.

Lower the chances of your email being identified as spam

Spam filters assign each incoming email a spam "score" that indicates the likelihood that the email is in fact spam. One flag that significantly increases the spam score of an email is if the "from" address is an email address only without a corresponding name (e.g., 360works@email.com). In order to avoid triggering this flag, you should add a name to your "from" address and put the email address in brackets following the name (e.g., 360Works <360works@email.com>). Please see the Internet Message Format RFC 2822 for more details

FileMaker's GetAsCSS function

GetAsCSS will take formatted FileMaker text and return HTML code that reproduces the formatted text in a form suitable for an HTML email. Use this to take bold, underlined, and even colored text from FileMaker to your HTML emails.

GetAsCSS also alters any HTML code in a FileMaker text field to be represented as plain-text in an HTML email. So if you have a formatted text field that also contains an HTML hyperlink (<a>), calling GetAsCSS will return the formatted text but it will change the HTML hyperlink into plain-text. This is because GetAsCSS alters the special characters (such as angle brackets and double-quotes) used to identify HTML code into their character entity equivalents. For example:

< becomes &lt;
> becomes &gt;
" becomes &quot;

If you must combine HTML code with formatted FileMaker text, you will need to call the Substitute function on the resulting text several times to replace the altered HTML special characters with their actual characters. For example:

Let(
[
text = GetAsCSS("<b>Formatted</b> text is the way to go! <a href=\"http://www.360works.com\">360Works!</a>");
first = Substitute(text ; "&lt;" ; "<" );
second = Substitute(first ; "&gt;" ; ">" );
final = Substitute(second ; "&quot;" ; "\"" )
];
final
)

POP mail server notes

POP (Post Office Protocol) mail servers are different from IMAP (Internet Message Access Protocol) mail servers in many ways, but one of the most important differences is that POP mail accounts only have a single folder: the Inbox.

POP mail servers keep only a single copy of each email on the mail server. You cannot create additional folders, and you cannot move emails around on the mail server since there is only one place (the Inbox) for them to go. However, using a mail client (e.g., Thunderbird, Mail.app, or PostBox) to interact with a POP mail server gives the illusion that you can create folders on the mail server. In fact, you are only creating local folders that the mail client itself uses to store the emails.

If you were to create a folder in a mail client while connected with a POP mailbox and move emails into that folder from the Inbox, you are actually removing the emails from the mail server and storing them locally (and only locally!) into the folder in the mail client. This removes the emails from the mail server which makes it impossible to retrieve them with the Email plugin, so be sure you are aware of how emails are stored if you work with a POP mailbox.

Read Receipts

Read receipts allow a user to confirm when the email has been read by the recipient(s). The Email standard defines a header called 'Disposition-Notification-To' which specifies the address to which read receipts should be sent. You can set this header using the EmailSetHeader function. For example, to send a read receipt to "address@hostname.com", you would call EmailSetHeader( "Disposition-Notification-To" ; "address@hostname.com" ). Whether or not this read receipt actually gets delivered is entirely dependent on the recipient's mail client. Some clients, such as Apple Mail or Gmail, don't support read receipts at all. Others, such as Google Apps (Google's online business suite) or Thunderbird, will offer a user the option to send the receipt or not. Therefore, not receiving a read receipt is not a guarantee that the message hasn't been read.

If you wish to implement sending read receipts with our plugin, simply check the header using EmailReadMessageValue("Disposition-Notification-To") when reading in emails. If the sender is requesting a read receipt, this function will return the desired address.

Fetch unread messages and create new records for each

The following is a simple FileMaker script can be used as a guideline for fetching unread messages and creating a record for each in FileMaker. Other options for finding unread messages are included here. The script assumes a table exists called ImportedMessages with fields for the desired message data. Passing the "uid" parameter when calling EmailReadMessages will get only messages with a larger UID, which will coincide with newer messages.

EmailConnectIMAP( "server" ; "username" ; "password" )

Go to Record/Request/Page [Last]
If [ isEmpty [ ImportedMessages::uid ]]
    # if no records exist with a UID, fetch all
    EmailReadMessages
Else
    # If there is a stored message with uid, get only newer messages
    EmailReadMessages[ ( "uid=" & ImportedMessages::uid ) ]

Loop
    # Exit loop if there are no more messages from the EmailGetMessages call
    Exit Loop If [ not EmailGetNextMessage ]
    # Create a new record for the currently fetched email
    New Record/Request
    Set Field [ ImportedMessages::subject ; EmailReadMessageValue( "subject" ) ]
    Set Field [ ImportedMessages::uid ; EmailReadMessageValue( "uid" ) ]
    # Set fields for the rest of the desired data
End Loop

Saving attachments to a container field

To save attachments from a specific message to container fields, you must loop through the list of attachments returned by EmailReadMessageValue("attachments"). The following script is a simple guide for retrieving messages and then saving each messages attachments. It assumes a table called Messages, as well as a separate table for Attachments, linking individual attachments to its originating message by messageId.

Go to Layout [ "Messages" ]
EmailConnectIMAP( "server" ; "username" ; "password" )

# attachments=true is needed to download a list/download attachments
EmailReadMessages("attachments=true")

# Loop through the returned messages to grab values, including attachments
Loop 
    Exit Loop If [not EmailGetNextMessage ]
    New Record/Request
    Set Field [ Messages::messageId ; EmailReadMessageValue("messageId") ]
    Set Field [ Messages::uid ; EmailReadMessageValue("uid") ]
    # ... other important values
    # Assumes another table called Attachments, with messageId tied between the two, and can create records based on relationship
    Set Field [ Messages::attachments ;  EmailReadMessageValue("attachments") ]

    #Check that there are attachments
    If { not IsEmpty Messages::attachments ]
        # Save the message ID and attachments list to variables before going to a new layout
        Set Variable [ $messageId ; Value: Messages::messageId ]
        Set Variable [ $messageAttachments; Value: Messages::attachments ]
        Go To Layout [ "Attachments" ]
        Set Variable [ $count ; Value: 1]
        # Loop through the attachments list and create records for each attachment
        Loop 
            Exit Loop If [ $count > ValueCount ( $messageAttachments) ]
            New Record / Request
            # Associate the current attachment record with our current messageid
            Set Field[  Attachments::messageId ;  $messageId ]
            Set Field[ Attachments::name ; Substitute ( MiddleValues ( $messageAttachments ; $count ; 1) ; "¶" ; "" ) ]
            Set Field[ Attachments::data ; EmailReadAttachment( Attachments::name ) ]
            Set Variable [$count ; Value: $count + 1 ]
            Commit Records/Requests
      End Loop
    End If
    Go to Layout [ "Messages" ]
    Commit Records/Requests
End Loop