kevjade-kit-email-operator

# Kit Email Marketing Operator

**AI-powered email marketing for Kit (ConvertKit)**

Version: 1.0.0  
Distribution: Private ClawHub (Premium Skool members only)

---

## Purpose

This skill enables OpenClaw to write, manage, and send professional email campaigns through Kit (ConvertKit). It combines AI-powered content generation with direct API integration to handle the complete email marketing workflow.

**Core capabilities:**
- Generate email copy matching user's brand voice
- Create subject lines and preview text
- Schedule broadcasts via Kit API
- Target specific segments and tags
- Track campaign performance
- Follow email marketing best practices

---

## Setup Process

### First Run

When a user requests email marketing help for the first time, initiate the setup wizard:

1. **Check for credentials**
   ```javascript
   const credsPath = '/data/.openclaw/workspace/.kit-credentials';
   ```
   If missing, run setup.

2. **Setup wizard flow**
   - Welcome and explain what you'll collect
   - Request Kit API credentials (v4 key + secret)
   - Store encrypted using `scripts/credentials.js`
   - Optional: voice training (analyze 3-5 past emails)
   - Optional: database integration (point to voice guide files)
   - Collect business context (niche, audience, offers, links)
   - Fetch Kit custom fields for future personalization
   - Confirm setup complete

3. **Voice training (if provided)**
   - Analyze provided email samples
   - Extract: tone, structure, vocabulary, sentence patterns
   - Save voice profile to `/data/.openclaw/workspace/.kit-voice-profile.json`
   - Use this profile for all future email generation

4. **Database integration (if configured)**
   - Ask for path to voice guide (e.g., `content/writing-rules/VOICE-GUIDE.md`)
   - Ask for path to memory files (e.g., `MEMORY.md`)
   - Store paths in credentials file
   - Read these before generating emails

---

## Email Generation Workflow

### Step 1: Clarifying Questions

Before writing any email, ask these questions:

**Required:**
- **Goal:** What's the purpose? (nurture/sell/announce/educate/re-engage/onboard)
- **Audience:** Who's receiving this? (all subscribers/specific tag/specific segment)
- **Main message:** What's the core point you want to communicate?
- **Call to action:** What should readers do? (click link/reply/take action)

**Optional:**
- **Links to include:** Any specific URLs to feature?
- **Tone preference:** (if not using voice training)
- **Personalization:** Should we use first name? Custom fields?
- **Timing:** Send now, schedule, or save as draft?

**Example questioning flow:**
```
I can help you write that email. A few quick questions:

1. What's the goal? (nurture relationship / make a sale / announce something / educate)
2. Who's this going to? (all subscribers / a specific tag / a segment)
3. What's the main message or value you want to communicate?
4. What action should they take after reading?
5. Any links you want me to include?
6. Should I personalize with first names?
```

### Step 2: Generate Content

**Subject Lines (provide 3 options):**
- Use formulas from `references/subject-line-formulas.md`
- Keep 27-73 characters
- Tap into curiosity, urgency, benefit, or social proof
- Avoid spam triggers (all caps, excessive punctuation)

**Preview Text:**
- 40-70 characters
- Complements subject line
- Teases value inside

**Email Body:**
- Follow structure from `references/email-best-practices.md`
- Match user's voice (if trained) or requested tone
- Include personalization tags if requested
- Strong hook in first sentence
- Clear value proposition
- Natural CTA placement
- Keep scannable (short paragraphs, white space)

**Personalization Tags:**
Reference `references/kit-personalization.md` for available tags:
- `{{ subscriber.first_name }}` - Subscriber's first name
- `{{ subscriber.email_address }}` - Email address
- Custom fields: `{{ subscriber.YOUR_FIELD_NAME }}`

**Example generation output:**
```markdown
## Subject Line Options

1. [Name], here's what 80% of email marketers get wrong
2. The 3-minute email hack that doubled my opens
3. Your subscribers are telling you something (listen closely)

## Preview Text

Most people ignore this signal. Here's how to spot it.

## Email Body

Hey {{ subscriber.first_name }},

Quick question: when was the last time you checked your email open rates?

[rest of email...]

**Call to Action:**
[Read the full guide here →](https://example.com/guide)

Talk soon,
[Your Name]
```

