selzy-api-skill（selzy API 技能）

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/):

⚠️ 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

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

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.

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

Response:

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

1.2 Create List — createList

Create a new contact list.

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.

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.

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"

2.2 Subscribe — subscribe

Add a single contact with opt-in control.

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.

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.

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.

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.

Create an email template for campaigns.

curl "https://api.selzy.com/en/api/createEmailMessage?format=json&api_key=$SELZY_API_KEY&sender_name=My%20Store&sender_email=news@yourdomain.com&subject=Summer%20Sale%20🔥&body=<h1>Hello!</h1><p>Check%20out%20our%20deals</p>&list_id=12345"

Response: {"result": {"message_id": 67890}}

3.2 Update Email Message — updateEmailMessage

Modify an existing email template.

curl "https://api.selzy.com/en/api/updateEmailMessage?format=json&api_key=$SELZY_API_KEY&id=67890&subject=Updated%20Subject"

3.3 Get Message — getMessage

Get email template details.

curl "https://api.selzy.com/en/api/getMessage?format=json&api_key=$SELZY_API_KEY&id=67890"

3.4 List Messages — listMessages

List all email templates with date filter.

curl "https://api.selzy.com/en/api/listMessages?format=json&api_key=$SELZY_API_KEY&date_from=2026-01-01&date_to=2026-02-01"

3.5 Create Email Template — createEmailTemplate

Create a reusable template (separate from messages).

curl "https://api.selzy.com/en/api/createEmailTemplate?format=json&api_key=$SELZY_API_KEY&name=Welcome%20Series&subject=Welcome!&body=<h1>Welcome {{Name}}!</h1>"

3.6 Get Template — getTemplate

Get template details.

curl "https://api.selzy.com/en/api/getTemplate?format=json&api_key=$SELZY_API_KEY&template_id=12345"

🚀 4. Campaigns

4.1 Create Campaign — createCampaign

Create and schedule a campaign.

curl "https://api.selzy.com/en/api/createCampaign?format=json&api_key=$SELZY_API_KEY&message_id=67890&start_time=2026-02-10%2010:00:00&timezone=Europe/Moscow&track_read=1&track_links=1"

Response: {"result": {"campaign_id": 11111}}

4.2 Cancel Campaign — cancelCampaign

Cancel a scheduled campaign before it sends.

curl "https://api.selzy.com/en/api/cancelCampaign?format=json&api_key=$SELZY_API_KEY&campaign_id=11111"

4.3 Get Campaign Status — getCampaignStatus

Check campaign status and progress.

curl "https://api.selzy.com/en/api/getCampaignStatus?format=json&api_key=$SELZY_API_KEY&campaign_id=11111"

Status values: draft, scheduled, sending, analysed, canceled

4.4 Get Campaigns — getCampaigns

List recent campaigns with optional date filter.

curl "https://api.selzy.com/en/api/getCampaigns?format=json&api_key=$SELZY_API_KEY&from=2026-01-01&to=2026-02-24"

Date format: YYYY-MM-DD HH:MM:SS or YYYY-MM-DD

📊 5. Campaign Statistics

5.1 Get Campaign Stats — getCampaignCommonStats

Get comprehensive statistics for a campaign.

curl "https://api.selzy.com/en/api/getCampaignCommonStats?format=json&api_key=$SELZY_API_KEY&campaign_id=11111"

Response:

{
  "result": {
    "total": 15000,
    "sent": 14800,
    "delivered": 14500,
    "read_unique": 4200,
    "read_all": 5100,
    "clicked_unique": 890,
    "clicked_all": 1200,
    "unsubscribed": 12,
    "spam": 3
  }
}

Metrics to calculate:

• Open Rate = (read_unique / delivered) × 100
• Click Rate = (clicked_unique / delivered) × 100
• Bounce Rate = ((sent - delivered) / sent) × 100
• Unsubscribe Rate = (unsubscribed / delivered) × 100
• Spam Rate = (spam / delivered) × 100

📮 6. Senders

6.1 Get Sender Emails — getSenderEmails

List all verified sender emails.

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

Response:

{
  "result": [
    {
      "id": 8526648,
      "email": "news@yourdomain.com",
      "name": "Your Store",
      "isVerified": true,
      "dkimStatus": "verified",
      "isFreeDomain": false
    }
  ]
}

Note: sender_email in campaigns must be from this verified list.

🎯 Instructions for the Agent

Critical Rules

🚨 SAFETY CHECKLIST (Before Any Campaign Send)

MANDATORY — verify ALL before proceeding:

• [ ] getLists called → have explicit list_id
• [ ] Contact count verified → matches expected recipients
• [ ] If count = 0 or count != expected → STOP and alert user
• [ ] createEmailMessage includes list_id parameter
• [ ] User confirmed: list name, count, subject, send time
• [ ] Explicit "send" or "confirm" received from user
• [ ] RATE LIMIT CHECK: Last campaign created >1 HOUR ago (HARD LIMIT)
• [ ] BATCH WARNING: If creating >1 campaign per hour = ACCOUNT BAN RISK

If ANY check fails → DO NOT SEND, ask user first.

CRITICAL: Creating 35 campaigns in a few minutes = ACCOUNT BAN. MAX 1 campaign per HOUR.

1. NEVER send a campaign without explicit user confirmation. Always show:

- Recipient list name and count (VERIFY this matches expectations) - Subject line - Body summary (first 100 chars) - Send time (immediate or scheduled) - list_id being used

