MailerLite Python SDK

Getting started

For more information about MailerLite API, please visit the following link:

Authentication

API keys are a quick way to implement machine-to-machine authentication without any direct inputs from a human beyond initial setup.

For more information how to obtain an API key visit the following link

Installation

Please run the following command:

python -m pip install mailerlite

Usage

MailerLite Client

The first thing that you need to do is to import mailerlite into your project and to instantiate the client by passing your API key:

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

MailerLite API supports versioning, so you can pass additional argument to specify the API version:

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key", "api_version": "2038-01-19"})

Error handling

API responses with a 4xx or 5xx status code raise a mailerlite.ApiError exception. ApiError is a subclass of requests.HTTPError, so except requests.HTTPError continues to work. The exception has these attributes:

status_code: the HTTP status code.
message: the error message of the API.
code: a machine-readable error code, if the API sends one. For example, version_conflict.
etag: the current etag of the email, if the API sends one. The API sends it with version_conflict.
errors: the validation errors for each field, if the API sends them.
response: the full requests.Response.

The attributes are None when the response does not have them.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

try:
    response = client.subscribers.get("some@email.com")
except MailerLite.ApiError as e:
    print(e.status_code)  # e.g. 404
    print(e.message)  # error message from the API
    print(e.errors)  # validation errors, if any
    print(e.response.json())  # full error body from the API

Network-level failures (DNS errors, connection resets, timeouts) raise the standard requests exceptions such as requests.ConnectionError and requests.Timeout. Catch requests.RequestException to handle both HTTP and network errors with a single handler.

Note: the batch endpoint (client.batch.request()) returns HTTP 200 even when individual sub-requests fail, so no exception is raised for them — check the per-request status codes in the returned body.

Upgrading from 0.1.x: methods that previously returned False or a raw status code on failure now raise requests.HTTPError instead. In particular, subscribers.delete() and subscribers.forget() used to return 204/200 and now return True on success.

Subscribers

List all subscribers

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.subscribers.list(limit=10, page=1, filter={"status": "active"})

Create a subscriber

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.subscribers.create(
    "some@email.com",
    fields={"name": "John", "last_name": "Doe"},
    ip_address="1.2.3.4",
    optin_ip="1.2.3.4",
)

Update a subscriber

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.subscribers.update(
    "some@email.com",
    fields={"name": "New", "last_name": "Name"},
    ip_address="1.2.3.5",
    optin_ip="1.2.3.5",
)

update sends PUT /subscribers/{subscriber}. The first argument is the email address or the ID of the subscriber. The subscriber must exist, or the API returns 404. groups replaces the subscriber's groups: groups you leave out are removed. To create a subscriber, or to add groups without removing others, use create. Pass new_email to change the email address.

Get a subscriber

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.subscribers.get("some@email.com")

Delete a subscriber

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

subscriber_id = 1234567890

response = client.subscribers.delete(subscriber_id)

Forget a subscriber

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

subscriber_id = 1234567890

response = client.subscribers.forget(subscriber_id)

Get subscriber activity

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

subscriber_id = 1234567890

response = client.subscribers.activity_log(
    subscriber_id, limit=10, page=1, filter={"log_name": "email_open"}
)

Groups

List all groups

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.groups.list(limit=10, page=1, filter={"name": "My"}, sort="name")

Create a group

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

group_name = "My Group"

response = client.groups.create(group_name)

Update a group

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

group_id = 1234567
group_name = "My New Group"

response = client.groups.update(group_id, group_name)

Delete a group

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

group_id = 1234567

response = client.groups.delete(group_id)

Get subscribers belonging to a group

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

group_id = 1234567

response = client.groups.get_group_subscribers(
    group_id, limit=10, filter={"status": "active"}
)

next_cursor = response["meta"]["next_cursor"]
response = client.groups.get_group_subscribers(
    group_id, cursor=next_cursor, limit=10, filter={"status": "active"}
)

Import bulk subscribers to a group

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

group_id = 1234567
subscribers = [
    {"email": "subscriber1@example.com", "name": "Subscriber One"},
    {"email": "subscriber2@example.com", "name": "Subscriber Two"},
]

response = client.groups.import_subscribers_to_group(group_id, subscribers)

Assign subscriber to a group

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

subscriber_id = 111222
group_id = 1234567

response = client.subscribers.assign_subscriber_to_group(subscriber_id, group_id)

Unassign subscriber from a group

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

subscriber_id = 111222
group_id = 1234567

response = client.subscribers.unassign_subscriber_from_group(subscriber_id, group_id)

