Rate this page:

Using Custom Fields

This page is describing the functionality of the new Marketing Campaigns experience, if you're using legacy Marketing Campaigns, your workflow and screens may be a little different. For more information on the new Marketing Campaigns experience click here.

Custom Fields allow you to add extra information about a contact within your contact database when you upload a CSV. You can use custom fields to create dynamic segments or to personalize the subject lines or content of Marketing Campaigns emails you send. Your custom fields are completely customizable to the use cases and user information that you need.

You can create up to 120 custom fields.

Creating Custom Fields

To add a custom field:

The most common way to add custom fields is by including each custom field you’d like to add as a column in your CSV upload. If you’d like to add custom fields programmatically, see our API documentation

You can also add custom fields manually from the Custom Fields page.

  1. Navigate to the Custom Fields page and click New Custom Field.
  2. Add a Field Name and select a Field Type.
  3. Click Create Field.

The field name should be created using only alphanumeric characters (A-Z and 0-9) and underscores (_). Custom fields should only begin with letters A-Z or underscores (_). The field type can be date, text, or number fields. The field type is important for creating segments from your contact database. Note: If you have created a custom field that begins with a number, you will need to recreate it with a name that begins with letters A-Z or an underscore (_).

Custom fields that begin with a number will cause issues when sending with Marketing Campaigns.

You can create three different types of custom fields, based on the data type. Each data type will allow you to use different queries for segmentation:

  • Date - allows you to select contacts before, after, or on a specific date. Example: 1/1/2014
  • Text - allows you to select contacts who match the specific text. Example: Pet field that says "Dog"
  • Number - allows you to do things like “greater than,” “less than,” or “equals” a specific number. Both decimal and integer values are accepted. Example: The age of your recipient: 27

Text custom fields are limited to 1,000 characters.

Reserved Fields

Your account comes preloaded with unremovable reserved fields. The following field names are all reserved:

Field NameField Type
first_nametext
last_nametext
emailtext
alternate_emailstext
address_line_1text
address_line_2text
citytext
state_province_regiontext
postal_codetext
countrytext
phone_numbertext
whatsapptext
linetext
facebooktext
unique_nametext

SendGrid auto-populates 6 reserved fields:

lists

created_at

updated_at

last_emailed

last_clicked

last_opened

Reserved fields are used by default to track useful metrics for your contacts.

Deleting a Custom Field

To delete a custom field:

  1. Navigate to Marketing and select Custom Fields.
  2. Locate the field you wish to remove.
  3. Hover over the action menu to the right of the field name entry.
  4. Select the delete icon.
  5. Click Delete Field.

This deletion process may take several minutes; you will continue to see the custom field on this page until the process completes.

Deleting a custom field deletes all values for that field across your contact database. It will also break Single Sends or Automation emails using the custom field as a tag or segments using the field as a condition. See below for details.

If a deleted custom field is used as a tag within a Single Send or Automation email as part of the subject line or body copy, the email will send with the default value you've designated or the fall back "default". If you have deleted the fallback, the email will not display anything at all in place of the deleted custom field.

If a deleted custom field is used as criteria within a segment the segment will fail to load. Neither Single Sends nor Automation emails will be able to be sent to the segment using the deleted custom field.

Troubleshooting

If a custom field value does not appear in the corresponding Substitution Tag, make sure that there is a value for that custom field associated with the contact in your contact database. If there is no value for a particular custom field, a space will be substituted instead.

If you do find that the custom field has an associated value on the contact’s profile page, check the spelling of the substitution tag in the content of your campaign.

Additional Resources

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

      
      
      

      Thank you for your feedback!

      We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

      Sending your feedback...
      🎉 Thank you for your feedback!
      Something went wrong. Please try again.

      Thanks for your feedback!

      Refer us and get $10 in 3 simple steps!

      Step 1

      Get link

      Get a free personal referral link here

      Step 2

      Give $10

      Your user signs up and upgrade using link

      Step 3

      Get $10

      1,250 free SMSes
      OR 1,000 free voice mins
      OR 12,000 chats
      OR more