added motre details and config examples for listmonk implementation #7

Author: bb-Ricardo

README.md

@@ -139,6 +139,82 @@ All options are described in the example file.
 After starting the API the first time it will add additional fields to each event.
 Such as a choice for the hosting Kennel or amount of Hash Cash.
 
+## Listmonk support to post event
+It is possible to post an event directly to via [Listmonk](https://github.com/knadh/listmonk) to a mailing list.
+
+### Requirements
+* a running listmonk instance
+* WordPress Advanced Custom Fields plugin
+* Wordpress WPCode Plugin
+
+First both WordPress plugins should be installed.
+
+Using the `Advanced Custom Fields` we add a new Field Group `Run Announcement`. There we add a new field `Mailing List`.
+* Type: Message
+* Label: Mailing List
+* Name: mailing_list
+* Message:
+```
+<div>
+<button
+    id="send-to-mailing-list-button"
+    type="button"
+    class="button-secondary send-to-mailing-list-button"
+    id="refresh-cache">Send/Update Event to Mailing List
+</button>
+</div>
+  ```
+
+In the bottom we can find `Settings`.
+* Rules:
+  1. Post Typ
+  2. is equal to
+  3. Event
+* Representation:
+  1. Style: Standard
+  2. Position: Side
+  3. Label Placement: Top
+  4. Instruction placement: Below
+  5. Order No: 2
+
+* Now press `Save Changes`
+
+After that we switch to the `WPCode` plugin and a Javascript function to this button we just created.
+Here we add a new `Send Mailinglist` code snippet of type `PHP Snipet` with this content:
+```php
+/* Inline script printed out in the header */
+add_action('admin_footer', 'tutsplus_add_script_wp_head');
+function tutsplus_add_script_wp_head() {
+    ?>
+		<script id="updateMailingList" type="text/javascript">
+			document.querySelector( '.send-to-mailing-list-button' ).addEventListener( 'click', function( e ) {
+				var xhttp = new XMLHttpRequest();
+				var params = {
+					user: "<?php echo get_current_user_id(); ?>",
+					token: "<?php echo wp_get_session_token(); ?>"
+				}
+
+				xhttp.onreadystatechange = function() {
+					if (this.readyState == 4 && this.status == 200) {
+					    console.log(this.responseText);
+					}
+				};
+
+			    xhttp.open("POST", "/api/v1/send-newsletter/<?php echo get_the_ID(); ?>" , true);
+				xhttp.setRequestHeader('Content-type', 'application/json')
+
+			    xhttp.send(JSON.stringify(params));
+				xhttp.onload = function() {
+                    // Do whatever with response
+                        alert("Mailing List request status: " + xhttp.responseText)
+                }
+
+			} );
+		</script>
+    <?php
+}
+```
+With Listmonk running on the same hos, sending an event via Mailing list is just a button press away.
 
 ## License
 >You can check out the full license [here](LICENSE.txt)

api/models/send_newsletter.py

@@ -8,10 +8,50 @@
 #  repository or visit: <https://opensource.org/licenses/MIT>.
 
 from pydantic.dataclasses import dataclass
+from typing import Any, Dict, List
+from pydantic import BaseModel
 
 
 @dataclass
 class SendNewsletterParams:
-
     user: int
     token: str
+
+
+class MailingListModel(BaseModel):
+    id: int
+    name: str
+
+
+class ListmonkReturnData(BaseModel):
+    id: int
+    created_at: str
+    updated_at: str
+    views: int
+    clicks: int
+    bounces: int
+    lists: List[MailingListModel]
+    started_at: Any
+    to_send: int
+    sent: int
+    uuid: str
+    type: str
+    name: str
+    subject: str
+    from_email: str
+    body: str
+    altbody: Any
+    send_at: Any
+    status: str
+    content_type: str
+    tags: List
+    headers: List
+    template_id: int
+    messenger: str
+    archive: bool
+    archive_template_id: int
+    archive_meta: Dict[str, Any]
+
+
+class ListmonkReturnDataList(BaseModel):
+    data: ListmonkReturnData

api/routers/send_newsletter.py

@@ -12,7 +12,7 @@
 from time import time
 
 from api.models.run import HashParams
-from api.models.send_newsletter import SendNewsletterParams
+from api.models.send_newsletter import SendNewsletterParams, ListmonkReturnDataList
 from api.models.exceptions import CredentialsInvalid
 from api.factory.runs import get_hash_runs
 from source.database import get_db_handler
@@ -30,7 +30,8 @@
 
 
 # noinspection PyShadowingBuiltins
-@newsletter.post("/{post_id}", summary="post run", description="post run via newsletter")
+@newsletter.post("/{post_id}", response_model=ListmonkReturnDataList, summary="post run",
+                 description="post run via newsletter")
 async def get_run(post_id: int, params: SendNewsletterParams):
     """
         To post/update a run to listmonk
@@ -127,12 +128,15 @@ async def get_run(post_id: int, params: SendNewsletterParams):
         "name": f"{subject_prefix}{event.event_name}",
         "subject": f"{subject_prefix}[{event.kennel_name}] Run #{event.run_number}, "
                    f"{event.start_date:%A %d %B %Y, %H:%M} @ {event.location_name}",
-        "lists": [listmonk_handler.config.list_id],
+        "lists": listmonk_handler.config.list_ids,
         "type": "regular",
         "content_type": "html",
         "body": campaign_body
     }
 
+    if listmonk_handler.config.campaign_template_id is not None:
+        campaign_data["template_id"] = listmonk_handler.config.campaign_template_id
+
     # create listmonk campaign
     campaign_result = listmonk_handler.add_campaign(campaign_data)
 
@@ -142,17 +146,18 @@ async def get_run(post_id: int, params: SendNewsletterParams):
     campaign_id = grab(campaign_result, "data.id")
 
     # send campaign
-    campaign_running_result = listmonk_handler.set_campaign_status(campaign_id, "running")
+    if listmonk_handler.config.send_campaign is True:
+        campaign_result = listmonk_handler.set_campaign_status(campaign_id, "running")
 
-    if campaign_running_result is None:
-        raise HTTPException(status_code=503, detail=f"Upstream request failed, unable to start campaign")
+        if campaign_result is None:
+            raise HTTPException(status_code=503, detail=f"Upstream request failed, unable to start campaign")
 
     # write campaign id to WP database
     if post_campaign_id is not None:
         db_handler.update_post_meta(post_id, "listmonk_campaign_id", campaign_id)
     else:
         db_handler.add_post_meta(post_id, "listmonk_campaign_id", campaign_id)
 
-    return {"status": "ok"}
+    return ListmonkReturnDataList(**campaign_result)
 
 # EOF

config-example.ini

@@ -94,6 +94,38 @@ hash_kennels = Nerd H3, Nerd Full Moon H3
 # add the FaceBook group ID here. This ID will be added to each run.
 #default_facebook_group_id =
 
+###
+### [listmonk]
+###
+### settings to connect to listmonk to prepare/send newsletter campaign
+###
+
+[listmonk]
+
+# Setting this option to true enables the listmonk integration
+#enabled = false
+
+# defines if the campaign should be sent out immediately after it got created
+#send_campaign = false
+
+# defines the admin credentials in order to connect to the listmonk API
+#username =
+#password =
+
+# defines the listmonk host name to connect to
+#host = list.example.com
+
+# The id of the campaign template to use, if empty the default template is used
+#campaign_template_id =
+
+# The id of the template to use which then is posted as content to the campaign
+#body_template_id =
+
+# the id or ids of the list to send this campaign to
+#list_ids =
+
+[database]
+
 
 ###
 ### [database]

config/models/listmonk.py

@@ -8,15 +8,28 @@
 #  repository or visit: <https://opensource.org/licenses/MIT>.
 
 from config.models import EnvOverridesBaseSettings
+from pydantic import validator
 
 
+# noinspection PyMethodParameters
 class ListMonkSettings(EnvOverridesBaseSettings):
     enabled: bool = False
+    send_campaign: bool = False
     username: str
     password: str
     host: str
+    campaign_template_id: int = None
     body_template_id: int
-    list_id: int
+    list_ids: str
 
     class Config:
         env_prefix = f"{__name__.split('.')[-1]}_"
+
+    @validator("list_ids")
+    def split_list_ids(cls, value):
+        if isinstance(value, str):
+            try:
+                value = [int(x) for x in value.split(",")]
+            except Exception as e:
+                raise ValueError(f"unable to pars '{value}' into list of ints: {e}")
+        return value

requirements.txt

@@ -7,3 +7,4 @@ pytz==2021.3
 phpserialize==1.3
 mysql-connector==2.2.9
 psutil==5.9.0
+requests==2.28.2