@thierryteisseire/woodpecker-skill 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+---
+name: woodpecker-campaign
+description: Create and configure Woodpecker campaigns (V2) with correctly linked prospects (V1)
+---
+
+# Woodpecker Campaign Setup Skill
+
+This skill provides the definitive workflow for creating a Woodpecker campaign using the V2 API and correctly enrolling prospects using the V1 API, ensuring visual linkage and account signatures.
+
+## Quick Start
+
+1. **Get your API Key** from Woodpecker (Settings > Marketplace > API keys).
+2. **Find your Email Account ID** (needed for campaign creation).
+3. **Use the scripts** in this skill to automate the 2-step process.
+
+## Key Findings & Gotchas
+
+*   **API Splitting**: Campaign creation should use **V2** (`/rest/v2/campaigns`). Prospect enrollment MUST use **V1** (`/rest/v1/add_prospects_campaign`).
+*   **The Linkage Secret**: To make prospects appear in the Woodpecker dashboard for a V2 campaign, you must nest the `campaign_id` inside a `campaign` object in the enrollment payload.
+*   **Signature Handling**: Setting `"signature": "SENDER"` in the V2 step body uses the account's configured professional signature automatically.
+*   **Status & Force**: Always set prospect status to `ACTIVE` and use `force: True` in the enrollment payload to override any prior global status.
+
+## Workflow Patterns
+
+### 1. Create Campaign (V2)
+**Endpoint**: `POST https://api.woodpecker.co/rest/v2/campaigns`
+**Header**: `X-API-KEY: YOUR_KEY`
+
+```json
+{
+  "name": "Campaign Name",
+  "email_account_ids": [123456],
+  "settings": {
+    "timezone": "Europe/Paris",
+    "daily_enroll": 50
+  },
+  "steps": {
+    "type": "START",
+    "followup": {
+      "type": "EMAIL",
+      "body": {
+        "versions": [{
+          "subject": "{{SNIPPET_2}}",
+          "message": "<div>Bonjour {{FIRST_NAME}},<br><br>{{SNIPPET_1}}</div>",
+          "signature": "SENDER"
+        }]
+      }
+    }
+  }
+}
+```
+
+### 2. Enroll Prospects (V1)
+**Endpoint**: `POST https://api.woodpecker.co/rest/v1/add_prospects_campaign`
+**Header**: `X-API-KEY: YOUR_KEY`
+
+```json
+{
+  "campaign": {
+    "campaign_id": 2418XXX
+  },
+  "force": true,
+  "prospects": [
+    {
+      "email": "lead@example.com",
+      "status": "ACTIVE",
+      "snippet1": "Personalized Message",
+      "snippet2": "Dynamic Subject"
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+*   **200 OK but campaign is empty**: Check your payload nesting. Ensure `campaign_id` is inside `{"campaign": {"campaign_id": ...}}`.
+*   **Signature not showing**: Verify `"signature": "SENDER"` is in the step version body and that the email account has a signature set in Woodpecker.
+*   **Prospects added to list but not campaign**: This happens if the `campaign` object is missing from the V1 call.

package/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: woodpecker-campaign
+description: Create and configure Woodpecker campaigns (V2) with correctly linked prospects (V1)
+---
+
+# Woodpecker Campaign Setup Skill
+
+This skill provides the definitive workflow for creating a Woodpecker campaign using the V2 API and correctly enrolling prospects using the V1 API, ensuring visual linkage and account signatures.
+
+## Quick Start
+
+1. **Get your API Key** from Woodpecker (Settings > Marketplace > API keys).
+2. **Find your Email Account ID** (needed for campaign creation).
+3. **Use the scripts** in this skill to automate the 2-step process.
+
+## Key Findings & Gotchas
+
+*   **API Splitting**: Campaign creation should use **V2** (`/rest/v2/campaigns`). Prospect enrollment MUST use **V1** (`/rest/v1/add_prospects_campaign`).
+*   **The Linkage Secret**: To make prospects appear in the Woodpecker dashboard for a V2 campaign, you must nest the `campaign_id` inside a `campaign` object in the enrollment payload.
+*   **Signature Handling**: Setting `"signature": "SENDER"` in the V2 step body uses the account's configured professional signature automatically.
+*   **Status & Force**: Always set prospect status to `ACTIVE` and use `force: True` in the enrollment payload to override any prior global status.
+
+## Workflow Patterns
+
+### 1. Create Campaign (V2)
+**Endpoint**: `POST https://api.woodpecker.co/rest/v2/campaigns`
+**Header**: `X-API-KEY: YOUR_KEY`
+
+```json
+{
+  "name": "Campaign Name",
+  "email_account_ids": [123456],
+  "settings": {
+    "timezone": "Europe/Paris",
+    "daily_enroll": 50
+  },
+  "steps": {
+    "type": "START",
+    "followup": {
+      "type": "EMAIL",
+      "body": {
+        "versions": [{
+          "subject": "{{SNIPPET_2}}",
+          "message": "<div>Bonjour {{FIRST_NAME}},<br><br>{{SNIPPET_1}}</div>",
+          "signature": "SENDER"
+        }]
+      }
+    }
+  }
+}
+```
+
+### 2. Enroll Prospects (V1)
+**Endpoint**: `POST https://api.woodpecker.co/rest/v1/add_prospects_campaign`
+**Header**: `X-API-KEY: YOUR_KEY`
+
+```json
+{
+  "campaign": {
+    "campaign_id": 2418XXX
+  },
+  "force": true,
+  "prospects": [
+    {
+      "email": "lead@example.com",
+      "status": "ACTIVE",
+      "snippet1": "Personalized Message",
+      "snippet2": "Dynamic Subject"
+    }
+  ]
+}
+```
+
+## Troubleshooting
+
+*   **200 OK but campaign is empty**: Check your payload nesting. Ensure `campaign_id` is inside `{"campaign": {"campaign_id": ...}}`.
+*   **Signature not showing**: Verify `"signature": "SENDER"` is in the step version body and that the email account has a signature set in Woodpecker.
+*   **Prospects added to list but not campaign**: This happens if the `campaign` object is missing from the V1 call.

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@thierryteisseire/woodpecker-skill",
+    "version": "1.0.0",
+    "description": "Skill for setting up and managing Woodpecker campaigns correctly using API V2 and V1. Includes correctly linked prospect enrollment and signature automation.",
+    "main": "SKILL.md",
+    "bin": {
+        "woodpecker-setup": "./scripts/setup_campaign.py"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/thierryteisseire/woodpecker-skill.git"
+    },
+    "keywords": [
+        "agent-skill",
+        "woodpecker",
+        "cold-email",
+        "sales-automation",
+        "email-campaign",
+        "prospecting"
+    ],
+    "author": "Thierry Teisseire",
+    "license": "MIT",
+    "files": [
+        "SKILL.md",
+        "README.md",
+        "scripts/"
+    ],
+    "dependencies": {
+        "requests": "^2.31.0"
+    }
+}