Segments

List all segments

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.segments.list(limit=10, page=1)

Update a segment

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

segment_id = 123456
name = "My New Segment Name"

response = client.segments.update(segment_id, name)

Delete a segment

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

segment_id = 123456

response = client.segments.delete(segment_id)

Get segment information

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

segment_id = 123456

response = client.segments.get(segment_id, limit=10, filter={"status": "active"})

Get subscribers belonging to a segment

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

segment_id = 123456

response = client.segments.get_subscribers(
    segment_id, limit=10, filter={"status": "active"}
)

next_cursor = response["meta"]["next_cursor"]
response = client.segments.get_subscribers(
    segment_id, cursor=next_cursor, limit=10, filter={"status": "active"}
)

Fields

List all fields

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.fields.list(
    limit=10, page=1, sort="name", filter={"keyword": "abc", "type": "text"}
)

Create a field

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

name = "My Field"
type = "text"

response = client.fields.create(name, type)

Update a field

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

field_id = 123456
name = "My New Field"

response = client.fields.update(field_id, name)

Delete a field

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

field_id = 123456

response = client.fields.delete(field_id)

Automations

List all automations

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.automations.list(
    limit=10, page=1, filter={"enabled": True, "name": "some name", "group": 123456}
)

Get an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.get(automation_id)

Get subscribers activity for an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.activity(
    automation_id,
    page=1,
    limit=10,
    filter={"status": "active", "date_from": "2022-12-20", "date_to": "2022-12-31"},
)

Create an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.automations.create("My automation")

Update an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.update(automation_id, "My new name")

Delete an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.delete(automation_id)

Copy an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.copy(automation_id)

Enable an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.enable(automation_id)

Disable an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.disable(automation_id)

Send a test of an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.test(automation_id, "some@email.com")

Add subscribers to an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.add_subscribers(
    automation_id, emails=["some@email.com"], groups=[1234567]
)

Re-add subscribers to an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.readd(
    automation_id, "last_completed_step", {"status": "completed"}
)

Copy automation subscribers to groups

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.activity_add_to_group(
    automation_id, ["1234567"], {"status": "completed"}
)

Cancel active automation runs

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.activity_cancel_automation(
    automation_id, {"status": "active"}
)

Skip an automation delay

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.activity_skip_delay(automation_id, {"status": "active"})

List automation triggers

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.list_triggers(automation_id)

Create an automation trigger

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.create_trigger(
    automation_id, "subscriber_joins_group", data={"group_ids": [1234567]}
)

Get an automation trigger

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
trigger_id = 123456

response = client.automations.get_trigger(automation_id, trigger_id)

Update an automation trigger

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
trigger_id = 123456

response = client.automations.update_trigger(
    automation_id, trigger_id, data={"group_ids": [1234567]}
)

Delete an automation trigger

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
trigger_id = 123456

response = client.automations.delete_trigger(automation_id, trigger_id)

List automation steps

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.list_steps(automation_id)

Create an automation step

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.create_step(
    automation_id, "delay", parent_id=123456, data={"unit": "days", "value": 1}
)

Get an automation step

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.get_step(automation_id, step_id)

Update an automation step

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.update_step(
    automation_id, step_id, data={"unit": "days", "value": 2}
)

Delete an automation step

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.delete_step(
    automation_id, step_id, branch_to_delete="all"
)

Copy an automation step

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.copy_step(automation_id, step_id, parent_id=123456)

Move an automation step

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.reorder_steps(
    automation_id, step_id, new_parent_step_id=123456
)

Select the winner of an A/B test step

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.select_ab_test_winner(automation_id, step_id, "a_path")

Get the content of an automation email

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
email_id = 123456

response = client.automations.get_email_content(automation_id, email_id)

Update the content of an automation email

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
email_id = 123456

response = client.automations.update_email_content(
    automation_id, email_id, "<p>Hello</p>"
)

Get the report stats of an automation email

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
email_id = 123456

response = client.automations.email_report_stats(
    automation_id, email_id, start_date="2026-01-01", end_date="2026-01-31"
)

Get the unsubscribe reasons of an automation email

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
email_id = 123456

response = client.automations.email_unsubscribe_reasons(automation_id, email_id)

List automation templates

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.automations.list_templates(limit=10, page=1, filter={"category": 1})

Create an automation from a template

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

template_id = 123456

response = client.automations.select_template(template_id)

Get the run counts of automation steps

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.steps_run_counts(automation_id)
response = client.automations.step_run_counts(automation_id, step_id)

Get the run counts of automation triggers

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
trigger_id = 123456

