API reference

Custom fields

Create, update, copy, list and delete custom fields on EmailMarketer.io lists through the API.

Custom fields store extra data per subscriber, such as first name, plan or country. A field belongs to one list, or to every list when it is global. All commands take APIKey and are sent to POST https://app.emailmarketer.io/api.php with Command.

customfield.create

Parameter Type Required Description
SubscriberListID int Yes
FieldName string Yes, unless PresetName is sent
FieldType string Yes, unless PresetName is sent Field type
PresetName string No A ready-made field, for example Country
DataType string No text, longtext, number, datetime, date, time, timestamp, single-select or multi-select. Overrides FieldType
DefaultValue string No
ValidationMethod string No Disabled, Numbers, Letters, Numbers and letters, Email address, URL, Date, Time or Custom
ValidationRule string When ValidationMethod is Custom
MergeTagAlias string No Name used in merge tags. Reserved names are refused
OptionLabel, OptionValue, OptionSelected array No Choices for select fields
IsRequired, IsUnique, IsGlobal string No Yes or No
Visibility string No Public, User Only or Hidden
Years string For date fields YYYY-YYYY
curl https://app.emailmarketer.io/api.php \
  -d Command=customfield.create \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123 \
  -d FieldName=Company \
  -d FieldType="Single line" \
  -d IsRequired=Yes
{ "Success": true, "ErrorCode": 0, "CustomFieldID": 456 }
Code Meaning
1 Missing list ID
2 Missing field name
3 Missing field type
4 Missing validation rule
5 Invalid preset
7 Invalid data type
8 Invalid list ID
1000 The merge tag alias is used by another field
1001 The alias has invalid characters
1002 The alias is a reserved name

customfield.update

Requires CustomFieldID, FieldName and FieldType. Takes the same optional parameters as create. A field cannot move to another list. Options you omit are kept. ValidationRule is required for Date, Time and Custom validation.

curl https://app.emailmarketer.io/api.php \
  -d Command=customfield.update \
  -d APIKey="$EM_API_KEY" \
  -d CustomFieldID=456 \
  -d FieldName="Company name" \
  -d FieldType="Single line"
Code Meaning
1, 2, 3, 4 Missing field ID, name, type or rule
6 Invalid field ID
7 to 12 Invalid type, validation method, visibility, IsRequired, IsUnique or IsGlobal
13 The list is not yours
14 The list cannot be changed
1000 to 1002 As in create

customfields.get

Requires SubscriberListID.

Parameter Description
OrderField FieldName (default), CustomFieldID, FieldType, IsRequired, IsUnique, Visibility or IsGlobal
OrderType ASC or DESC
ReturnGlobalCustomFields Include global fields. Default false
curl https://app.emailmarketer.io/api.php \
  -d Command=customfields.get \
  -d APIKey="$EM_API_KEY" \
  -d SubscriberListID=123 \
  -d ReturnGlobalCustomFields=true
{ "Success": true, "ErrorCode": 0, "TotalFieldCount": 5, "CustomFields": [{ "CustomFieldID": "456", "RelListID": "123", "FieldName": "Company", "FieldType": "Single line", "ValidationMethod": "Disabled", "IsRequired": "No", "IsUnique": "No", "Visibility": "Public", "IsGlobal": "No" }] }

Errors: 1 missing list ID, 2 invalid list ID. List IDs must be digits only.

customfields.copy

Copies every field from one list to another. Requires SourceListID and TargetListID. Errors: 1 missing source, 2 missing target, 3 invalid source, 4 invalid target.

curl https://app.emailmarketer.io/api.php \
  -d Command=customfields.copy \
  -d APIKey="$EM_API_KEY" \
  -d SourceListID=123 \
  -d TargetListID=124

customfields.delete

Requires CustomFields, comma-separated field IDs. Either all are deleted or none. Errors: 1 missing IDs, 2 an ID is invalid or belongs to another account.

curl https://app.emailmarketer.io/api.php \
  -d Command=customfields.delete \
  -d APIKey="$EM_API_KEY" \
  -d CustomFields=456,457

Using fields