Skip to content

mailerlite/mailerlite-python

BranchesTags

Repository files navigation

MailerLite Python SDK

MIT licensed

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

Table of Contents

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 requests.HTTPError exception. The exception includes the full response, so you can inspect the status code and error body:

import requests
import mailerlite as MailerLite

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

try:
    response = client.subscribers.get('some@email.com')
except requests.HTTPError as e:
    print(e.response.status_code)  # e.g. 404
    print(e.response.json())       # 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')

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)

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, page=1, 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'})

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'})

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)

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)

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()

About

No description or website provided.

Topics

sdk

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

6 stars

Watchers

2 watching

Forks

5 forks
Report repository

Releases 12

v0.2.0 Latest
Jul 6, 2026
+ 11 releases

Packages

 
 
 

Contributors

Languages