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
- Set values with
CustomFieldsin subscriber.create orFieldsin subscriber.update. - Filter on them in segment rules with the
fieldsrule type.