response = client.automations.triggers_run_counts(automation_id)
response = client.automations.trigger_run_counts(automation_id, trigger_id)

Get the stats of A/B test steps

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.ab_steps_stats(automation_id)
response = client.automations.ab_step_stats(automation_id, step_id)

List the subscribers on an automation step

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
step_id = 123456

response = client.automations.step_subscribers(
    automation_id, step_id, "queued", limit=10, page=1
)

List the subscribers on an automation trigger

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456
trigger_id = 123456

response = client.automations.trigger_subscribers(
    automation_id, trigger_id, "completed", limit=10, page=1
)

Get the monthly email totals of an automation

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

automation_id = 123456

response = client.automations.email_monthly_totals(
    automation_id, start_date="2026-01-01", end_date="2026-06-30"
)

Campaigns

List all campaigns

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.campaigns.list(
    limit=10, page=1, filter={"status": "ready", "type": "regular"}
)

Get a campaign

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

campaign_id = 123456

response = client.campaigns.get(campaign_id)

Create a campaign

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

params = {
    "name": "Test Campaign",
    "language_id": 1,
    "type": "regular",
    "emails": [
        {
            "subject": "This is a test campaign",
            "from_name": "Test Man",
            "from": "testuser@mailerlite.com",
            "content": "Hi there, this is a test campaign!",
        }
    ],
}

response = client.campaigns.create(params)

Create a simple editor campaign

To build the email with the simple editor, set editor to MailerLite.EDITOR_SIMPLE, and do not send content. Then edit the email with the email methods.

template_id is optional. It is a shared template of the simple editor that the email starts from. It needs editor.
All emails of a campaign must have the same editor and template_id.
Only create accepts editor and template_id. update does not.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

params = {
    "name": "Test Campaign",
    "type": "regular",
    "emails": [
        {
            "subject": "This is a test campaign",
            "from_name": "Test Man",
            "from": "testuser@mailerlite.com",
            "editor": MailerLite.EDITOR_SIMPLE,
        }
    ],
}

response = client.campaigns.create(params)

email_id = response["data"]["emails"][0]["id"]

Update a campaign

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

campaign_id = 123456
params = {
    "name": "New Campaign Name",
    "language_id": 2,
    "emails": [
        {
            "subject": "This is a test campaign",
            "from_name": "Test Man",
            "from": "testuser@mailerlite.com",
            "content": "Hi there, this is a test campaign!",
        }
    ],
}

response = client.campaigns.update(campaign_id, params)

Schedule a campaign

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

campaign_id = 123456
params = {
    "delivery": "scheduled",
    "schedule": {"date": "2022-12-31", "hours": "22", "minutes": "00"},
}

response = client.campaigns.schedule(campaign_id, params)

Cancel a campaign

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

campaign_id = 123456

response = client.campaigns.cancel(campaign_id)

Delete a campaign

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

campaign_id = 123456

response = client.campaigns.delete(campaign_id)

Get subscribers activity for a campaign

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

campaign_id = 123456

response = client.campaigns.activity(campaign_id)

Emails

These methods edit emails built with the simple editor. To create such an email, create a simple editor campaign. The ID of the email is in response['data']['emails'][0]['id'].

IDs are strings of digits. You can also give them as int. An empty ID raises mailerlite.EmptyIdError, and an ID that does not contain only digits raises mailerlite.InvalidIdError. The SDK sends no request in these cases.
Before the request, the SDK checks only the IDs and the settings of update_settings(). It sends all other values as you give them, and the API checks them. An invalid value raises mailerlite.ApiError, for example with status 422.
The methods return a mailerlite.ApiResponse. It is a dict with the response body, and it also has status_code and headers.
Each write needs the etag from the last response for the email, and returns a new etag. The etag covers the whole email, so send the writes to one email one after another.
If the email changed after you read it, the write raises mailerlite.ApiError with code equal to mailerlite.VERSION_CONFLICT. Its etag is the current etag. Get the email again, and then repeat the write with the current etag.
The keys of editor_content are camelCase, for example textAlign. The SDK sends them as you give them.

Get an email

Returns the email with its settings and blocks, and the etag of the email.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"

response = client.emails.get(email_id)

email = response["data"]
etag = response["etag"]

Get the HTML of an email

Returns the HTML that the email sends. The API can return a temporary 503 error. If it does, try again later.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"

response = client.emails.get_html(email_id)

html = response["data"]["html"]

Get a block

Returns the block and its place in the email: placement has the IDs of the blocks after and before it, or None.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"
block_id = "57"

