Skip to content
This repository has been archived by the owner on Jul 17, 2023. It is now read-only.

Python wrapper for Mailerlite API v2

License

Notifications You must be signed in to change notification settings

skoudoro/mailerlite-api-python

Repository files navigation

⚠️⚠️⚠️⚠️⚠️ WARNING ⚠️⚠️⚠️⚠️⚠️ : This REPO is no longer maintained in favor of the official mailerlite python client look here

Mailerlite-api-python

Python Wrapper for Mailerlite API

Deployment pypi mailerlite
Build Status
Metrics codacy mailerlite python
License bsd
Community

Getting Started

Installation

This client is hosted at PyPi under the name mailerlite-api-python, to install it, simply run

pip install mailerlite-api-python

or install dev version:

git clone https://github.com/skoudoro/mailerlite-api-python.git
pip install -e .

Method reference

For the complete reference, visit the official MailerLite API reference.

Notes

This version is handling the V2_BETA API (classic version).

we are currently updating the project to handle the new V2 released last summer 2022.

Examples

Initialization

First, Grab YOUR_API_KEY from your Mailerlite account (Profile > Integrations > Developer Api).

>>> from mailerlite import MailerLiteApi
>>> api = MailerLiteApi('YOUR_API_KEY')

A second option is to define an environment variable named MAILERLITE_PYTHON_API_KEY. Then, you do not need to precise it in your code:

>>> from mailerlite import MailerLiteApi
>>> api = MailerLiteApi()

Campaigns

Get all campaigns or a specific one

>>> all_campaigns = api.campaigns.all()
>>> draft = api.compaings.all(status='draft')

Modify a campaign

>>> one_campaign = all_campaigns[0]
>>> html = '<head></head><body><h1>Title</h1><p>Content</p><p><small><a href=\"{$unsubscribe}\">Unsubscribe</a></small></p></body>'
>>> plain = "Your email client does not support HTML emails. "
>>> plain += "Open newsletter here: {$url}. If you do not want"
>>> plain += " to receive emails from us, click here: {$unsubscribe}"

>>> api.campaigns.update(one_campaign.id, html=html, plain=plain)

Create / Delete a campaign

>>> data = {"subject": "Regular campaign subject",
            "name": "Regular campaign name",
            "groups": [2984475, 3237221],
            "type": "regular"}
>>> api.campaigns.create(data)
>>> api.campaigns.delete(campaign_id=3971635)

Send a campaign

>>> data = {"subject": "Regular campaign subject",
            "name": "Regular campaign name",
            "groups": [2984475, 3237221],
            "type": "regular"}
>>>
>>> _, res = api.campaigns.create(data)
>>> campaign_id = res['id']
>>>
>>> html = '<head></head><body><h1>Your Title</h1><p>Your Content</p><p><small>'
>>> html += '<a href=\"{$unsubscribe}\">Unsubscribe</a></small></p></body>'
>>> plain = "Your email client does not support HTML emails. "
>>> plain += "Open newsletter here: {$url}. If you do not want"
>>> plain += " to receive emails from us, click here: {$unsubscribe}"
>>>
>>> api.campaigns.update(campaign_id, html=html, plain=plain)
>>> api.campaigns.send(campaign_id)

Cancel a scheduled campaign

>>> outbox_campaigns = campaign_obj.all(status='outbox', limit=5)
>>> selected_campaign = outbox_campaigns[0]
>>>
>>> api.campaigns.cancel(selected_campaign.id)

count campaign

>>> api.campaigns.count()
>>> api.campaigns.count(status='draft')

Subscribers

Get all subscribers

>>> api.subscribers.all()
>>> api.subscribers.all(stype='active')
>>> api.subscribers.active()
>>> api.subscribers.unsubscribed()
>>> api.subscribers.bounced()
>>> api.subscribers.junk()
>>> api.subscribers.unconfirmed()

Get one subscriber

>>> api.subscribers.get(email='[email protected]')
>>> api.subscribers.get(id=1343965485)

search

>>> api.subscribers.search(search='[email protected]')

subscribers groups

>>> api.subscribers.groups(id=1343965485)

subscribers activity

>>> api.subscribers.activity(id='1343965485')
>>> api.subscribers.activity(id='1343965485', limit=50, offset=1, atype='clicks')

