Email Address Fields

Liferay DXP 2026.Q3+

Email Address fields store and validate email addresses entered on forms and through the API. Objects normalizes every value to lowercase before storage, and you can configure the field to block specific domains or suggest domains through autocomplete.

Adding an Email Address Field

Open the Global Menu () and navigate to Control Panel → Objects.
Click the object definition you want to edit.
Go to the Fields tab and click the Add button ().
Enter a Label and Field Name.
Select Email Address as the field type.
Turn on Enable Entry Translation to store a separate email address per language. This option cannot be changed after the object definition is published.
Enable Mandatory if entries must provide a value.
Turn on Accept Unique Values Only to prevent two entries from storing the same email address. You can change this while the object definition is a draft.
Click Save.

Note

Saving adds the field to the object definition’s draft. Publish the draft to make the field available in forms and through the API. See Publishing Object Drafts.

To configure blocked domains and autocomplete suggestions, click the field in the Fields tab and open the Advanced tab of the Field panel. See Advanced Options.

Validation and Storage

Objects normalizes every entered email address to lowercase before storing the value. Object entry API responses return that stored lowercase value, regardless of the case used when the value was entered or submitted.

Objects applies the 254-character maximum defined by RFC 5321 to every Email Address field, so the limit is enforced without configuration.

Advanced Options

The Advanced tab of an Email Address field’s configuration panel has four sections: Read Only, Default Value, Blocked Domains, and Autocomplete. Blocked Domains and Autocomplete are specific to Email Address fields. Blocked Domains has a Domains input, and Autocomplete shows its Domains input only after you turn on Enable Autocomplete.

The Advanced tab of an Email Address field's configuration panel shows the Read Only, Default Value, Blocked Domains, and Autocomplete sections.

Blocking Domains

Use the Blocked Domains section to reject email addresses from specific domains.

In the object definition’s Fields tab, click the field to edit it.
Go to the Advanced tab.
In the Blocked Domains section, enter a domain in the Domains input (for example, @example.com) and press Enter.

The domain appears in the list below the input.
Click Save.

Objects matches blocked domains case-insensitively against the domain portion of a submitted address. When an entry matches a blocked domain, Objects rejects it with this message: “The email address domain is not allowed. Enter an email address with a different domain.” Through the API, the same rejection returns HTTP 400 with that message as the problem title.

Enabling Autocomplete

Use the Autocomplete section to suggest domains as users type an email address.

In the object definition’s Fields tab, click the field to edit it.
Go to the Advanced tab.
In the Autocomplete section, turn on Enable Autocomplete.
Enter a domain in the Domains input (for example, @liferay.com) and press Enter.

The domain appears in the list below the input.
Click Save.

As users type an email address, Objects suggests the configured domains in a drop-down menu, narrowing the list once they type @ and start a domain. These domains are suggestion-only; they do not restrict which domains Objects accepts for the field. Objects omits any domain that also appears in Blocked Domains from the suggestions.

Field Options

Email Address fields support these standard Object field options:

Mandatory: Entries without a value are rejected. The Object Admin REST API exposes this option as required.
Accept Unique Values Only: Prevents two entries from storing the same email address, using a case-insensitive comparison. Set this when adding the field. You can change it while the object definition is a draft, but not after publishing.
Default Value: Sets a pre-filled value for new entries. Set this on the Advanced tab: turn on Use Default Value, then enter the address or build it with an expression. Objects validates the default value as a real email address and normalizes it to lowercase before saving. A default value matching a blocked domain is rejected the same way a submitted entry is.
Enable Entry Translation: Stores separate email addresses per language or locale when the object definition enables localization. This option cannot be changed after the object definition is published.

Email Address fields are also available as variables in Expression Builder and Notification Templates.

Using Email Address Fields with APIs

When querying an object definition’s fields through the Object Admin REST API, each Email Address field includes "businessType": "EmailAddress" in its response. Use this property to distinguish Email Address fields from standard Text fields programmatically.

curl "http://localhost:8080/o/object-admin/v1.0/object-definitions/{objectDefinitionId}/object-fields" \
     -u 'test@liferay.com:learn'

Replace {objectDefinitionId} with the object definition’s ID. Listing object definitions at /o/object-admin/v1.0/object-definitions returns the id for each one.

When creating or updating entries, pass the email address as a string. Objects normalizes the value to lowercase before storage regardless of the case you submit. This example adds an entry to an object named Contact Request whose email address field is named emailAddress:

curl -X "POST" "http://localhost:8080/o/c/contactrequests?restrictFields=actions" \
     -H "Content-Type: application/json" \
     -u 'test@liferay.com:learn' \
     -d '{"emailAddress": "User@Example.COM"}'

The response contains the stored, lowercase value:

{
  "emailAddress": "user@example.com"
}

Replace emailAddress with your field’s configured field name and contactrequests with your object’s API endpoint name. The endpoint name is the lowercase plural of the object’s name, and it appears as restContextPath on the object definition. See Custom Object APIs. The restrictFields=actions parameter is optional and omits the actions block from the response.

If a value fails validation, the API returns HTTP 400 with the failure described in the response title. Submitting an address whose domain is blocked returns “The email address domain is not allowed. Enter an email address with a different domain.”

Note

Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2.