Selzy Email Marketing

通过 Selzy API 创建和发送电子邮件营销活动。 管理联系人、细分、模板。安排活动， 运行 A/B 测试并分析性能（打开、点击、弹跳）。 将自然语言请求转化为完整的电子邮件活动。 **v2.1 — 修复了严重错误：** 活动现在需要显式 list_id 验证。 如果没有 list_id，Selzy 仅发送给 1 个联系人。始终首先调用 getLists。

## 概述（中文）

通过 Selzy API 创建和发送电子邮件营销活动。
管理联系人、细分、模板。安排活动，
运行 A/B 测试并分析性能（打开、点击、弹跳）。
将自然语言请求转化为完整的电子邮件活动。
**v2.1 — 修复了严重错误：** 活动现在需要显式 list_id 验证。
如果没有 list_id，Selzy 仅发送给 1 个联系人。始终首先调用 getLists。

## 原文

# Selzy Email Marketing API — Complete Guide

Selzy is an email marketing platform with a REST API for managing contacts, creating campaigns, and analyzing performance. This skill lets you run your entire email marketing from an AI assistant.

---

## 🚨 CRITICAL WARNING — Read Before Using

### ⚠️ Common Pitfall: Campaigns Sent to Wrong Recipients

**Problem:** If you create a campaign without explicitly specifying `list_id`, Selzy will send to **ONLY 1 contact** (default behavior), not your entire list.

**Solution:** ALWAYS follow this workflow:
1. Call `getLists` → get the correct `list_id` AND verify contact count
2. Pass `list_id` to `createEmailMessage` (REQUIRED parameter)
3. Verify recipient count matches expectations BEFORE calling `createCampaign`
4. Get explicit user confirmation before sending

**This affects ALL users.** The fix is in the workflow, not the API.

---

### 🚫 RATE LIMIT WARNING — Account Ban Risk

**REAL INCIDENT (2026-02-25):** User sent **35 email campaigns in a few minutes** using `createCampaign`. Selzy blocked the account for suspicious bulk activity.

