6.4 KiB
birthdaymessaging
Overview
The Birthday Messaging Intelligence Platform is a data-driven engagement system designed to transform static birthday campaigns into an intelligent engagement engine.
The system integrates CRM data, behavioral interaction logs, and predictive analytics to automatically identify high-value engagement opportunities, detect churn risk, and orchestrate personalized birthday messaging campaigns.
The platform evolves through three stages:
Stage Description Week 2 Data pipeline and engagement preparation Week 3 Predictive intelligence and behavioral segmentation Future Multi-channel automation and campaign optimization
The end result is a system that predicts disengagement before it happens and activates personalized engagement campaigns.
System Architecture
The project is organized into modular components following a data pipeline → intelligence → automation architecture.
CRM Data + Clickstream Logs │ ▼ Unified Data Pipeline │ ▼ Data Cleaning & Compliance │ ▼ Engagement Intelligence │ ▼ Churn Prediction │ ▼ Predictive Segmentation │ ▼ Automation Triggers Project Structure birthdaymessaging/ │ ├── config.yaml ├── main.py ├── README.md │ ├── data/ │ ├── raw/ │ └── processed/ │ ├── docs/ │ ├── ethics.md │ └── model-audits/ │ ├── src/ │ ├── pipeline/ # Week 2 Data Engineering │ │ ├── unified_stream.py │ │ ├── relative_date_trigger.py │ │ ├── rf_scoring.py │ │ ├── list_hygiene.py │ │ ├── ethics_flags.py │ │ ├── deliverability_check.py │ │ └── config_loader.py │ │ │ ├── models/ # Week 3 Intelligence Layer │ │ ├── engagement_scoring.py │ │ ├── churn_classifier.py │ │ └── send_time_optimizer.py │ │ │ ├── segmentation/ │ │ └── predictive_segments.py │ │ │ └── automation/ │ ├── trigger_engine.py │ └── reactivation_triggers.yaml Week 2: Data Engineering Pipeline
Week 2 focuses on building a clean, compliant data foundation.
Unified Data Stream
File:
src/pipeline/unified_stream.py
Functions:
Load CRM dataset
Load clickstream activity logs
Pseudonymize user identifiers
Merge datasets
Normalize timestamps (UTC)
Output:
unified_dataset.csv Birthday Recursion Trigger
File:
relative_date_trigger.py
Implements recurring campaign triggers such as:
Birthday approaching
Pre-birthday reminder
Post-birthday follow-up
Ensures contacts re-enter the workflow annually.
Recency-Frequency Scoring
File:
rf_scoring.py
Calculates engagement indicators:
Recency index
Frequency of sessions
Session change delta
Used as an early engagement signal.
List Hygiene Automation
File:
list_hygiene.py
Improves deliverability by removing:
Invalid email domains
Disposable email services
Role-based addresses
Ethics and Compliance Layer
File:
ethics_flags.py
Detects sensitive data usage:
medical_condition
political_opinion
dietary_restrictions
Ensures compliance with GDPR principles.
Deliverability Simulation
File:
deliverability_check.py
Simulates email infrastructure readiness:
SPF validation
DKIM compatibility
DMARC enforcement
inactive contact suppression
Week 3: Engagement Intelligence Engine
Week 3 converts the pipeline into a predictive analytics platform.
Engagement Scoring Engine
File:
src/models/engagement_scoring.py
Calculates a normalized engagement score (0–100) based on:
Recency of interaction
Session frequency
Session duration
Click engagement depth
Formula:
Engagement Score = (Recency Weight × Normalized Recency)
- (Frequency Weight × Session Count)
- (Engagement Depth Weight × Interaction Index)
Output classification:
Score Tier 75–100 Highly Engaged 50–74 Stable 25–49 Declining 0–24 At Risk Churn Risk Classification
File:
src/models/churn_classifier.py
Defines churn risk using behavioral signals.
Conditions:
No login ≥ X days AND Engagement score drop ≥ Y%
Risk categories:
Risk Level Description Low Healthy engagement Medium Engagement declining High High probability of churn
Output fields:
churn_risk_flag churn_probability_score risk_class Predictive Segmentation
File:
src/segmentation/predictive_segments.py
Creates behavioral marketing segments using:
Lifecycle Stage Engagement Tier Birthday Proximity Churn Risk Overlay
Example segment:
At-Risk + Birthday Approaching Send-Time Optimization
File:
src/models/send_time_optimizer.py
Analyzes historical open patterns and determines optimal send windows.
Outputs:
optimal_send_hour optimal_send_day Automation Triggers
File:
src/automation/reactivation_triggers.yaml
Defines campaign orchestration rules.
Example:
IF churn_risk_flag = True AND birthday_within_30_days = True
THEN send reminder email WAIT 24h IF unopened → send SMS Model Governance & Ethics
Documentation:
docs/model-audits/week3-bias-review.md docs/ethics.md
Audits include:
Geographic bias
Age-based performance variance
False-positive churn classification
Transparency measures include clear documentation of automated decision logic.
Running the Pipeline
Run the full pipeline:
python main.py
Pipeline order:
Week 2: Data Merge Birthday Triggers RF Scoring List Hygiene Ethics Checks Deliverability Simulation
Week 3: Engagement Scoring Churn Classification Predictive Segmentation Send-Time Optimization
Final dataset:
data/processed/final_intelligence_output.csv Success Criteria
The system is considered operational when:
Engagement scores generated for all active users
Churn risk classification validated
Predictive segments documented
Reactivation triggers tested
Send-time optimization operational
Ethics documentation updated
Bias audit completed
Outcome
At completion, the platform functions as an Engagement Intelligence Engine.
Capabilities include:
Predicting disengagement
Prioritizing high-value users
Automating reactivation campaigns
Personalizing birthday marketing
Ensuring ethical data usage
The platform transforms traditional birthday messaging into a behaviorally intelligent engagement strategy.