Custom Fields

Overview

SMTPProvider Application allows you to add custom fields to a mailing list, so that you can associate additional information with each subscriber record beyond the base information already included in the subscriber record. Each subscriber on the mailing list can store a value for each custom field.

For example, custom fields might be First Name or CustomerID.

Each mailing list maintains its own set of custom fields which are independent from any other mailing list.

Properties Common to Most Custom Fields

Name

(Valid for all custom field types)

The name that describes this custom field. The name will appear wherever the custom field is referenced. For example, Name or Favorite Color. The name must be less than 50 characters.

A mailing list can not have two custom fields with the same name.

Required

(Valid for all custom field types).

This states that a value is required.

For each field type, this means specifically:

Field type Behavior
Text A blank string, or string only containing whitespace is not allowed.
Text Multiline A blank string, or string only containing whitespace is not allowed.
Number A number must be specified.
Date A date must be specified.
Select Single Dropdown One option must be selected.
Select Single Radio One option must be selected.
Select Multiple Checkboxes At least one option must be checked.
Boolean True or False must be selected, and blank values are not allowed.

This requirement is enforced when editing or adding a subscriber through the UI and through an import.

You may want to create a default value for custom fields that are required. If a required field does not have a default value, then a value must be manually specified for that field.

If you enable the required option for a custom field on a list that already has subscribers, then you may have subscribers which don’t have any value. If/when you edit these subscribers, you then must supply a value for the required custom fields, because the subscriber will not validate without the a value for the required custom field.

Coming Feature

In a coming release we will allow you to set the value for all subscribers that
do not have a value when you make a field required. We may require that you do
this, so that all records always meet the validation requirements. This will
avoid the above potential problem.

Instructions

Each custom field’s Instructions setting is used to control the text that’s displayed below the custom field when adding or editing subscriber. This field may be left blank if the custom field has no instructions.

5516d51d3774c33d087408800c0b34ad8dcfec04  e443cc686a8b69ea04c0a1eb37b943acc8708da4

You can toggle instructions on and off by clicking the Quick Tips button:

acc32b967fa00ea6e348a474eb6578533bee7970

Default Value

Valid for only these types of custom fields:

  • Text
  • Text Multiline
  • Number
  • Boolean
Coming Feature

In a future release we will allow you to specify a default value for all custom field types.

The default value is used as the default for any new subscribers. Specifically:

  • If you manually add a subscriber through the UI, the form will be pre-populated with this default value.
  • If you add a subscriber using the import feature and do not associate a column with this custom field or hard-code a value to this custom field, then the default value will be used.

What this setting does not do:

  • If you add a subscriber through the UI or the import feature and specify a blank value for this custom field, a blank value will be stored (or for a Boolean custom field, False will be stored). The default value will NOT be used.
  • Adding a default value to a custom field or creating a new custom field with a default value, does NOT affect the value for any subscribers already in the list, even if they don’t have a value for this custom field.

Custom Field Types

There are many types of custom fields to support different types of data.

Text

Allows a single line of text to be entered.

Field Parameters:

  • Default value – See this page’s Default Value section.
  • Minimum length – The minimum length in characters for any non-blank values. Leave blank to have no requirement.
  • Maximum length – The maximum length in characters for any non-blank values. Leave blank to have no requirement.
  • Interpolation – Allows you to specify how the field value will be replaced in the content or click URL. By default, content will be HTML encoded in HTML emails or URL encoded in click URLs.

Misc details:

  • Accepts UTF-8 text.
  • Maximum amount of data supported: 1,024 characters
  • Leading and trailing whitespaces are not stripped.

Text Multiline

Allows multiple lines of text to be entered with a multi-line text box.

Field Parameters:

  • Default value – See this page’s “Default Value” section.
  • Number of rows – The number of lines tall to make the editing box when presenting this field in a form. Defaults to 5 if blank. Valid values are 1100. This does not limit the amount of data that may be entered.
  • Interpolation – Allows you to specify how the field value will be replaced in the content or click URL. By default, content will be HTML encoded in HTML emails or URL encoded in click URLs.

Misc details:

  • Accepts UTF-8 text.
  • Maximum amount of data supported: 10,240 characters
  • Leading and trailing whitespaces are not stripped.

Number

Allows an integer number.

