claude-plugin-wordpress-manager 2.3.1 → 2.6.0

package/skills/wp-social-email/references/audience-segmentation.md

@@ -0,0 +1,173 @@
+# Audience Segmentation
+
+## Overview
+
+Audience segmentation divides your subscriber base into targeted groups for more relevant messaging. Effective segmentation improves open rates, click rates, and reduces unsubscribes. This reference covers segmentation strategies across Mailchimp, SendGrid, and Buffer.
+
+## Mailchimp List Segmentation
+
+### Segment by subscriber data
+
+Mailchimp segments are dynamic filters applied to an audience. Subscribers matching the criteria are automatically included.
+
+```
+Tool: mc_get_audience_members
+Params:
+  audience_id: "abc123def4"
+  status: "subscribed"
+  # Filter by merge fields, tags, or activity in the Mailchimp UI
+```
+
+### Tag-based segmentation
+
+Tags are the most flexible segmentation method via the API:
+
+```
+Tool: mc_add_subscriber
+Params:
+  audience_id: "abc123def4"
+  email: "user@example.com"
+  tags: ["wordpress-user", "product-interest-seo", "signup-2026-q1"]
+```
+
+### Common Mailchimp segments
+
+| Segment | Criteria | Use Case |
+|---------|----------|----------|
+| New subscribers | Signup date < 30 days | Welcome series, onboarding |
+| Engaged readers | Opened last 3 campaigns | Premium content, surveys |
+| Inactive | Not opened in 90 days | Re-engagement campaign |
+| Product interest | Tagged by category | Targeted product launches |
+| High-value | Purchase history > $100 | VIP offers, early access |
+| Location-based | Merge field `COUNTRY` | Localized content, events |
+
+### Merge fields for segmentation
+
+Define custom merge fields to capture WordPress user data:
+
+| Merge Tag | Type | WordPress Source |
+|-----------|------|-----------------|
+| `FNAME` | Text | `user.first_name` |
+| `LNAME` | Text | `user.last_name` |
+| `WP_ROLE` | Text | `user.role` (subscriber, customer, etc.) |
+| `SIGNUP_SRC` | Text | Registration source (blog, checkout, popup) |
+| `LAST_ORDER` | Date | Most recent WooCommerce order date |
+| `ORDER_TOTAL` | Number | Lifetime order value |
+
+## SendGrid Contact Segmentation
+
+### Contact lists
+
+SendGrid uses contact lists for static segmentation:
+
+```
+Tool: sg_add_contacts
+Params:
+  list_ids: ["list_new_users", "list_blog_subscribers"]
+  contacts:
+    - email: "user@example.com"
+      first_name: "Jane"
+      custom_fields:
+        signup_source: "blog_popup"
+        wp_user_id: "42"
+```
+
+### Custom fields
+
+Define custom fields in SendGrid to mirror WordPress user data:
+
+| Field Name | Type | Purpose |
+|------------|------|---------|
+| `wp_user_id` | Number | Link to WordPress user record |
+| `signup_source` | Text | Track acquisition channel |
+| `user_role` | Text | WordPress role for permission-based content |
+| `last_purchase_date` | Date | Trigger post-purchase sequences |
+| `content_preference` | Text | Category interest for targeted notifications |
+
+### SGQL queries for segmentation
+
+```
+Tool: sg_list_contacts
+Params:
+  query: "signup_source = 'blog_popup' AND last_purchase_date IS NULL"
+```
+
+Common SGQL patterns:
+
+| Query | Segment |
+|-------|---------|
+| `signup_source = 'checkout'` | Customers who bought |
+| `last_purchase_date < '2026-01-01'` | Lapsed customers |
+| `user_role = 'subscriber'` | Blog-only subscribers |
+| `content_preference = 'tutorials'` | Tutorial readers |
+
+## Buffer Profile-Based Targeting
+
+Buffer segments audiences by social profile rather than individual users. Each profile reaches a different audience.
+
+### Profile selection strategy
+
+| Profile | Audience Type | Content Style |
+|---------|--------------|---------------|
+| Twitter/X | Tech-savvy, real-time | Short, punchy, hashtags |
+| LinkedIn | Professional, B2B | Thought leadership, data-driven |
+| Facebook | Broad, community | Storytelling, engagement prompts |
+| Instagram | Visual-first, younger | Image-heavy, lifestyle |
+
+### Targeting by profile
+
+```
+Tool: buf_create_update
+Params:
+  profile_ids: ["linkedin_id"]    # Only post to LinkedIn for B2B content
+  text: "Our latest research on WordPress performance..."
+```
+
+Select profiles based on content type:
+- **Product launches**: All profiles
+- **Technical tutorials**: Twitter + LinkedIn
+- **Behind-the-scenes**: Instagram + Facebook
+- **Industry news**: Twitter + LinkedIn
+
+## Building Personas from WordPress Data
+
+### Data sources for persona building
+
+| Source | Data | Tool |
+|--------|------|------|
+| WordPress users | Role, registration date, profile fields | `wp_list_users` |
+| WooCommerce orders | Purchase history, AOV, frequency | `wc_list_orders` |
+| Post analytics | Most-read categories, time on page | Site analytics |
+| Form submissions | Stated interests, preferences | Contact form data |
+
+### Persona-to-segment mapping
+
+| Persona | Characteristics | Mailchimp Tags | SendGrid Lists |
+|---------|----------------|----------------|----------------|
+| New Visitor | First 30 days, no purchase | `new-visitor` | `list_onboarding` |
+| Blog Reader | Regular reader, no purchase | `blog-reader`, category tags | `list_blog` |
+| First Buyer | 1 order, < $50 | `first-buyer` | `list_customers` |
+| Loyal Customer | 3+ orders, > $200 | `loyal-customer`, `vip` | `list_vip` |
+| Churning | No activity 60+ days | `at-risk` | `list_reengagement` |
+
+### Sync WordPress users to segments
+
+Workflow to keep segments current:
+
+```
+1. wp_list_users → fetch all users with roles and metadata
+2. For each user, determine persona based on rules
+3. mc_add_subscriber → set tags matching persona
+4. sg_add_contacts → add to appropriate contact lists
+5. Schedule weekly sync to update segment membership
+```
+
+## Best Practices
+
+- **Start simple**: Begin with 3-4 segments (new, active, inactive, customer); add granularity as data grows
+- **Dynamic over static**: Prefer Mailchimp tag-based segments that update automatically over manually managed lists
+- **Consistent field naming**: Use the same custom field names across Mailchimp and SendGrid for easier cross-channel management
+- **Hygiene**: Remove hard bounces and unsubscribes from all platforms; sync removals across services
+- **Privacy compliance**: Honor opt-out preferences across all channels; never re-add unsubscribed contacts
+- **Test segments**: Before sending a campaign to a new segment, verify member count and sample members for accuracy
+- **Document segments**: Maintain a segment registry with criteria, purpose, and last review date