response = client.emails.get_block(email_id, block_id)

block = response["data"]

Insert a block

Use the block types in MailerLite.BlockType. editor_content can be empty. Without placement, the API puts the block at the end of the email. The before and after positions also need a block_id. The API ignores the block_id of start and end. The SDK sends the placement as you give it.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"
etag = client.emails.get(email_id)["etag"]

response = client.emails.create_block(
    email_id,
    etag,
    MailerLite.BlockType.PARAGRAPH,
    {"attrs": {"textAlign": "left"}, "content": [{"type": "text", "text": "Hello"}]},
    placement={"position": MailerLite.BlockPosition.START},
)

block_id = response["data"]["id"]
etag = response["etag"]

Update a block

The new editor_content replaces the whole content of the block. The API removes the keys that you do not send.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"
block_id = "57"
etag = "etag-from-the-last-response"

response = client.emails.update_block(
    email_id,
    block_id,
    etag,
    {
        "attrs": {"textAlign": "center"},
        "content": [{"type": "text", "text": "Hello again"}],
    },
)

etag = response["etag"]

Delete a block

Also deletes the blocks in it. The response has only the new etag.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"
block_id = "57"
etag = "etag-from-the-last-response"

response = client.emails.delete_block(email_id, block_id, etag)

etag = response["etag"]

Move a block

The before and after positions also need a block_id. The API ignores the block_id of start and end. The SDK sends the placement as you give it.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"
block_id = "57"
etag = "etag-from-the-last-response"

response = client.emails.move_block(
    email_id,
    block_id,
    etag,
    {"position": MailerLite.BlockPosition.AFTER, "block_id": "12"},
)

etag = response["etag"]

Validate a block

Checks a block before you insert it. It needs no email and no etag. An invalid block does not raise an error: the response has valid set to False and the errors for each field.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.emails.validate_block(
    MailerLite.BlockType.BUTTON,
    {
        "attrs": {"href": "https://example.com"},
        "content": [{"type": "text", "text": "Buy now"}],
    },
)

if not response["valid"]:
    print(response["errors"])

Update the design settings

Send only the keys to change, in the shape of settings in the email. The groups are brand, layout, typography, button and footer.

Send all style values as strings, for example '16' and not 16.
The API stores each value that you send, also a value that the email inherits from your account. Then the email no longer follows your account for that value.
To unset a brand colour, send an empty string. The API stores the value empty, and the email then uses the account value.
To unset a footer text, send an empty editor document: {'editor_content': {}} or {'editor_content': {'content': []}}.
Other colours, sizes, button.border_radius and brand.style cannot be empty. An empty string gives a 422 error.
footer.social_links replaces the whole list. Keep the link_id of each link to keep its click history.
brand.mode is one of MailerLite.BrandMode. To apply a preset palette, send its identifier from the brand styles in brand.style.
If the API removed unsafe values, the response has rejected with the keys of these values.
settings must be a dict without an etag key, because the SDK adds the etag argument to it. Otherwise the SDK raises TypeError or ValueError and sends no request.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"
etag = "etag-from-the-last-response"

response = client.emails.update_settings(
    email_id,
    etag,
    {
        "brand": {"mode": MailerLite.BrandMode.CUSTOM, "background_color": "#f4f4f4"},
        "typography": {"paragraph": {"p1": {"size": "18"}}},
    },
)

etag = response["etag"]
if response.get("rejected"):
    print(response["rejected"]["keys"])

Validate the design settings

Checks a change with the rules of the update, and saves nothing. It needs no etag. Invalid settings do not raise an error: the response has valid set to False and the errors for each field.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"

response = client.emails.validate_settings(
    email_id,
    {
        "button": {"border_radius": "8"},
    },
)

if not response["valid"]:
    print(response["errors"])

Save an email as a template

Copies the email to a new template. The API cannot delete templates.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"

response = client.emails.create_template(email_id, "Monthly newsletter")

template_id = response["data"]["id"]

List the versions of an email

A version is a saved copy of the content and the settings of an email. The list starts with the newest version. current marks the version that the email has now.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"

response = client.emails.list_versions(email_id, page=1, limit=10)

Save a version of an email

Writes through the API do not save versions. If nothing changed after the last version, the API saves no new version and returns the last version. response.status_code is 201 for a new version and 200 for the last version.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"

response = client.emails.create_version(email_id)

version_id = response["data"]["id"]
is_new = response.status_code == 201

Restore a version of an email

