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")

This will return a JavaScript array in the same format as returned by the REST API (above). This array of e-mails is typically iterated through for display in custom Handlebars templates.

PDF Templates

This change also applies to PDF templates. Here is the correct way to reference the primary e-mail address from a PDF template.

{$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.

Anonymous
  • Thanks everyone for the input.  The reality is email1 works, so I will have to use it. When it breaks, if it ever does, i will have to fix it!  - See you all then ;-)

  • I respectfully disagree on avoiding the usage of email1 as it pertains to Sugar Logic. While the developer blog post states email1 is deprecated, that post was over 2+ years ago and utilization of email1 remains prominent throughout the codebase and in the developer guide. If email1 is ever truly deprecated, I expect that the upgrade introducing that deprecation would at a minimum come with some significant warning and hopefully an automatic conversion for in-app elements such as Sugar Logic that currently rely on its functionality. 

  • I would not use email1, as is stated in this blog email1 "is out of date, inaccurate, deprecated, and subject to removal in upcoming Sugar releases."

    If you can't get the formula to work, I would make the field read only and use a before_save logic_hook to retrieve the primary email address from the related record and set it that way.

    FrancescaS

  • Hi Luke,

    Congratulations on finding the solution! email1 is how Sugar has programmatically referred to the primary email address of a record for 10+ years (if not always). If this formula breaks, there are much larger issues at hand. :-)

  • Update

    related($contacts_r_rma_1,"email") returns 'Array'

    related($contacts_r_rma_1,"email1") Works like a dream!   I will have to use this until it breaks?