package/skills/wp-social-email/references/buffer-social-publishing.md

@@ -0,0 +1,124 @@
+# Buffer Social Publishing
+
+## Overview
+
+Buffer is a social media scheduling platform that manages posting across Twitter/X, Facebook, Instagram, LinkedIn, and other channels. The WP REST Bridge provides 5 MCP tools (`buf_*`) for creating posts, managing queues, and retrieving analytics.
+
+## Setup
+
+### Access Token Configuration
+
+Add Buffer credentials to `WP_SITES_CONFIG`:
+
+```json
+{
+  "sites": [{
+    "name": "my-site",
+    "url": "https://example.com",
+    "distribution": {
+      "buffer": {
+        "access_token": "1/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }]
+}
+```
+
+Obtain the access token from Buffer's developer portal (Settings → Apps → Access Token).
+
+## Profile Management
+
+### List connected profiles
+
+```
+Tool: buf_list_profiles
+Returns: Array of profiles with id, service (twitter, facebook, etc.),
+         formatted_username, avatar, schedules, counts
+```
+
+Each profile represents a connected social account. A single Buffer account may have multiple profiles (e.g., @company on Twitter + Company Page on Facebook).
+
+## Post Creation
+
+### Create a social post
+
+```
+Tool: buf_create_update
+Params:
+  profile_ids: ["profile_abc123"]
+  text: "New blog post: 10 Tips for Better SEO — Read more at https://example.com/seo-tips"
+  scheduled_at: "2026-03-15T14:00:00Z"   # Optional: omit for immediate queue
+```
+
+### Create a post with media
+
+```
+Tool: buf_create_update
+Params:
+  profile_ids: ["profile_abc123", "profile_def456"]
+  text: "Check out our latest product launch!"
+  media:
+    photo: "https://example.com/wp-content/uploads/2026/03/product-launch.jpg"
+    thumbnail: "https://example.com/wp-content/uploads/2026/03/product-launch-thumb.jpg"
+```
+
+### Post to multiple profiles
+
+Pass an array of `profile_ids` to publish the same content across channels simultaneously. Buffer adapts character limits per platform.
+
+```
+Tool: buf_create_update
+Params:
+  profile_ids: ["twitter_id", "facebook_id", "linkedin_id"]
+  text: "We just published a comprehensive guide to WordPress performance optimization."
+```
+
+## Queue Management
+
+### List pending posts
+
+```
+Tool: buf_list_pending
+Params:
+  profile_id: "profile_abc123"
+Returns: Array of queued posts with id, text, scheduled_at, media
+```
+
+### List sent posts
+
+```
+Tool: buf_list_sent
+Params:
+  profile_id: "profile_abc123"
+  count: 20
+  page: 1
+Returns: Array of published posts with engagement metrics
+```
+
+## WordPress-to-Buffer Workflow
+
+Typical flow for distributing a WordPress post to social media:
+
+1. **Fetch the post** using `wp_get_post` to get title, excerpt, permalink, featured image
+2. **Format for social**: Compose text from post title + excerpt (truncated to platform limits)
+3. **Attach media**: Use the featured image URL as the `media.photo` parameter
+4. **Schedule**: Set `scheduled_at` for optimal posting time or omit for queue placement
+5. **Post to profiles**: Select target profiles and call `buf_create_update`
+
+```
+# Example: Blog post → Twitter + LinkedIn
+Step 1: wp_get_post id=42 → { title, excerpt, link, featured_media_url }
+Step 2: Compose text = "📝 {title}\n\n{excerpt}\n\nRead more: {link}"
+Step 3: buf_create_update profile_ids=[twitter, linkedin] text=... media.photo={featured_media_url}
+```
+
+## Best Practices
+
+- **Optimal posting times**: Analyze `buf_get_analytics` to identify when your audience is most active; schedule posts during those windows
+- **Platform-specific formatting**: Twitter has 280 chars; LinkedIn allows 3000; tailor text length per profile rather than using identical copy
+- **Hashtag strategy**: Use 1-2 relevant hashtags on Twitter, 3-5 on LinkedIn; avoid hashtags on Facebook
+- **Image dimensions**: Use 1200x628px for link previews, 1080x1080px for square posts; Buffer will resize but starting with correct dimensions avoids cropping
+- **Queue spacing**: Buffer's default schedule spaces posts throughout the day; avoid overriding with manual times unless needed
+- **Evergreen content**: Re-queue high-performing posts using `buf_list_sent` to identify top performers, then `buf_create_update` to re-share
+- **UTM parameters**: Append `?utm_source=buffer&utm_medium=social&utm_campaign={campaign}` to URLs for tracking in Google Analytics
+- **Avoid duplicate content**: Check `buf_list_pending` before creating new posts to prevent queue duplication