1. For new campaigns, follow this workflow (MANDATORY):

   1. getLists → GET list_id AND count of contacts
   2. VERIFY: count >= expected recipients (if count=0, STOP and ask)
   3. createEmailMessage → MUST include list_id parameter + confirm subject + content
   4. RATE LIMIT CHECK: If created campaign in last 60s, WAIT before proceeding
   5. createCampaign → confirm timing + recipient count
   6. WAIT for explicit "send" or "confirm" from user

⚠️ BATCH SENDS: If creating multiple campaigns (e.g., for different segments): - Create all createEmailMessage calls first (no rate limit) - Queue createCampaign calls with 1 HOUR delays between each (HARD LIMIT) - NEVER create >1 campaign per hour — instant ban risk - Real incident: 35 campaigns in few minutes = account blocked - Use cron jobs to space campaigns across days if needed

1. CRITICAL: list_id is REQUIRED

- NEVER create email message without explicit list_id - ALWAYS verify contact count matches expectations before sending - If list_id is missing or count is wrong → STOP and alert user

1. For statistics requests:

- Always calculate rates as percentages - Compare to industry benchmarks if asked (avg: 20% open, 2.5% click) - Highlight trends (up/down vs previous campaigns)

1. Handle errors gracefully:

- Explain what went wrong in plain language - Suggest specific fixes - Retry once for rate limiting (add 1s delay)

1. Security reminders:

- Never log or display the full API key - Remind users that sender_email must be verified - Warn about GDPR/compliance for contact imports

Common Workflows

"Create a campaign for my VIP customers"

1. getLists → find VIP list, confirm count (MUST match expected recipients)
2. If count is wrong → STOP and alert user (DO NOT proceed)
3. Ask: subject, content type (promo/newsletter/event)
4. createEmailMessage → MUST include list_id parameter, show preview
5. createCampaign (omit start_time for immediate)
6. ⚠️ WAIT for "send it" or "confirm" before considering it done
7. Report: campaign_id, status, recipient count (verify matches step 1)

"How did my last campaign perform?"

1. getCampaigns (last 7 days) → get latest campaign_id
2. getCampaignCommonStats → get metrics
3. Calculate: open rate, click rate, bounce rate, unsubscribe rate
4. Present as: "X% opened, Y% clicked, Z% bounced"
5. Optional: compare to industry avg or previous campaign

"Add new subscribers to my newsletter"

1. getLists → find newsletter list
2. Confirm: list name, number of contacts to add
3. importContacts (bulk) OR subscribe (single)
4. Report: success count, skipped count, errors

"Show my contact lists"

1. getLists → retrieve all
2. Present table: Name | Total | Active | Created
3. Offer: "Want to create a new list or add contacts?"

"Schedule a webinar invitation"

1. getLists → confirm audience (GET list_id + count)
2. VERIFY count matches expected recipients
3. Ask: webinar details (title, date, time, link)
4. createEmailMessage with storytelling approach + list_id parameter
5. createCampaign with start_time="2026-02-25 10:00:00" timezone="Europe/Belgrade"
6. Confirm: "Scheduled for Feb 25 at 10:00 AM Belgrade time to {count} recipients"

📖 Real-World Bug Fix Example

❌ WRONG — Campaign sent to 1 person instead of 4

# Missing list_id — Selzy sends to 1 contact by default!
curl "https://api.selzy.com/en/api/createEmailMessage?format=json&api_key=$KEY&sender_name=My+Store&sender_email=me@example.com&subject=Sale&body=<h1>Sale!</h1>"

Result: Campaign #327590492 sent to 1 recipient instead of 4 contacts in list.

✅ CORRECT — Always include list_id

# Step 1: Get lists and verify count
curl "https://api.selzy.com/en/api/getLists?format=json&api_key=$KEY"
# Response: [{"id": 12345, "title": "My first list", "count": 4}]

# Step 2: Create message WITH list_id
curl "https://api.selzy.com/en/api/createEmailMessage?format=json&api_key=$KEY&sender_name=My+Store&sender_email=me@example.com&subject=Sale&body=<h1>Sale!</h1>&list_id=12345"
# Response: {"result": {"message_id": 67890}}

# Step 3: Create campaign
curl "https://api.selzy.com/en/api/createCampaign?format=json&api_key=$KEY&message_id=67890"
# Response: {"result": {"campaign_id": 11111}}

# Result: Campaign sent to ALL 4 contacts ✅

⚠️ API Error Handling

📚 Resources

• API Reference: https://selzy.com/en/support/api/
• Getting Started: https://selzy.com/en/support/
• Sign Up: https://selzy.com/en/registration/
• Blog: https://selzy.com/en/blog/

🧪 Quick Test Commands

Verify API access:

# Check connection
curl "https://api.selzy.com/en/api/getLists?format=json&api_key=YOUR_KEY"

# Check verified senders
curl "https://api.selzy.com/en/api/getSenderEmails?format=json&api_key=YOUR_KEY"

# Test campaign stats (replace ID)
curl "https://api.selzy.com/en/api/getCampaignCommonStats?format=json&api_key=YOUR_KEY&campaign_id=123456"

Skill Version: 2.0 (Complete) Last Updated: 2026-02-24 Tested Methods: getLists, getSenderEmails, getCampaigns, getCampaignCommonStats, createEmailMessage, createCampaign, getTemplates