**Official Selzy API Rate Limits** (from https://selzy.com/en/support/api/common/selzy-api-limits/):

| Endpoint / Action | Limit |
|-------------------|-------|
| **General API** | 1200 requests / 60 seconds (per API key or IP) |
| **checkEmail method** | 300 requests / 60 seconds |
| **subscribe method** | Limited (exact value not published) |
| **sendEmail method** | 1,000 emails/day default for new users (auto-increases) |
| **sendSms method** | 150 numbers per call |
| **getCampaigns method** | 10,000 campaigns per response |
| **getMessages limit** | 100 records per request (default 50) |
| **importContacts timeout** | 30 seconds per call |

**⚠️ CRITICAL: Campaign Creation Rate (UNPUBLISHED but ENFORCED)**

While general API allows 1200 req/min, **creating campaigns (`createCampaign`) has additional fraud detection**:
- **MAX 1 campaign creation per HOUR** (strict limit after ban incident)
- **Burst of 35 campaigns in <5 min = instant account block** (real incident 2026-02-25)
- Selzy's fraud system flags rapid campaign creation as suspicious bulk activity

**Why the discrepancy?**
- 1200 req/min is for **read operations** (getLists, getCampaigns, stats)
- **Write operations** (createCampaign, importContacts) have stricter anti-abuse limits
- No official documentation on campaign creation rate — enforced heuristically

**Symptoms of Rate Limit Violation:**
- API returns `count=0` for all campaigns (even valid ones)
- Campaigns stuck in `scheduled` status but never send
- Account flagged for manual review

**Recovery:**
1. **STOP all campaign creation immediately**
2. Wait 24-48 hours for automatic unblock OR contact Selzy support
3. Request manual review + explain it was automation error
4. When unblocked: implement rate limiting (**1 campaign / hour MAX**)

**Prevention:**
- **Wait 1 HOUR between `createCampaign` calls** — this is now the hard limit
- For batch sends: create max 1 campaign per hour, spread across days
- Monitor API responses: `count=0` across multiple campaigns = RED FLAG
- **NEVER automate bulk campaign creation without rate limiting**
- Remember: 1200 req/min is for READ operations, not campaign creation

**If you need to send to multiple segments:**
```
1. Create all email messages first (no rate limit on createEmailMessage)
2. Schedule campaigns across multiple days (1 per hour max)
3. OR: use single campaign with segmented list (preferred)
4. Use cron jobs with hourly spacing for automated sends
```

**This is now MANDATORY:** Any automation creating >1 campaign per hour will risk permanent ban. **1 campaign per hour = HARD LIMIT.**

---

### 📊 Official Selzy API Limits Summary

| Operation | Limit | Notes |
|-----------|-------|-------|
| General API calls | 1200 / min | Per API key or IP |
| checkEmail | 300 / min | Email validation |
| sendEmail (transactional) | 1000 / day | New users, auto-increases |
| sendSms | 150 / call | Max numbers per request |
| getCampaigns | 10,000 / response | Pagination needed for more |
| getMessages | 100 / request | Default 50 |
| importContacts | 30s timeout | Per call |
| **createCampaign** | **1 / hour** | **Unpublished, HARD LIMIT after ban incident** |

**Source:** https://selzy.com/en/support/api/common/selzy-api-limits/

---

## 🔐 Authentication

All requests require the `SELZY_API_KEY` environment variable. Pass it as the `api_key` parameter.

**Base URL:** `https://api.selzy.com/en/api`

**Important:** All methods use `GET` with query parameters (Selzy API uses GET for all endpoints). URL-encode parameter values when needed.

## General Request Pattern

```bash
curl "https://api.selzy.com/en/api/{METHOD}?format=json&api_key=$SELZY_API_KEY&{params}"
```

**Response Format:**
- Success: `{"result": {...}}` or `{"result": [...]}`
- Error: `{"error": "message", "code": "error_code"}`

---

## 📋 1. Contact Lists

### 1.1 Get Lists — `getLists`

Retrieve all contact lists.

```bash
curl "https://api.selzy.com/en/api/getLists?format=json&api_key=$SELZY_API_KEY"
```

**Response:**
```json
{
  "result": [
    {"id": 1, "title": "Newsletter subscribers", "count": 15420, "active_contacts": 14800}
  ]
}
```

### 1.2 Create List — `createList`

Create a new contact list.

```bash
curl "https://api.selzy.com/en/api/createList?format=json&api_key=$SELZY_API_KEY&title=VIP%20Customers"
```

**Response:** `{"result": {"id": 12345}}`

### 1.3 Get List Details — `getList`

Get detailed info about a specific list.

```bash
curl "https://api.selzy.com/en/api/getList?format=json&api_key=$SELZY_API_KEY&list_id=12345"
```

---

## 👥 2. Contact Management

### 2.1 Import Contacts — `importContacts`

Bulk import contacts into a list.

```bash
curl "https://api.selzy.com/en/api/importContacts?format=json&api_key=$SELZY_API_KEY&field_names[]=email&field_names[]=Name&data[][]=john@example.com&data[][]=John&data[][]=jane@example.com&data[][]=Jane&list_ids=12345&overwrite=2"
```

| Parameter | Description |
|-----------|-------------|
| `field_names[]` | Column names: email (required), Name, phone, etc. |
| `data[][]` | Contact data rows (flat array, fills row by row) |
| `list_ids` | Comma-separated list IDs to add contacts to |
| `overwrite` | 0=skip existing, 1=overwrite all, 2=overwrite empty only |

### 2.2 Subscribe — `subscribe`

Add a single contact with opt-in control.

```bash
curl "https://api.selzy.com/en/api/subscribe?format=json&api_key=$SELZY_API_KEY&list_ids=12345&fields[email]=user@example.com&fields[Name]=Alice&double_optin=3"
```

**double_optin values:**
- `0` = no confirmation
- `3` = send confirmation email
- `4` = already confirmed (force subscribe)

### 2.3 Exclude Contact — `exclude`

Unsubscribe/remove a contact.

```bash
curl "https://api.selzy.com/en/api/exclude?format=json&api_key=$SELZY_API_KEY&contact_type=email&contact=user@example.com"
```

### 2.4 Get Contact — `getContact`

Get contact details by email.

```bash
curl "https://api.selzy.com/en/api/getContact?format=json&api_key=$SELZY_API_KEY&email=user@example.com"
```

### 2.5 Create Custom Field — `createField`

Add a custom field for contacts.

```bash
curl "https://api.selzy.com/en/api/createField?format=json&api_key=$SELZY_API_KEY&field_name=Company&field_type=text"
```

**field_type options:** `text`, `number`, `date`, `boolean`

---

## 📧 3. Email Messages (Templates)

### 3.1 Create Email Message — `createEmailMessage`

⚠️ **CRITICAL: `list_id` is REQUIRED** ⚠️

**Without `list_id`, Selzy will send to ONLY 1 contact (default behavior).** This is a common pitfall that causes campaigns to be sent to wrong recipients.

**ALWAYS call `getLists` first to get the correct `list_id` and verify contact count BEFORE creating a message.**