---
name: dailydraft
description: Manage DailyDraft newsletters end-to-end. Use when you need to create newsletters, draft and send issues, manage subscribers, audit newsletter health, or set up custom domains on the DailyDraft platform.
metadata:
  version: "1.0"
  author: DailyDraft
  api_base: https://www.dailydraft.ai/api/v1
  api_reference: https://www.dailydraft.ai/llms-full.txt
---

# DailyDraft Agent Skill

You are operating against the DailyDraft REST API. All requests require `Authorization: Bearer <api_key>`.

## Discovery

- Full reference: https://www.dailydraft.ai/llms-full.txt
- Brief index: https://www.dailydraft.ai/llms.txt
- Agent docs: https://www.dailydraft.ai/docs/api/ai-agents
- Health check: `curl https://www.dailydraft.ai/up` → `{"status":"ok"}`

---

## Phase 0: Account & Newsletter Onboarding (Browser Flow)

If no account exists yet, use browser automation. There are no REST endpoints for these steps.

### 0.1 — Register

```
Navigate: https://www.dailydraft.ai/signup
Submit form:
  user[email_address]         = "your@email.com"
  user[password]              = "SecurePass123!"
  user[password_confirmation] = "SecurePass123!"
→ Redirected to /email_confirmation_pending
```

### 0.2 — Confirm Email

```
Extract confirmation link from email (format: /email_confirmations/<TOKEN>)
Navigate to that URL
→ Session created, redirected to /newsletters
```

### 0.3 — Create Newsletter

```
Navigate: https://www.dailydraft.ai/newsletters/new
Submit form:
  newsletter[name]       = "Your Newsletter Name"
  newsletter[tagline]    = "One-line description for your readers"
  newsletter[keywords]   = "topic1, topic2, topic3"
  newsletter[from_name]  = "Your Name"
  newsletter[from_email] = "you@yourdomain.com"
→ Redirected to /newsletters/:id/setup_frequency
```

### 0.4 — Set Frequency

```
Submit: POST /newsletters/:id/apply_frequency
  frequency = "weekly"  # or: daily, three_times, skip
→ Redirected to /newsletters/:id/preference/edit
```

### 0.5 — Set Preferences

```
Submit: PATCH /newsletters/:id/preference
  newsletter_preference[target_audience]   = "Who reads your newsletter"
  newsletter_preference[content_tone]      = "professional"
  newsletter_preference[newsletter_length] = "medium"
→ Newsletter live at https://<subdomain>.dailydraft.ai
```

### 0.6 — Generate API Key

```
Navigate: https://www.dailydraft.ai/newsletters/:id/api_keys/new
Submit form:
  api_key[name]          = "my-agent"
  api_key[permissions][] = "read"
  api_key[permissions][] = "write"
→ Full key shown ONCE on screen — capture it immediately
```

Set for all subsequent steps:
```bash
BASE=https://www.dailydraft.ai/api/v1
API_KEY=<captured_key>
```

---

## Setup (Existing Account)

If you already have an account and API key:
1. API key is at: newsletter dashboard → Settings → API Keys
2. Newsletter tier must be `paid` to send email via `send_now`

Set `API_KEY` and `BASE=https://www.dailydraft.ai/api/v1` in your environment or substitute inline.

---

## Core Workflows

### 1. Audit newsletter health

```bash
curl -s $BASE/newsletter -H "Authorization: Bearer $API_KEY" | jq .
curl -s $BASE/newsletter/stats -H "Authorization: Bearer $API_KEY" | jq .
```

Check: `status` (should be `active`), `tier` (must be `paid` to send email), `from_email` (must be a valid sender).

### 2. List recent issues

```bash
curl -s "$BASE/issues?per_page=10" -H "Authorization: Bearer $API_KEY" | jq '.issues[] | {id, subject, status, sent_at}'
```

### 3. Create and send an issue

