# Listmonk Email App API Client for Python
Client for the for open source, self-hosted [Listmonk email platform](https://listmonk.app) based on
[httpx](https://www.python-httpx.org) and [pydantic](https://pydantic.dev).
`listmonk` is intended for integrating your Listmonk instance into your web app. The [Listmonk API is extensive](https://listmonk.app/docs/apis/apis/) but this only covers the subset that most developers will need for common SaaS actions such as subscribe, unsubscribe, and segmentate users (into separate lists).
So while it doesn't currently cover every endpoint (for example you cannot create a list programatically nor can you edit HTML templates for campaigns over APIs) it will likely work for you. That said, PRs are weclome.
🔀 Async is currently planned but not yet implemented. With the httpx-base, it should be trivial if needed.
## Core Features
* ➕**Add a subscriber** to your subscribed users.
* 🙎 Get **subscriber details** by email, ID, UUID, and more.
* 📝 **Modify subscriber details** (including custom attribute collection).
* 🔍 **Search** your users based on app and custom attributes.
* 🏥 Check the **health and connectivity** of your instance.
* 👥 Retrieve your **segmentation lists**, list details, and subscribers.
* 🙅 Unsubscribe and block users who don't want to be contacted further.
* 💥 Completely delete a subscriber from your instance.
* 📧 Send transactional email with template data (e.g. password reset emails).
## Installation
Just `pip install listmonk`
## Usage
```python
import pathlib
import listmonk
listmonk.set_url_base('https://yourlistmonkurl.com')
listmonk.login('sammy_z', '1234')
valid: bool = listmonk.verify_login()
# Is it alive and working?
up: bool = listmonk.is_healthy()
# Read data about your lists
lists: list[] = listmonk.lists()
the_list: MailingList = listmonk.list_by_id(list_id=7)
# Various ways to access existing subscribers
subscribers: list[] = listmonk.subscribers(list_id=9)
subscriber: Subscriber = listmonk.subscriber_by_email('testuser@some.domain')
subscriber: Subscriber = listmonk.subscriber_by_id(2001)
subscriber: Subscriber = listmonk.subscriber_by_uuid('f6668cf0-1c...')
# Create a new subscriber
new_subscriber = listmonk.create_subscriber(
'testuser@some.domain', 'Jane Doe',
{1, 7, 9}, pre_confirm=True, attribs={...} )
# Change the email, custom rating, and add to lists 4 & 6, remove from 5.
subscriber.email = 'newemail@some.domain'
subscriber.attribs['rating'] = 7
subscriber = listmonk.update_subscriber(subscriber, {4, 6}, {5})
# Confirm single-opt-ins via the API (e.g. for when you manage that on your platform)
listmonk.confirm_optin(subscriber.uuid, the_list.uuid)
# Disable then re-enable a subscriber
subscriber = listmonk.disable_subscriber(subscriber)
subscriber = listmonk.enable_subscriber(subscriber)
# Block (unsubscribe) them
listmonk.block_subscriber(subscriber)
# Fully delete them from your system
listmonk.delete_subscriber(subscriber.email)
# Send an individual, transactional email (e.g. password reset)
to_email = 'testuser@some.domain'
from_email = 'app@your.domain'
template_id = 3 # *TX* template ID from listmonk
template_data = {'full_name': 'Test User', 'reset_code': 'abc123'}
status: bool = listmonk.send_transactional_email(
to_email, template_id, from_email=from_email,
template_data=template_data, content_type='html')
# You can also add one or multiple attachments with transactional mails
attachments = [
pathlib.Path("/path/to/your/file1.pdf"),
pathlib.Path("/path/to/your/file2.png")
]
status: bool = listmonk.send_transactional_email(
to_email,
template_id,
from_email=from_email,
template_data=template_data,
attachments=attachments,
content_type='html'
)
```
## Want to contribute?
PRs are welcome. But please open an issue first to see if the proposed feature fits with the direction of this library.
Enjoy.
Raw data
{
"_id": null,
"home_page": null,
"name": "listmonk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "api-client, email, marketing, newsletters",
"author": null,
"author_email": "Michael Kennedy <michael@talkpython.fm>",
"download_url": "https://files.pythonhosted.org/packages/96/7a/64836c3590281831e4d227dc22f8ffd94acdbd81f65176905f264ffcaf18/listmonk-0.1.8.tar.gz",
"platform": null,
"description": "# Listmonk Email App API Client for Python\n\nClient for the for open source, self-hosted [Listmonk email platform](https://listmonk.app) based on \n[httpx](https://www.python-httpx.org) and [pydantic](https://pydantic.dev). \n\n`listmonk` is intended for integrating your Listmonk instance into your web app. The [Listmonk API is extensive](https://listmonk.app/docs/apis/apis/) but this only covers the subset that most developers will need for common SaaS actions such as subscribe, unsubscribe, and segmentate users (into separate lists).\n\nSo while it doesn't currently cover every endpoint (for example you cannot create a list programatically nor can you edit HTML templates for campaigns over APIs) it will likely work for you. That said, PRs are weclome.\n\n\ud83d\udd00 Async is currently planned but not yet implemented. With the httpx-base, it should be trivial if needed.\n\n## Core Features\n\n* \u2795**Add a subscriber** to your subscribed users. \n* \ud83d\ude4e Get **subscriber details** by email, ID, UUID, and more.\n* \ud83d\udcdd **Modify subscriber details** (including custom attribute collection).\n* \ud83d\udd0d **Search** your users based on app and custom attributes.\n* \ud83c\udfe5 Check the **health and connectivity** of your instance.\n* \ud83d\udc65 Retrieve your **segmentation lists**, list details, and subscribers.\n* \ud83d\ude45 Unsubscribe and block users who don't want to be contacted further.\n* \ud83d\udca5 Completely delete a subscriber from your instance.\n* \ud83d\udce7 Send transactional email with template data (e.g. password reset emails).\n\n## Installation\n\nJust `pip install listmonk`\n\n\n## Usage\n\n```python\n\nimport pathlib\nimport listmonk\n\nlistmonk.set_url_base('https://yourlistmonkurl.com')\n\nlistmonk.login('sammy_z', '1234')\nvalid: bool = listmonk.verify_login()\n\n# Is it alive and working?\nup: bool = listmonk.is_healthy()\n\n# Read data about your lists\nlists: list[] = listmonk.lists()\nthe_list: MailingList = listmonk.list_by_id(list_id=7)\n\n# Various ways to access existing subscribers\nsubscribers: list[] = listmonk.subscribers(list_id=9)\n\nsubscriber: Subscriber = listmonk.subscriber_by_email('testuser@some.domain')\nsubscriber: Subscriber = listmonk.subscriber_by_id(2001)\nsubscriber: Subscriber = listmonk.subscriber_by_uuid('f6668cf0-1c...')\n\n# Create a new subscriber\nnew_subscriber = listmonk.create_subscriber(\n 'testuser@some.domain', 'Jane Doe',\n {1, 7, 9}, pre_confirm=True, attribs={...} )\n\n# Change the email, custom rating, and add to lists 4 & 6, remove from 5.\nsubscriber.email = 'newemail@some.domain'\nsubscriber.attribs['rating'] = 7\nsubscriber = listmonk.update_subscriber(subscriber, {4, 6}, {5})\n\n# Confirm single-opt-ins via the API (e.g. for when you manage that on your platform)\nlistmonk.confirm_optin(subscriber.uuid, the_list.uuid)\n\n# Disable then re-enable a subscriber\nsubscriber = listmonk.disable_subscriber(subscriber)\nsubscriber = listmonk.enable_subscriber(subscriber)\n\n# Block (unsubscribe) them\nlistmonk.block_subscriber(subscriber)\n\n# Fully delete them from your system\nlistmonk.delete_subscriber(subscriber.email)\n\n# Send an individual, transactional email (e.g. password reset)\nto_email = 'testuser@some.domain'\nfrom_email = 'app@your.domain'\ntemplate_id = 3 # *TX* template ID from listmonk\ntemplate_data = {'full_name': 'Test User', 'reset_code': 'abc123'}\n\nstatus: bool = listmonk.send_transactional_email(\n to_email, template_id, from_email=from_email, \n template_data=template_data, content_type='html')\n\n# You can also add one or multiple attachments with transactional mails\nattachments = [\n pathlib.Path(\"/path/to/your/file1.pdf\"),\n pathlib.Path(\"/path/to/your/file2.png\")\n]\n\nstatus: bool = listmonk.send_transactional_email(\n to_email,\n template_id,\n from_email=from_email,\n template_data=template_data,\n attachments=attachments,\n content_type='html'\n)\n```\n\n## Want to contribute?\n\nPRs are welcome. But please open an issue first to see if the proposed feature fits with the direction of this library.\n\nEnjoy.\n",
"bugtrack_url": null,
"license": null,
"summary": "Listmonk Email App API Client for Python",
"version": "0.1.8",
"project_urls": {
"Homepage": "https://github.com/mikeckennedy/listmonk",
"Source": "https://github.com/mikeckennedy/listmonk",
"Tracker": "https://github.com/mikeckennedy/listmonk/issues"
},
"split_keywords": [
"api-client",
" email",
" marketing",
" newsletters"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f1f0b736630a1d938de7f0150263c1d42ad407532062149c0bbf4582918cc174",
"md5": "80c5ed23545351a9ebab85237592c311",
"sha256": "d48009edf1233065881793d12889bbd22cc673145add96fd1145eff87aa08dee"
},
"downloads": -1,
"filename": "listmonk-0.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80c5ed23545351a9ebab85237592c311",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12186,
"upload_time": "2024-04-06T00:01:17",
"upload_time_iso_8601": "2024-04-06T00:01:17.460655Z",
"url": "https://files.pythonhosted.org/packages/f1/f0/b736630a1d938de7f0150263c1d42ad407532062149c0bbf4582918cc174/listmonk-0.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "967a64836c3590281831e4d227dc22f8ffd94acdbd81f65176905f264ffcaf18",
"md5": "48522816568af9cfa68977ea8866dce2",
"sha256": "f7727b4f716361deed7c4413410dcc8cb0ca199cc2bf61d5e2a2d6a31c268514"
},
"downloads": -1,
"filename": "listmonk-0.1.8.tar.gz",
"has_sig": false,
"md5_digest": "48522816568af9cfa68977ea8866dce2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11882,
"upload_time": "2024-04-06T00:01:15",
"upload_time_iso_8601": "2024-04-06T00:01:15.917610Z",
"url": "https://files.pythonhosted.org/packages/96/7a/64836c3590281831e4d227dc22f8ffd94acdbd81f65176905f264ffcaf18/listmonk-0.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-06 00:01:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mikeckennedy",
"github_project": "listmonk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "listmonk"
}
JSON
