AI Membership Assistant

This is a Streamlit-based application designed to assist with managing Mailchimp subscriber lists, analyzing click activity on Wordpress posts via the newsletter, and generating personalized fundraising emails based on member click behavior.

It is a work in progress built at Cityside Journalism for the goal of prototyping a solution to obtain more revenue from Mailchimp newsletter subscribers.

Core functionality

Sync newsletter audience members and generate emails based on their headline click activity on newsletters linked to Wordpress posts.

Features

• Authentication: Secure login to access the application.
• Newsletter Management: Add and view newsletters, sync subscribers from Mailchimp.
• Click Activity Analysis: Fetch and analyze click activity from newsletters.
• AI Click Analyzer: Generate personalized marketing emails based on member click activity using OpenAI.
• Member Data: Fetch and display subscriber data based on various criteria.

Prereqs

• Mailchimp subscribers lists and campaigns to fetch.
• A live Wordpress site with active posts inlcuded in the newsletters.
• A valid Mailchip API key
• A Supabase account and API key
• A valid OpenAI API key (for generating emails)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/membership-helper.git
   cd membership-helper

2. Create a virtual environment and activate it:

   python -m venv .venv
   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

3. Install the required packages:

   pip install -r requirements.txt

4. Set up Streamlit secrets:

   • Create a secrets.toml file in the .streamlit directory with the following content:

   [auth]
   username = "your_username"
   password = "your_password"
   
   API_KEY = "your_mailchimp_api_key"
   MC_KEY = "your_mailchimp_marketing_key"
   OPEN_AI_KEY = "your_openai_api_key"
   SB_URL = "your_supabase_url"
   SB_KEY = "your_supabase_key"

5. Find your Newsletter IDs from your Mailchimp account (10 character alphanumeric)

6. Get your Wordpress site URL for the WP API to fetch headlines from slugs. For example: https://richmondside.org/wp-json/wp/v2/posts?slug=

7. Create Supabase account and project and structure your tables as shown below:

Supabase Schema

The Supabase database schema consists of the following three tables:

1. subscribers: Stores subscriber information.

   • id: Unique identifier for the subscriber.
   • email: Email address of the subscriber.
   • name: Name of the subscriber.
   • status: Subscription status (e.g., subscribed, unsubscribed).

2. click_activity: Stores click activity data for subscribers.

   • id: Unique identifier for the click activity.
   • subscriber_id: Foreign key referencing the subscriber.
   • newsletter_id: Foreign key referencing the newsletter.
   • click_time: Timestamp of the click activity.
   • url: URL that was clicked.

3. newsletters: Stores information about newsletters.

   • id: Unique identifier for the newsletter.
   • title: Title of the newsletter.
   • content: Content of the newsletter.
   • sent_date: Date when the newsletter was sent.

Usage

1. Run the Streamlit application:

   streamlit run app.py

2. Open your web browser and navigate to http://localhost:8080.

File Descriptions

• app.py: Main entry point of the application.
• chimp/: Contains modules for interacting with Mailchimp.
  • member_clicks.py: Fetches member activity from Mailchimp.
  • newsletters.py: Manages newsletters and subscribers.
  • subscriber_sync.py: Syncs subscribers from Mailchimp.
• pages/: Contains Streamlit pages for different functionalities.
  • ai_click_analyzer.py: Generates personalized marketing emails.
  • click_activity.py: Analyzes click activity from newsletters.
  • login.py: Handles user authentication.
  • manage_newsletters.py: Manages newsletters.
  • member_data.py: Displays subscriber data.
• prompts/: Contains prompt templates for generating emails.
  • test_gen_funraising.py: Templates for fundraising emails.
• db.py: Contains database interaction logic using Supabase.
• email_generator.py: Generates personalized emails using OpenAI.
• tasks.py: Contains background tasks for processing click activity.
• utils.py: Utility functions for URL parsing and data cleaning.
• requirements.txt: Lists the required Python packages.
• README.md: This file.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.

License

This project is licensed under the MIT License.