MailerLite developers website

Subscribers

You can add or update subscribers in your mailing list.

List all subscribers

If you want to list all of your subscribers, send this GET request

GET https://connect.mailerlite.com/api/subscribers
1

Request parameters

ParameterTypeRequiredLimitations
filter[status]stringnoMust be one of the possible statuses: active, unsubscribed, unconfirmed, bounced or junk.
limitintegernoDefaults to 25
cursorstringnoDefaults to first page. Cursor value available in response body
includestringnoAdditional resources to include in the response. Currently, only groups is supported.

Response

{
  "data": [
    {
      "id": "31986843064993537",
      "email": "dummy@example.com",
      "status": "active",
      "source": "api",
      "sent": 0,
      "opens_count": 0,
      "clicks_count": 0,
      "open_rate": 0,
      "click_rate": 0,
      "ip_address": null,
      "subscribed_at": "2021-09-01 14:03:50",
      "unsubscribed_at": null,
      "created_at": "2021-09-01 14:03:50",
      "updated_at": "2021-09-01 14:03:50",
      "fields": {
        "city": null,
        "company": null,
        "country": null,
        "last_name": "Testerson",
        "name": "Dummy",
        "phone": null,
        "state": null,
        "z_i_p": null
      },
      "opted_in_at": null,
      "optin_ip": null
    }
  ],
  "links": {
     "first": null,
     "last": null,
     "prev": "https://connect.mailerlite.com/api/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9",
     "next": "https://connect.mailerlite.com/api/subscribers?cursor=eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
  },
  "meta": {
      "path": "https://connect.mailerlite.com/api/subscribers",
      "per_page": 25,
      "next_cursor": "eyJpZCI6NzI1ODIxNjQ2NDY5ODcxMzYsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
      "prev_cursor": "eyJpZCI6NzI1ODIxNjQ2NDU5Mzg1NTksIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

Create/upsert subscriber

If you want to create or update a subscriber, send this POST request

POST https://connect.mailerlite.com/api/subscribers
1

If a subscriber already exists, it will be updated with new values. This is non-destructive operation, so omitting fields or groups will not remove them from subscriber.

Request

ParameterTypeRequiredLimitations
emailstringyesValid email address as per RFC 2821
fieldsobjectnoObject keys must correspond to default or custom field name. Values can only be added this way and will not be removed by omission.
groupsarraynoarray must contain existing group ids. Subscriber can only be added to groups this way and will not be removed by omission
statusstringnoCan be one of the following: active, unsubscribed, unconfirmed, bounced, junk
subscribed_atstringnoMust be a valid date in the format yyyy-MM-dd HH:mm:ss
ip_addressstringnoMust be a valid ip address
opted_in_atstringnoMust be a valid date in the format yyyy-MM-dd HH:mm:ss
optin_ipstringnoMust be a valid ip address
unsubscribed_atstringnoMust be a valid date in the format yyyy-MM-dd HH:mm:ss
{
    "email": "dummy@example.com",
    "fields": {
      "name": "Dummy",
      "last_name": "Testerson"
    },
    "groups": [
        "4243829086487936",
        "14133878422767533",
        "31985378335392975"
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12

Response

If the subscriber was created:

Response Code: 201 Created
1

If the subscriber with specified email was already in the mailing list:

Response Code: 200 OK
1
{
  "data": {
    "id": "31897397363737859",
    "email": "dummy@example.com",
    "status": "active",
    "source": "api",
    "sent": 0,
    "opens_count": 0,
    "clicks_count": 0,
    "open_rate": 0,
    "click_rate": 0,
    "ip_address": null,
    "subscribed_at": "2021-08-31 14:22:08",
    "unsubscribed_at": null,
    "created_at": "2021-08-31 14:22:08",
    "updated_at": "2021-08-31 14:22:08",
    "fields": {
      "city": null,
      "company": null,
      "country": null,
      "last_name": "Testerson",
      "name": "Dummy",
      "phone": null,
      "state": null,
      "z_i_p": null
    },
    "groups": [],
    "opted_in_at": null,
    "optin_ip": null
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Error

Response Code: 422 Unprocessable Entity
1
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email must be a valid email address."]
  }
}
1
2
3
4
5
6

Update a subscriber

If you want to update a single subscriber, send this PUT request:

PUT https://connect.mailerlite.com/api/subscribers/(:id)
1

If a subscriber already exists, it will be updated.

Request

ParameterTypeRequiredLimitations
fieldsobjectnoObject keys must correspond to default or custom field name. Values can only be added this way and will not be removed by omission.
groupsarraynoarray containing existing group ids. Subscriber will be removed from unlisted groups
statusstringnoCan be one of the following: active, unsubscribed, unconfirmed, bounced, junk
subscribed_atstringnoMust be a valid date in the format yyyy-MM-dd HH:mm:ss
ip_addressstringnoMust be a valid ip address
opted_in_atstringnoMust be a valid date in the format yyyy-MM-dd HH:mm:ss
optin_ipstringnoMust be a valid ip address
unsubscribed_atstringnoMust be a valid date in the format yyyy-MM-dd HH:mm:ss
{
    "fields": {
      "name": "Dummy",
      "last_name": null
    },
    "groups": [
        "4243829086487936",
        "14133878422767533",
        "31985378335392975"
    ]
}
1
2
3
4
5
6
7
8
9
10
11

Response

Response Code: 200 OK
1
{
  "data": {
    "id": "31897397363737859",
    "email": "dummy@example.com",
    "status": "active",
    "source": "api",
    "sent": 0,
    "opens_count": 0,
    "clicks_count": 0,
    "open_rate": 0,
    "click_rate": 0,
    "ip_address": null,
    "subscribed_at": "2021-08-31 14:22:08",
    "unsubscribed_at": null,
    "created_at": "2021-08-31 14:22:08",
    "updated_at": "2021-08-31 14:22:08",
    "fields": {
      "city": null,
      "company": null,
      "country": null,
      "last_name": null,
      "name": "Dummy",
      "phone": null,
      "state": null,
      "z_i_p": null
    },
    "groups": [],
    "opted_in_at": null,
    "optin_ip": null
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Error

Response Code: 422 Unprocessable Entity
1
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email must be a valid email address."]
  }
}
1
2
3
4
5
6

Fetch a subscriber

If you want to fetch a subscriber, send this GET request

GET https://connect.mailerlite.com/api/subscribers/(:id or :email)
1

Request

ParameterTypeRequiredLimitations
emailstringnoMust provide either valid subscriber id or email
idstringnoMust provide either valid subscriber id or email
GET https://connect.mailerlite.com/api/subscribers/31986843064993537
GET https://connect.mailerlite.com/api/subscribers/dummy@example.com
1
2

Response

If subscriber exists:

Response Code: 200 OK
1
{
  "data": {
    "id": "31986843064993537",
    "email": "dummy@example.com",
    "status": "active",
    "source": "api",
    "sent": 0,
    "opens_count": 0,
    "clicks_count": 0,
    "open_rate": 0,
    "click_rate": 0,
    "ip_address": null,
    "subscribed_at": "2021-09-01 14:03:50",
    "unsubscribed_at": null,
    "created_at": "2021-09-01 14:03:50",
    "updated_at": "2021-09-01 14:03:50",
    "fields": {
      "city": null,
      "company": null,
      "country": null,
      "last_name": "Testerson",
      "name": "Dummy",
      "phone": null,
      "state": null,
      "z_i_p": null
    },
    "groups": [],
    "opted_in_at": null,
    "optin_ip": null
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Error

If the subscriber cannot be found:

Response Code: 404 Not Found
1

Fetch total subscribers count

GET https://connect.mailerlite.com/api/subscribers?limit=0
1

Request

ParameterTypeRequiredLimitations
limitintegeryesValue must be 0

Response

Response Code: 200 OK
1
{
  "total": 100
}
1
2
3

Fetch subscriber activity

GET https://connect.mailerlite.com/api/subscribers/:id/activity-log
1

Request

ParameterTypeRequiredLimitations
idstringyesMust provide either valid subscriber id
filter[log_name]stringnoMust be one of the possible log_name: campaign_send, automation_email_sent, email_open, link_click, email_bounce, spam_complaint, unsubscribed, email_forward, marketing_preferences_change or preference_center.
limitintegernoDefaults to 100
pageintegernoCount starts from 1

Response

Response Code: 200 OK
1
{
  "data": [
    {
      "id": "1235",
      "log_name": "added_to_group",
      "subject_id": "1000000000000000",
      "subject_type": "subscribers",
      "properties": {
        "group_name": "test group",
        "group_id": "1"
      },
      "created_at": "2024-05-01 12:43:29",
      "updated_at": "2024-05-01 12:43:29"
    },
    {
      "id": "1234",
      "log_name": "activated",
      "subject_id": "1000000000000000",
      "subject_type": "subscribers",
      "properties": [],
      "created_at": "2024-05-01 12:43:29",
      "updated_at": "2024-05-01 12:43:29"
    },
    {
      "id": "123456",
      "log_name": "email_open",
      "subject_id": "123456",
      "subject_type": "opens",
      "properties": {
        "type": "campaigns",
        "campaign_id": "123456",
        "campaign_name": "Example name",
        "preview_url": "https://example_preview.url"
      },
      "created_at": "2024-09-01 00:00:00",
      "updated_at": "2024-09-01 00:00:00"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

Delete a subscriber

It will removes the subscriber from your account, but all their information is still kept in case they re-subscribe to your list. If you want to delete a subscriber, send this DELETE request

DELETE https://connect.mailerlite.com/api/subscribers/:id
1

Request

ParameterTypeRequiredLimitations
idstringyesValid subscriber id for the account

Response

Response Code: 204 No Content
1

Error

Response Code: 404 Not Found
1

Forget a subscriber

It will removes the subscriber from your account and all information will be completely deleted in 30 days. This feature is GDPR compliant.If you want to forget a subscriber, send this POST request

POST https://connect.mailerlite.com/api/subscribers/:id/forget
1

Request

ParameterTypeRequiredLimitations
idstringyesValid subscriber id for the account

Response

Response Code: 200 OK
1
{
  "message": "Subscriber data will be completely deleted and forgotten within 30 days.",
  "data": {
    "id": "85348545455981948",
    "email": "bashirian.wilhelmine@yahoo.com",
    "status": "active",
    "source": "subscribe app",
    "sent": 89,
    "opens_count": 0,
    "clicks_count": 0,
    "open_rate": 0,
    "click_rate": 0,
    "ip_address": "140.229.243.225",
    "subscribed_at": "2023-04-13 14:05:15",
    "unsubscribed_at": null,
    "created_at": "2023-04-13 14:05:15",
    "updated_at": "2023-04-19 05:40:50",
    "deleted_at": "2023-04-19 05:40:50",
    "forget_at": "2023-05-19 05:40:50",
    "fields": {
      "name": "Carmella",
      "last_name": "Hegmann",
      "company": "DuBuque Inc",
      "country": "Puerto Rico",
      "city": "Moshemouth",
      "phone": "1-628-782-7066",
      "state": null,
      "zip": null
    },
    "groups": [
      {
        "id": "85348546500363273",
        "name": "sint incidunt",
        "active_count": 20,
        "sent_count": 1284,
        "opens_count": 0,
        "open_rate": {
          "float": 0,
          "string": "0%"
        },
        "clicks_count": 0,
        "click_rate": {
          "float": 0,
          "string": "0%"
        },
        "unsubscribed_count": 0,
        "unconfirmed_count": 0,
        "bounced_count": 0,
        "junk_count": 0,
        "created_at": "2023-04-13 14:05:16",
        "processing": true,
        "used_in_forms": false,
        "used_in_sites": false
      }
    ],
    "location": {
      "id": "1",
      "title": "New York City",
      "country_name": "United States of America",
      "continent_name": "North America",
      "state_name": "New York",
      "time_zone": "America/New_York"
    },
    "opted_in_at": null,
    "optin_ip": null,
    "email_changed_at": null
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

Error

Response code: 404 Not Found
1

Get single import

If you want to get a single import report, send this GET request

GET https://connect.mailerlite.com/api/subscribers/import/{import_id}
1

Response

Response Code: 200 OK
1
{
  "data": {
    "id": "47366063630845932",
    "total": 3,
    "processed": 3,
    "imported": 0,
    "updated": 0,
    "errored": 3,
    "percent": 100,
    "done": true,
    "file_path": "",
    "invalid": [],
    "invalid_count": 0,
    "mistyped": [],
    "mistyped_count": 0,
    "changed": [],
    "changed_count": 0,
    "unchanged": [
      {
        "id": "47366064023013357",
        "email": "dummy_one@import.com"
      },
      {
        "id": "47366064023013358",
        "email": "dummy_two+two@import.com"
      },
      {
        "id": "47366064023013359",
        "email": "dummy_three@new.com"
      }
    ],
    "unchanged_count": 3,
    "unsubscribed": [],
    "unsubscribed_count": 0,
    "role_based": [],
    "role_based_count": 0,
    "banned_import_emails_count": 0,
    "match_route": "",
    "source_label": "",
    "updated_at": "2022-02-18T08:09:58.000000Z",
    "undone_at": null,
    "stopped_at": null,
    "undo_started_at": null,
    "finished_at": "2022-02-18T08:09:58.000000Z"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
Last Updated: