Support (800) 775-8378 Contact Us

    Using E-mail Fields Correctly in Sugar

    By David Wheeler • September 5th, 2017
    Audiences: Developers

    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

    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": "",
            "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.