```bash
# Step 1: Create
ISSUE=$(curl -s -X POST $BASE/issues \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": {
      "subject": "Your Subject Line",
      "content_markdown": "## Intro\n\nYour content here..."
    }
  }')
ISSUE_ID=$(echo $ISSUE | jq -r '.id')

# Step 2: Approve
curl -s -X PATCH $BASE/issues/$ISSUE_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"issue": {"status": "approved"}}'

# Step 3: Send
curl -s -X POST $BASE/issues/$ISSUE_ID/send_now \
  -H "Authorization: Bearer $API_KEY" | jq .
```

### 4. Edit an existing issue

```bash
curl -s -X PATCH $BASE/issues/$ISSUE_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": {
      "subject": "Updated subject",
      "content_markdown": "## Updated content\n\n..."
    }
  }' | jq .
```

### 5. Publish to web (no email)

```bash
curl -s -X POST $BASE/issues/$ISSUE_ID/publish \
  -H "Authorization: Bearer $API_KEY" | jq '{message, web_url}'
```

### 6. Import subscribers

```bash
curl -s -X POST $BASE/subscribers/bulk_create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscribers": [{"email": "user@example.com"}]}' | jq .
```

### 7. Tag a subscriber

```bash
curl -s -X POST $BASE/subscribers/$SUBSCRIBER_ID/add_tag \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag": "vip"}' | jq .
```

### 8. Update newsletter profile

```bash
curl -s -X PATCH $BASE/newsletter \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "newsletter": {
      "name": "New Name",
      "tagline": "New tagline",
      "from_name": "Todd Dickerson",
      "from_email": "todd@example.com"
    }
  }' | jq .
```

### 9. Set up custom domain (web only)

No API endpoint for domain setup — must use the web dashboard:
1. Go to: `https://www.dailydraft.ai/newsletters/<newsletter_id>/custom_domains/choose_method`
2. Enter domain (e.g., `newsletter.yourdomain.com`)
3. Add the CNAME record shown at your DNS provider
4. Click **Verify** — monitor status at the custom domains page
5. Domain becomes `active` once DNS propagates + SSL provisions

DNS record format:
```
CNAME  newsletter.yourdomain.com  →  <subdomain>.dailydraft.ai
```

Optionally add TXT record if shown for Cloudflare ownership verification.

---

## Issue Content Format

Write `content_markdown` using standard Markdown:

```markdown
## Opening Hook

One paragraph that makes the reader glad they opened.

## Main Story: [Headline]

Your lead story — 150-300 words. What happened, why it matters, what to do about it.

## Quick Takes

- **[Source]:** One-sentence summary of what they announced
- **[Source]:** One-sentence summary of what happened
- **[Source]:** One-sentence summary of the trend

## The Takeaway

One paragraph with your editorial POV. What should the reader do differently after reading this?

---

*Reply to this email with your thoughts. Every reply gets read.*
```

---

## Newsletter Profile Best Practices

- `from_email`: Use a custom domain address (e.g., `digest@yourdomain.com`) for deliverability
- `from_name`: First name or brand name — avoid "noreply"
- `tagline`: One sentence describing who the newsletter is for and what they get
- `primary_color`: Hex color matching your brand
- `keywords`: Comma-separated topics (used by AI curation engine)

---

## Status Machine

```
draft → approved → sending → sent
draft → scheduled (AI draft complete, awaiting review)
scheduled → approved → sending → sent
any → published (web-only, no email state change)
```

Always call `send_now` only when status is `approved` or `scheduled`.

---

## Errors to Handle

| Code | Meaning | Fix |
|------|---------|-----|
| 401 | Bad API key | Regenerate key at Settings → API Keys |
| 402 | Free tier | Upgrade newsletter to paid |
| 403 | Wrong permission | Use a key with `write` or `delete` permission |
| 422 | Validation failure | Check `errors` array in response |
| 429 | Rate limited | Wait until `X-RateLimit-Reset` timestamp |

---

## Health Check

```bash
curl https://www.dailydraft.ai/up
# → {"status":"ok"}
```