Fields
Create, update, list, and delete the custom fields you can attach to subscribers.
Fields are the custom attributes you store on subscribers, such as a first name, a plan tier or a renewal date.
Each field has a name you choose and a key derived from it when the field is created. The key is the identifier you use when setting values in a subscriber's fields object, and it stays the same if you rename the field.
A field's type is fixed when it is created and cannot be changed afterwards:
| Type | Stores |
|---|---|
text | Any string value. |
number | Numeric values you can compare in segment rules. |
date | Dates you can compare in segment rules and use to schedule automations. |
An account can hold at most 200 fields, counting both the defaults and your own.
MailerLite provides a set of default fields that every account has. Those cannot be renamed or deleted, only read.
Deleting a custom field means its values are no longer returned on any subscriber, and flags any automation that uses the field as broken until you fix it.
List all fields
If you want to list all of your fields, use this GET endpoint
GET https://connect.mailerlite.com/api/fieldsRequest parameters
| Parameter | Type | Required | Limitations |
|---|---|---|---|
| limit | integer | no | Number of fields to return per page. Defaults to 200, which is the most fields an account can have. Maximum 1000. |
| page | integer | no | Page number to return. Counting starts from 1 |
| filter[keyword] | string | no | Return only fields whose name contains this value |
| filter[type] | string | no | Return only fields of this type. One of text, number or date. Separate several types with commas |
| sort | string | no | Field to sort results by. One of name or type. Prefix with - for descending order, e.g. -name. Defaults to name |
Response
Response Code: 200 OK{
"data": [
{
"id": "1",
"name": "new field",
"key": "new_field",
"type": "text"
}
],
"links": {
"first": "https://connect.mailerlite.com/api/fields?page=1",
"last": "https://connect.mailerlite.com/api/fields?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://connect.mailerlite.com/api/fields?page=1",
"label": "1",
"active": true
},
{
"url": null,
"label": "Next »",
"active": false
}
],
"path": "https://connect.mailerlite.com/api/fields",
"per_page": 100,
"to": 1,
"total": 1
}
}Create a field
If you want to create a field that can be assigned to subscribers, use this POST request
POST https://connect.mailerlite.com/api/fieldsRequest body
| Parameter | Type | Required | Limitations |
|---|---|---|---|
| name | string | yes | Up to 255 characters, and must not match an existing or reserved field name |
| type | string | yes | One of text, number or date. Cannot be changed later |
Response
Response Code: 201 Created{
"data": {
"id": "1",
"name": "new field",
"key": "new_field",
"type": "text"
}
}Error
If invalid data has been passed
Response Code: 422 Unprocessable Entity{
"message": "The given data was invalid.",
"errors": {
"type": ["The selected type is invalid."]
}
}Update a field
If you want to update a field, use this PUT request
PUT https://connect.mailerlite.com/api/fields/{field_id}Request body
| Parameter | Type | Required | Limitations |
|---|---|---|---|
| name | string | yes | Maximum length of 255 characters |
Response
Response Code: 200 OK{
"data": {
"id": "1",
"name": "new field",
"key": "new_field",
"type": "text"
}
}Error
If invalid data has been passed
Response Code: 422 Unprocessable Entity{
"message": "The given data was invalid.",
"errors": {
"type": ["The name may not be greater than 255 characters."]
}
}Delete a field
If you want to delete a field, use this DELETE request
DELETE https://connect.mailerlite.com/api/fields/{field_id}Response
Response code: 204 No ContentError
Response Code: 404 Not found