package/scripts/setup_campaign.py

@@ -0,0 +1,83 @@
+import requests
+import json
+
+def create_woodpecker_campaign(api_key, account_id, name, subject_snippet="{{SNIPPET_2}}", body_html="<div>Bonjour {{FIRST_NAME}},<br><br>{{SNIPPET_1}}</div>"):
+    """
+    Creates a Woodpecker V2 Campaign with optimized settings.
+    """
+    url = "https://api.woodpecker.co/rest/v2/campaigns"
+    headers = {
+        "X-API-KEY": api_key,
+        "Content-Type": "application/json"
+    }
+    
+    payload = {
+        "name": name,
+        "email_account_ids": [int(account_id)],
+        "settings": {
+            "timezone": "Europe/Paris",
+            "prospect_timezone": True,
+            "daily_enroll": 50,
+            "gdpr_unsubscribe": True
+        },
+        "steps": {
+            "type": "START",
+            "followup": {
+                "type": "EMAIL",
+                "body": {
+                    "versions": [
+                        {
+                            "subject": subject_snippet,
+                            "message": body_html,
+                            "signature": "SENDER", # Use account signature
+                            "track_opens": True
+                        }
+                    ]
+                },
+                "followup": None
+            }
+        }
+    }
+    
+    resp = requests.post(url, headers=headers, json=payload)
+    if resp.status_code == 201:
+        campaign_id = resp.json().get("id")
+        print(f"SUCCESS: Campaign created with ID: {campaign_id}")
+        return campaign_id
+    else:
+        print(f"FAILED to create campaign: {resp.status_code}")
+        print(resp.text)
+        return None
+
+def enroll_prospects(api_key, campaign_id, prospects_list):
+    """
+    Enrolls a list of prospects into a campaign using V1 with correct nesting.
+    """
+    url = "https://api.woodpecker.co/rest/v1/add_prospects_campaign"
+    headers = {
+        "X-API-KEY": api_key,
+        "Content-Type": "application/json"
+    }
+    
+    # Batch size of 50 is recommended for V1
+    batch_size = 50
+    for i in range(0, len(prospects_list), batch_size):
+        batch = prospects_list[i:i + batch_size]
+        
+        payload = {
+            "campaign": {
+                "campaign_id": int(campaign_id)
+            },
+            "force": True, # Overrides status to ACTIVE
+            "prospects": batch
+        }
+        
+        resp = requests.post(url, headers=headers, json=payload)
+        print(f"Batch {i//batch_size + 1}: Status {resp.status_code}")
+        if resp.status_code != 200:
+            print(f"Error in batch: {resp.text}")
+
+# Usage Example:
+# prospects = [{"email": "test@example.com", "first_name": "John", "snippet1": "Icebreaker"}]
+# cid = create_woodpecker_campaign(YOUR_KEY, YOUR_ACC_ID, "New Campaign")
+# if cid: enroll_prospects(YOUR_KEY, cid, prospects)