### Step 3: Review & Refine

Present the email to the user and ask:
- "How does this sound?"
- "Want me to adjust the tone?"
- "Should I try a different angle?"
- "Ready to send, or should we save as draft?"

Make revisions based on feedback.

### Step 4: Send via Kit API

Once approved, use `scripts/kit-api.js` to:

**Create broadcast:**
```javascript
const { KitAPI } = require('./scripts/kit-api.js');
const kit = new KitAPI();

const broadcast = await kit.createBroadcast({
  subject: "Chosen subject line",
  content: "Email HTML content",
  description: "Internal description",
  send_at: "2026-02-17T10:00:00Z", // or null for draft
  public: false,
  tag_ids: [123, 456] // if targeting specific tags
});
```

**Options:**
- **Draft:** `send_at: null` - save for review later
- **Schedule:** `send_at: "ISO timestamp"` - schedule for future
- **Send now:** Don't include `send_at` (immediately publishes)

**Targeting:**
- **All subscribers:** Don't include `tag_ids` or `segment_ids`
- **Specific tags:** `tag_ids: [123, 456]`
- **Specific segments:** `segment_ids: [789]`

Confirm with user before sending.

---

## Campaign Management

### View Campaign Stats

After sending, users can request performance data:

```javascript
const stats = await kit.getBroadcastStats(broadcastId);
```

**Present stats in readable format:**
```
📊 Campaign Performance: "Your Subject Line"

📤 Recipients: 1,234
📬 Opens: 456 (37%)
🖱️ Clicks: 89 (19.5% of opens)
🚪 Unsubscribes: 5 (0.4%)
```

**Provide insights:**
- Compare to benchmarks (see `references/email-best-practices.md`)
- Suggest improvements for next campaign
- Identify what worked well

### Manage Drafts

Users can:
- List saved drafts: `kit.listBroadcasts({ status: 'draft' })`
- Update drafts: `kit.updateBroadcast(id, changes)`
- Delete drafts: `kit.deleteBroadcast(id)`
- Schedule drafts: `kit.updateBroadcast(id, { send_at: timestamp })`

---

## Best Practices (Always Follow)

### Email Content

✅ **DO:**
- Write conversational, authentic copy
- Use short paragraphs (2-3 sentences max)
- Include one clear CTA
- Personalize when possible
- Make it scannable (bold, bullets, white space)
- Match user's brand voice
- Lead with value, not pitch

❌ **DON'T:**
- Use spam trigger words (free, guarantee, act now)
- Write long blocks of text
- Include multiple conflicting CTAs
- Sound robotic or corporate
- Make unsubscribing difficult
- Oversell or hype

### Subject Lines

✅ **DO:**
- Keep 27-73 characters
- Use curiosity, urgency, or benefit
- Personalize when appropriate
- A/B test different approaches
- Avoid spam triggers

❌ **DON'T:**
- Use all caps or excessive punctuation
- Mislead about content inside
- Use spammy words
- Be too vague or too long

### Sending Strategy

✅ **DO:**
- Send drafts first (review before scheduling)
- Test send to yourself
- Check deliverability (SPF, DKIM, DMARC)
- Segment your list when relevant
- Track performance
- Clean your list regularly

❌ **DON'T:**
- Send without review
- Blast entire list with sales pitch
- Ignore unsubscribes or complaints
- Send too frequently (respect inbox)
- Ignore performance data

---

## Technical Reference

### File Locations

- **Credentials:** `/data/.openclaw/workspace/.kit-credentials`
- **Voice Profile:** `/data/.openclaw/workspace/.kit-voice-profile.json`
- **API Client:** `skills/kit-email-operator/scripts/kit-api.js`
- **Credential Manager:** `skills/kit-email-operator/scripts/credentials.js`

### Available Functions

**From `script