Puts the email back to the version, and returns the full email with the new etag. Before the restore, the API saves the current state as a version, so you can undo the restore.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"
version_id = "901"
etag = "etag-from-the-last-response"

response = client.emails.restore_version(email_id, version_id, etag)

etag = response["etag"]

Retry a write with an idempotency key

If a write fails with a network error, you do not know if the API did the write. Give the write an idempotency_key, and retry it with the same key and the same arguments. If the first request succeeded, the API returns the stored response and does not do the write two times. Then response.is_idempotent_replay is True.

Use a new key for each write. The API keeps a key for 24 hours.
The key must be 1 to 255 printable ASCII characters. The SDK sends the key as you give it. The API answers an invalid key with status 400.
If requests cannot send the key in a header, it raises requests.exceptions.InvalidHeader. For example, a key with a space at the start or a new line causes this error.
The same key with different arguments raises ApiError with status 422. If the first request is still running, the API returns 409 without a code.
These methods accept a key: create_block, update_block, delete_block, move_block, update_settings, create_template, create_version and restore_version.

import uuid

import requests
import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

email_id = "123456"
etag = "etag-from-the-last-response"
key = str(uuid.uuid4())

try:
    response = client.emails.create_block(
        email_id, etag, MailerLite.BlockType.DIVIDER, {}, idempotency_key=key
    )
except (requests.ConnectionError, requests.Timeout):
    # Network error: retry with the same key and the same arguments.
    response = client.emails.create_block(
        email_id, etag, MailerLite.BlockType.DIVIDER, {}, idempotency_key=key
    )

print(response["data"]["id"], response.is_idempotent_replay)

Brand styles

Get the brand styles

Returns the palettes of your account: brand (your brand styles, or None if your account has none), default and the presets. Match a palette on its identifier, not on its name. To apply a preset to an email, update the design settings with {'brand': {'style': identifier}}.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.brand_styles.get()

identifiers = [preset["identifier"] for preset in response["data"]["presets"]]

Files

List all files

Returns the files of your media library. Use their url in image blocks. width and height are None for files that are not images.

filter: name (a part of the file name) and type (one of MailerLite.FileType).
sort: one of MailerLite.FileSort. The default is newest first.

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.files.list(
    filter={"name": "summer sale", "type": MailerLite.FileType.IMAGE},
    sort=MailerLite.FileSort.SIZE_DESCENDING,
    page=1,
    limit=25,
)

Forms

List all forms

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.forms.list(
    limit=10, page=1, sort="name", filter={"name": "form name"}
)

Get a form

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

form_id = 123456

response = client.forms.get(form_id)

Update a form

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

form_id = 123456
name = "New Form Name"

response = client.forms.update(form_id, name)

Delete a form

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

form_id = 123456

response = client.forms.delete(form_id)

Get subscribers who signed up to a specific form

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

form_id = 123456

response = client.forms.get_subscribers(
    form_id, page=1, limit=10, filter={"status": "active"}
)

Batching

Create a new batch

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

params = [
    {"method": "GET", "path": "api/subscribers/list"},
    {"method": "GET", "path": "api/campaigns/list"},
]

response = self.client.batches.request(params)

Webhooks

List all webhooks

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.webhooks.list()

Get a webhook

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

webhook_id = 123456

response = client.webhooks.get(webhook_id)

Create a webhook

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

events = ["subscriber.created", "subscriber.updated", "subscriber.unsubscribed"]
url = "https://my-url.com"
name = "Webhook name"

response = client.webhooks.create(events, url, name)

Update a webhook

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

webhook_id = 123456
events = ["subscriber.created", "subscriber.updated", "subscriber.unsubscribed"]
url = "https://my-url.com"
name = "Webhook name"
enabled = False

response = client.webhooks.update(webhook_id, events, url, name, enabled)

Delete a webhook

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

webhook_id = 123456

response = client.webhooks.delete(webhook_id)

Timezones

Get a list of timezones

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.timezone.list()

Campaign languages

Get a list of languages

import mailerlite as MailerLite

client = MailerLite.Client({"api_key": "your-api-key"})

response = client.campaigns.languages()

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
mailerlite		mailerlite
tests		tests
.coveragerc		.coveragerc
.envrc		.envrc
.flake8		.flake8
.gitignore		.gitignore
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Readme.md		Readme.md
VERSION		VERSION
flake.lock		flake.lock
flake.nix		flake.nix
lefthook.yml		lefthook.yml
pyproject.toml		pyproject.toml
renovate.json		renovate.json
requirements.txt		requirements.txt
setup.py		setup.py
test-requirements.txt		test-requirements.txt
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation