Using e-mail fields correctly in Sugar

Post originally written by dwheelz.

Here is an important message from David Wheeler, a long time Software Engineer and Architect at SugarCRM, about using e-mail fields correctly.

E-mail handling is core to CRM software. Almost everyone we know uses multiple e-mail addresses every single day for both personal or work purposes. So it goes without saying that managing a person's multiple e-mail addresses correctly is essential in your Sugar customizations and integrations.

History of Sugar E-Mail fields

Several years ago, Sugar changed from using email# named text fields (like email1, email2, etc.) to using an e-mail relationship. This was done to better handle multiple e-mails, multiple relationships, and e-mail attributes like opt in or invalid.

However, use of the email1 field remains particularly persistent. We observe many examples of custom code (and some core code) that still use the old email# fields. This is probably because it is convenient to use the email1 field like a regular text field.But this is out of date, inaccurate, deprecated, and subject to removal in upcoming Sugar releases.

Below we will describe the proper method for using e-mail fields within Sugar customizations and integrations.

Sugar Metadata

You should reference the "email" field instead of "email#".

For record views, this will load a "email" type field widget with all related e-mail addresses included.

For list views, instead of all e-mail addresses only the primary e-mail address will be displayed.

Sugar PHP code

Instead of

$bean->email#

use

$bean->emailAddress->addresses

which references an array of e-mail addresses.

To determine the primary e-mail, you can iterate over the addresses array to find where the primary_address attribute is true.

foreach ($bean->emailAddresses->addresses as $address) {
    if ($address->primary_address == true) {
        // Found primary e-mail
    }
}

v10 REST API

When selecting a record's email field in a GET request, it will return a JSON array of all associated e-mail addresses.

When using a PUT request to update an e-mail address on a record, provide the complete e-mail address array.

For example,

"email": [
    {
        "email_address": "judith.banks@yahoo.com",
        "primary_address": true,
        "reply_to_address": false,
        "invalid_email": false,
        "opt_out": false
    },
    {
        "email_address": "jbanks@hotmail.com",
        "primary_address": false,
        "reply_to_address": false,
        "invalid_email": false,
        "opt_out": true
    }
],

If you leave off an e-mail address in a PUT request then this will be removed during the update to the record.

Sidecar code

For Sidecar code, you should not reference fields like email1, etc, when working with Beans or other models. You should be referencing the email field instead.

model.get("email1") --> model.get("email")

{$field.email1} --> {$fields.email_addresses_primary.email_address}

Other locations

You may still see email1 field referenced in e-mail templates used with Advanced Workflow or Campaigns module. Don't count on those sticking around. Please, use the email field instead.