Using E-mail Fields Correctly in Sugar

by David Wheeler on September 5, 2017

This article originally appeared on SugarCRM's Developer Blog.

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 email1email2, 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.

Example of e-mail field in Record view

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

Example of e-mail field in List view

Sugar PHP Code

Instead of




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


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": "",
        "primary_address": true,
        "reply_to_address": false,
        "invalid_email": false,
        "opt_out": false
        "email_address": "",
        "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.

Find similar articles in these categories:


AUDIENCE: Developers