Field Parameters:

  • Default value – See this page’s “Default Value” section.
  • Minimum value – The minimum integer value required when this field is not blank. Leave this blank to have no requirement.
  • Maximum value – The minimum integer value required when this field is not blank. Leave this blank to have no requirement.

Misc details:

  • Integers may only be entered as follows: an optional hyphen (-) followed by one or more digits. Scientific notation, hex, octal, or binary formats are not supported. Leading and trailing whitespace is stripped.
  • Decimal values, such as 12.3, are not supported by this type.
  • Range of valid values: -2,147,483,648 to 2,147,483,647(signed 32-bit integers).

Date

Allows a date to be entered. A date consists of a valid year, month, and day.

Field Parameters:

  • Display order – The order to display year, month and date to the user.

Misc details:

  • Dates must appear on the Gregorian calendar to be valid. For example: February 29th 2011 is not a valid date.
  • Range of valid values: January 1, 1700 to December 31, 3000.
  • Uses Gregorian calendar for all dates.

Select Single Dropdown

Allows zero or one of several pre-defined options to be selected.

Shows the options to the user using a drop-down box.

Field Parameters:

  • Select options – A list of the different options and the order they will be presented to the user.

Select Single Radio

Allows one or more options to be selected. Shows the options to the user using radio buttons.

Field Parameters:

  • Select options – A list of the different options and the order they will be presented to the user.

Misc details:

  • It is possible for zero options to be selected. This can happen two ways: (1) a blank text value is imported into this custom field, or (2) this custom field is added to a list that already has subscribers, each already-existing subscriber will have no options selected for this custom field.

Select Multiple Checkboxes

Allows zero or more options to be selected. Shows the options to the user with a checkbox for each option.

Field Parameters:

  • Select options – A list of the different options and the order they will be presented to the user.

Misc details:

  • It is possible for zero options to be selected by un-checking all of the checkboxes.

Boolean

Allows a true or false value to be selected.

Field Parameters:

  • Default value – See this page’s Default Value section.

Adding Custom Fields to a List That Already Has Subscribers

If you add a custom field to a list that already has subscribers, then subscribers already in the database will get the following value for the newly created custom field:

Field type Value
Text A blank string
Text Multiline A blank string
Number A blank value
Date A blank value
Select Single Dropdown No options will be selected
Select Single Radio No options will be selected
Select Multiple Checkboxes No options will be selected
Boolean False

Editing Field Requirements

It is possible for subscriber data in the database to not meet the current validation requirements of the custom fields.

This can happen if:

  • You set a field to be required where subscribers already have blank values for it.
  • You change the minimum length or maximum length parameters for a text field.
  • You change the maximum value or minimum value parameters for a number custom field.
  • You remove options from a select custom field that is required and there were subscribers who had only this option selected.

A subscriber being in the database with invalid data has interesting effects:

  • If you edit a subscriber, make no changes, and try to save the form, the save will fail.
  • If you do an import and try to update one column with valid data, the import can fail on that subscriber because a different column that you didn’t attempt to update had invalid data.

We recommend that you avoid creating subscribers with invalid data. Think very carefully before your tighten validation requirements on existing custom fields.

Upcoming feature

A future release will likely prevent you from modifying the requirements so that any existing subscribers end up having invalid data.

Editing Options on Select Field Types

If you rename an option, all subscribers that had that option selected with the old name will have it selected with the new name.

If you remove an option on a select-type field, then all subscribers which have this option selected will no longer have this option selected. If you then create a new option with that same name, none of those subscribers who had the old option with that name selected will have the new option with that name selected.

If you add an option, no already existing subscribers will have this option selected.

Different Mailing Lists With the Same Custom Fields

Each mailing list has its own custom fields which are separate from any other mailing list.

This means that if you have a First Name field on Mailing list #1 and a First Name field on Mailing list #2, and you update the field on Mailing list #1 the changes are not automatically applied to the First Name field on Mailing list #2. The two custom fields are completely different objects in the database, even though they have the same name.

However, we know that sometimes you want multiple mailing lists to have the same custom fields. So, if you have custom field objects on different mailing lists that have the same name and all of the same settings, if you edit one, the system will ask if you want the apply the changes to all custom fields in different mailing lists that are identical.

If you add a new custom field to a mailing list, and there is a different mailing list with exactly the same custom fields as the first mailing list, the system will ask you if you want to add the same custom field to those other mailing lists.