package/skills/wp-social-email/references/content-to-distribution.md

@@ -0,0 +1,156 @@
+# Content-to-Distribution Workflow
+
+## Overview
+
+The content-to-distribution pipeline transforms WordPress content into format-appropriate messages for email and social channels. This reference covers the full workflow: fetching content, adapting it per channel, scheduling distribution, and orchestrating multi-channel campaigns.
+
+## WordPress-to-Channel Pipeline
+
+### Core flow
+
+```
+WordPress Post → Fetch Content → Adapt Format → Distribute
+                 (wp_get_post)   (per channel)   (mc_*/buf_*/sg_*)
+```
+
+### Step 1: Fetch the source content
+
+```
+Tool: wp_get_post
+Params:
+  id: 42
+  _embed: true    # Include featured image, author, categories
+Returns:
+  title, excerpt, content (HTML), permalink, featured_media_url,
+  author, categories, tags, date
+```
+
+### Step 2: Adapt for each channel
+
+The same post requires different formatting per distribution target.
+
+### Step 3: Distribute via service tools
+
+Route the adapted content to the appropriate MCP tool.
+
+## Content Adaptation Per Channel
+
+### Blog → Newsletter (Mailchimp)
+
+| Element | Adaptation |
+|---------|------------|
+| Title | Campaign subject line (max 150 chars, add emoji or personalization) |
+| Excerpt | Preview text (max 200 chars) |
+| Content | Full HTML body, reformatted for email (inline CSS, max 600px width) |
+| Featured image | Hero image at top of email (600px wide) |
+| CTA | "Read the full post" button linking to permalink |
+
+```
+1. wp_get_post → extract title, content, featured_image
+2. mc_create_campaign → subject = post title, from_name = site name
+3. mc_set_campaign_content → html = email-formatted post content
+4. mc_send_campaign → deliver or schedule
+```
+
+### Blog → Social Post (Buffer)
+
+| Platform | Adaptation |
+|----------|------------|
+| Twitter/X | Title + shortened excerpt (max 250 chars with URL) |
+| LinkedIn | Title + full excerpt + 3-5 hashtags (max 700 chars) |
+| Facebook | Title + excerpt + URL (no character pressure) |
+| Instagram | Excerpt + 10-15 hashtags (image required) |
+
+```
+1. wp_get_post → extract title, excerpt, permalink, featured_image
+2. Compose platform-specific text variants
+3. buf_create_update → text, media.photo, profile_ids, scheduled_at
+```
+
+### Blog → Transactional Notification (SendGrid)
+
+For notifying specific users about relevant new content:
+
+```
+1. wp_get_post → extract title, excerpt, permalink
+2. sg_list_contacts → find users matching content category
+3. sg_send_email → template with post title, excerpt, read-more link
+```
+
+## Scheduling Strategies
+
+### Immediate distribution
+
+Publish to all channels as soon as the WordPress post goes live. Best for breaking news or time-sensitive content.
+
+```
+1. WordPress publish event triggers distribution
+2. mc_send_campaign (send now)
+3. buf_create_update (no scheduled_at → immediate queue)
+4. sg_send_email (immediate delivery)
+```
+
+### Staggered distribution
+
+Spread distribution across hours or days to maximize reach across time zones and channel algorithms.
+
+```
+Day 0, Hour 0:  Blog post published
+Day 0, Hour 1:  buf_create_update → Twitter (immediate engagement)
+Day 0, Hour 4:  buf_create_update → LinkedIn (business hours)
+Day 1, Hour 10: mc_send_campaign → Newsletter (Tuesday 10am optimal)
+Day 3:          buf_create_update → Facebook (extend reach)
+Day 7:          sg_send_email → Re-engagement for non-openers
+```
+
+### Evergreen rotation
+
+Re-distribute high-performing content on a recurring schedule:
+
+```
+1. buf_list_sent → identify posts with highest engagement
+2. Filter for content older than 30 days (avoid fatigue)
+3. buf_create_update → re-share with updated text
+4. Track performance to retire content below threshold
+```
+
+## Multi-Channel Distribution Workflow
+
+### Full orchestration example
+
+Distribute a new blog post across all three services:
+
+```
+# 1. Fetch source content
+wp_get_post id=42 → { title, excerpt, content, permalink, featured_image }
+
+# 2. Email campaign (Mailchimp)
+mc_create_campaign type="regular" audience_id=... subject="{title}"
+mc_set_campaign_content campaign_id=... html="{formatted_content}"
+mc_send_campaign campaign_id=... schedule_time="2026-03-15T10:00:00Z"
+
+# 3. Social posts (Buffer)
+buf_create_update profile_ids=[twitter] text="{short_text}" media.photo="{featured_image}"
+buf_create_update profile_ids=[linkedin] text="{long_text}" scheduled_at="2026-03-15T14:00:00Z"
+
+# 4. Notification email (SendGrid)
+sg_send_email to="vip-subscribers" template_id="d-newpost" dynamic_template_data={title, excerpt, permalink}
+```
+
+### Coordination checklist
+
+- [ ] Source content finalized and published on WordPress
+- [ ] Email campaign created and content set (Mailchimp)
+- [ ] Social posts queued for each target profile (Buffer)
+- [ ] Transactional notifications sent to relevant user segments (SendGrid)
+- [ ] UTM parameters appended to all outbound URLs
+- [ ] Analytics tracking confirmed for each channel
+
+## Best Practices
+
+- **Single source of truth**: Always fetch content from WordPress (`wp_get_post`) rather than duplicating content manually
+- **URL tracking**: Append UTM parameters per channel (`utm_source=mailchimp`, `utm_source=buffer`, `utm_source=sendgrid`)
+- **Content freshness**: Verify post status is `publish` before distributing; draft content should never reach channels
+- **Error handling**: If one channel fails, proceed with others; log failures and retry individually
+- **Preview before send**: Use Mailchimp preview and Buffer draft features to review formatting before live distribution
+- **Audience overlap**: Be mindful that users may follow multiple channels; vary the messaging slightly to avoid fatigue