Create subscriber

>>> data = {'name': 'John',
            'email': '[email protected]',
            'fields': {'company': 'MailerLite'}
            }
>>> api.subscribers.create(data)

Update subscriber

>>> data = {'name': 'John',
            'fields': {'company': 'MailerLite'}
            }
>>> api.subscribers.update(data, id='1343965485')

Count subscribers

Get the total count of all subscribers in a single call.

Please, be aware that this is not a documented feature in the official API.

>>> api.subscribers.count()

Groups

Get all Groups

>>> api.groups.all()
>>> api.groups.all(limit=50)
>>> api.groups.all(offset=10)
>>> api.groups.all(gfilters='My Group')
>>> api.groups.all(group_id=12345)

Create a Group

>>> api.groups.create(group_id=12345, name='My New Group')

Rename a Group

>>> api.groups.update(group_id=12345, name='New Name')

Get a Group

>>> api.groups.get(group_id=12345)

Delete a Group

>>> api.groups.delete()
>>> api.groups.delete(group_id=12345)

Get all subscribers in a Group

>>> api.groups.subscribers(group_id=12345)
>>> api.groups.subscribers(group_id=12345, limit=50, offset=1)
>>> api.groups.subscribers(group_id=12345, stype='active')

Get one subscriber from a Group

>>> api.groups.subscriber(group_id=12345, subscriber_id=54321)

Add list of subscribers to a Group

This method calls the import endpoint https://developers.mailerlite.com/reference#add-many-subscribers

>>> api.groups.add_subscribers(group_id=12345, subscribers_data=[{"email": "[email protected]", "name": "John Wick"}], autoresponders=False, resubscribe=False, as_json=False)

subscriber_data argument accepts a list of dictionaries or just one dictionary containing the subscriber name and email

Add a single subscriber to a Group

This method calls the add single subscriber endpoint https://developers.mailerlite.com/reference#add-single-subscriber

>>> api.groups.add_single_subscriber(group_id=12345, subscribers_data={"email": "[email protected]", "name": "John Wick" ...}, autoresponders=False, resubscribe=False, as_json=False)

Unlike the method above, this adds only one subscriber to a group. The subscriber_data argument accepts all subscriber attributes. Check available attributes on https://developers.mailerlite.com/reference#create-a-subscriber

Delete one subscriber from a Group

>>> api.groups.delete_subscriber(group_id=12345, subscriber_id=54321)

Segments

Get list of Segments

>>> api.segments.all()

Get count of Segments

>>> api.segments.count()

Fields

Get list of Fields

>>> api.fields.all()

Get one Field

>>> api.fields.get(field_id=123456)

Create / update / delete one Field

>>> api.fields.create(title="my custom title")
>>> api.fields.update(field_id=123456, title="my new title 2")
>>> api.fields.delete(field_id=123456)

Webhooks

Get list of Webhooks

>>> api.webhooks.all()

Get one webhook

>>> api.webhooks.get(webhook_id=123456)

Create/update/delete one webhook

>>> api.webhooks.create(url="https://yoursite/script-is-here",
...                     event="subscriber.create")
>>> api.webhooks.update(webhook_id=123456,
...                     url="https://yoursite/script-is-here",
...                     event="subscriber.create")
>>> api.webhooks.delete(webhook_id=123456)

Account

# Get some info or stats
>>> api.account.info()
>>> api.account.stats()
>>> api.account.double_optin()
# Set up the double_optin
>>> api.account.set_double_optin(True)

Batch

>>> batch_requests = {"requests": [{"method":"GET",
...                                 "path": "/api/v2/groups"
...                                 },
...                                 {"method":"POST",
...                                  "path": "/api/v2/groups",
...                                  "body": {"name": "New group"}
...                                 }
...                                 ]
...                    }
>>> api.batch(batch_requests)

Tests

  • Step 1: Install pytest
  pip install pytest
  • Step 2: Run the tests
  pytest -svv mailerlite

Contribute

We love contributions!

You've discovered a bug or something else you want to change - excellent! Create an issue!

You've worked out a way to fix it – even better! Submit a Pull Request!

Start with the contributing guide!

License

Project under 3-clause BSD license, more informations here