Selzy

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"