package/skills/wp-social-email/references/distribution-analytics.md

@@ -0,0 +1,208 @@
+# Distribution Analytics
+
+## Overview
+
+Distribution analytics measure the effectiveness of content distributed across email (Mailchimp, SendGrid) and social (Buffer) channels. Tracking performance per channel enables data-driven decisions on content strategy, send timing, and audience targeting.
+
+## Mailchimp Campaign Reports
+
+### Get campaign performance
+
+```
+Tool: mc_get_campaign_report
+Params:
+  campaign_id: "campaign_xyz"
+Returns:
+  emails_sent: 1250
+  opens:
+    total: 487
+    unique: 412
+    rate: 0.33
+  clicks:
+    total: 98
+    unique: 76
+    rate: 0.061
+  bounces:
+    hard: 3
+    soft: 12
+  unsubscribes: 2
+  forwards: 5
+  abuse_reports: 0
+```
+
+### Key Mailchimp metrics
+
+| Metric | Calculation | Benchmark |
+|--------|-------------|-----------|
+| Open rate | Unique opens / Delivered | 20-25% |
+| Click rate | Unique clicks / Delivered | 2.5-5% |
+| Click-to-open rate | Unique clicks / Unique opens | 10-15% |
+| Bounce rate | (Hard + Soft bounces) / Sent | < 2% |
+| Unsubscribe rate | Unsubscribes / Delivered | < 0.5% |
+| List growth rate | (New - Unsubscribes) / Total | > 2% monthly |
+
+### Analyzing campaign trends
+
+Compare multiple campaigns to identify patterns:
+
+```
+# Fetch reports for recent campaigns
+mc_get_campaign_report campaign_id="campaign_1" → { open_rate: 0.28, click_rate: 0.04 }
+mc_get_campaign_report campaign_id="campaign_2" → { open_rate: 0.35, click_rate: 0.07 }
+mc_get_campaign_report campaign_id="campaign_3" → { open_rate: 0.22, click_rate: 0.03 }
+
+# Campaign 2 outperformed — analyze: subject line? send time? content type?
+```
+
+## Buffer Analytics
+
+### Get social profile analytics
+
+```
+Tool: buf_get_analytics
+Params:
+  profile_id: "profile_abc123"
+Returns:
+  posts_count: 45
+  total_reach: 12500
+  total_engagement: 890
+  total_clicks: 234
+  per_post_average:
+    reach: 278
+    engagement: 19.8
+    clicks: 5.2
+```
+
+### Key Buffer metrics
+
+| Metric | Description | Benchmark |
+|--------|-------------|-----------|
+| Reach | Number of unique users who saw the post | Varies by platform |
+| Engagement | Likes + comments + shares + retweets | 1-3% of reach |
+| Engagement rate | Engagement / Reach | 1-5% (varies by platform) |
+| Clicks | Link clicks from post | 0.5-2% of reach |
+| Click-through rate | Clicks / Reach | 1-3% |
+| Best time to post | Time slot with highest engagement | Platform-specific |
+
+### Identifying top-performing content
+
+```
+Tool: buf_list_sent
+Params:
+  profile_id: "profile_abc123"
+  count: 50
+
+# Sort results by engagement metrics to find top performers
+# Re-share top content using buf_create_update with updated text
+```
+
+## SendGrid Statistics
+
+### Get email delivery stats
+
+```
+Tool: sg_get_stats
+Params:
+  start_date: "2026-03-01"
+  end_date: "2026-03-15"
+Returns:
+  - date: "2026-03-01"
+    metrics:
+      requests: 150
+      delivered: 148
+      opens: 52
+      unique_opens: 45
+      clicks: 12
+      unique_clicks: 10
+      bounces: 2
+      spam_reports: 0
+      blocks: 0
+```
+
+### Key SendGrid metrics
+
+| Metric | Calculation | Benchmark |
+|--------|-------------|-----------|
+| Delivery rate | Delivered / Requests | > 95% |
+| Open rate | Unique opens / Delivered | 15-25% (transactional: 40-60%) |
+| Click rate | Unique clicks / Delivered | 2-5% |
+| Bounce rate | Bounces / Requests | < 3% |
+| Spam complaint rate | Spam reports / Delivered | < 0.1% |
+| Block rate | Blocks / Requests | < 1% |
+
+### Transactional vs marketing benchmarks
+
+Transactional emails (welcome, order confirmation) consistently outperform marketing emails:
+
+| Type | Open Rate | Click Rate |
+|------|-----------|------------|
+| Transactional | 40-60% | 10-20% |
+| Marketing | 15-25% | 2-5% |
+
+## Cross-Channel Performance Comparison
+
+### Unified metrics dashboard
+
+Build a cross-channel view by combining data from all three services:
+
+```
+# Email (Mailchimp campaigns)
+mc_get_campaign_report → opens, clicks, unsubscribes
+
+# Social (Buffer)
+buf_get_analytics → reach, engagement, clicks
+
+# Transactional (SendGrid)
+sg_get_stats → deliveries, opens, clicks
+```
+
+### Channel comparison table
+
+| Channel | Reach | Engagement Rate | Click Rate | Cost per Click |
+|---------|-------|-----------------|------------|----------------|
+| Email (Mailchimp) | Audience size | Open rate 20-25% | 2.5-5% | Low |
+| Social (Buffer) | Follower count + viral | 1-5% | 0.5-2% | Free (organic) |
+| Transactional (SendGrid) | Per-event | 40-60% open | 10-20% | Per email |
+
+### Attribution tracking
+
+Use UTM parameters to track which channel drives conversions in WordPress/WooCommerce:
+
+| Channel | UTM Source | UTM Medium | UTM Campaign |
+|---------|-----------|------------|--------------|
+| Mailchimp | `mailchimp` | `email` | `{campaign_name}` |
+| Buffer | `buffer` | `social` | `{post_slug}` |
+| SendGrid | `sendgrid` | `email` | `{template_name}` |
+
+## KPIs and Benchmarks
+
+### Weekly KPIs to track
+
+| KPI | Target | Tool |
+|-----|--------|------|
+| Email open rate | > 22% | `mc_get_campaign_report` |
+| Email click rate | > 3% | `mc_get_campaign_report` |
+| Social engagement rate | > 2% | `buf_get_analytics` |
+| Email delivery rate | > 95% | `sg_get_stats` |
+| List growth (net) | > 50/week | `mc_get_audience_members` count delta |
+| Content distributed | 3+ posts/week | Track distribution events |
+
+### Red flags requiring action
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| Open rate drop | < 15% | Review subject lines, check deliverability |
+| High unsubscribe rate | > 0.5% | Reduce frequency, improve segmentation |
+| Bounce rate spike | > 5% | Clean list, verify new signups |
+| Spam complaints | > 0.1% | Review content, check opt-in process |
+| Social engagement decline | < 0.5% | Refresh content format, test new posting times |
+| Delivery blocks | > 1% | Check domain reputation, review SPF/DKIM |
+
+## Best Practices
+
+- **Weekly review cadence**: Pull analytics every Monday; compare to previous week and 4-week average
+- **A/B test systematically**: Test one variable at a time (subject line, send time, content format) and track results in `mc_get_campaign_report`
+- **Channel-specific goals**: Email optimizes for clicks; social optimizes for engagement; transactional optimizes for delivery
+- **Sunset inactive contacts**: After 90 days of no opens, move contacts to a re-engagement segment or suppress
+- **Document learnings**: Record what subject lines, content types, and send times produce the best results
+- **Automate reporting**: Build a weekly script that calls `mc_get_campaign_report`, `buf_get_analytics`, and `sg_get_stats` to generate a unified report