smartlead-api

Smartlead API リファレンス

認証

すべてのリクエストでクエリパラメーターによる認証を使用します：?api_key={SMARTLEAD_API_KEY}

環境変数：$SMARTLEAD_API_KEY

ベース URL：https://server.smartlead.ai/api/v1

レート制限

• 標準プラン： 2,000 req/min（33 req/sec）
• 上位プラン： 3,000 req/min（50 req/sec）
• 429 および 5xx が返された場合は、指数バックオフで再試行します
• 一括操作では、並行数を 8～15 に設定して p-limit または PQueue を使用します

CLI クイックリファレンス

smartlead CLI（@smartlead/cli）は、すべての API エンドポイントをラップしています。簡単な情報照会に使用します：

# Campaigns
smartlead campaigns list
smartlead campaigns get <id>
smartlead campaigns create --name "Campaign Name"

# Leads
smartlead leads list --campaign-id <id>
smartlead leads add --campaign-id <id> --file leads.csv

# Email accounts
smartlead email-accounts list
smartlead email-accounts get <id>

# Analytics
smartlead analytics campaign <id>
smartlead analytics overall

# Master inbox
smartlead inbox replies

API エンドポイント

キャンペーン

GET  /campaigns/{id}                    — Fetch campaign by ID
POST /campaigns/create                  — Create new campaign
POST /campaigns/{id}/status             — Update status (START, PAUSED, STOP)
     Body: { "status": "START" }

キャンペーンのメールアカウント

GET    /campaigns/{id}/email-accounts   — List accounts assigned to campaign
POST   /campaigns/{id}/email-accounts   — Add accounts to campaign
       Body: { "email_account_ids": [1, 2, 3] }
DELETE /campaigns/{id}/email-accounts   — Remove accounts from campaign

キャンペーンのシーケンス

GET  /campaigns/{id}/sequences          — Fetch sequences
POST /campaigns/{id}/sequences          — Save/update sequences
     Body: { "sequences": [{ "seq_number": 1, "seq_delay_details": { "delay_in_days": 0 }, "subject": "...", "email_body": "..." }] }

A/B/C バリアント — 各シーケンス内の seq_variants 配列を使用します：

{
  "sequences": [{
    "seq_number": 1,
    "seq_delay_details": { "delay_in_days": 0 },
    "seq_variants": [
      { "variant_label": "A", "subject": "Subject A", "email_body": "<div>Body A</div>" },
      { "variant_label": "B", "subject": "Subject B", "email_body": "<div>Body B</div>" },
      { "variant_label": "C", "subject": "Subject C", "email_body": "<div>Body C</div>" }
    ]
  }]
}

注：distribution フィールドは含めないでください。SmartLead が自動的に均等に配分します。

メール本文の順序： コンテンツ → PS 配信停止文 → %signature%（署名は必ず最後）

キャンペーン設定とスケジュール

POST /campaigns/{id}/settings           — Update settings
     Body: { "track_settings": [...], "stop_lead_settings": "..." }

POST /campaigns/{id}/schedule           — Update schedule
     Body: { "timezone": "US/Eastern", "days_of_the_week": [1,2,3,4,5], "start_hour": "08:00", "end_hour": "17:00", "min_time_btw_emails": 8, "max_new_leads_per_day": 30 }

リード

GET  /leads/?api_key={key}&email={email}
     — Lookup lead by email address

POST /campaigns/{id}/leads
     — Add leads to campaign (batch up to 100)
     Body: { "lead_list": [{ "email": "...", "first_name": "...", "last_name": "...", "company_name": "...", "custom_fields": { "field1": "value1" } }] }

アナリティクス

GET /analytics/day-wise-overall-stats
    ?api_key={key}&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
    — Day-by-day metrics (sent, opened, clicked, replied, bounced)

GET /analytics/day-wise-positive-reply-stats
    ?api_key={key}&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
    — Day-by-day positive reply counts

GET /analytics/overall-stats-v2
    ?api_key={key}&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
    — Overall campaign metrics for date range

GET /analytics/campaign/list
    ?api_key={key}
    — List all campaigns with summary stats

GET /campaigns/{id}/analytics
    ?api_key={key}
    — Analytics for specific campaign

GET /campaigns/{id}/analytics-by-date
    ?api_key={key}&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
    — Campaign analytics for specific date range (sent_count, reply_count)

メールアカウント（グローバル）

GET  /email-accounts
     ?api_key={key}&offset=0&limit=100
     — List all email accounts (paginated)

GET  /email-accounts/{id}
     ?api_key={key}
     — Get specific email account

POST /email-accounts/save
     — Create/update email account (SMTP details, warmup, etc.)

マスター受信トレイ

POST /master-inbox/inbox-replies
     Body: { "api_key": "...", "offset": 0, "limit": 50, "message_type": "RECEIVED" }
     — Fetch inbox replies with filtering and pagination

サブクライアント／カスタム API キーのパターン

• 通常のサブクライアント： すべてのリクエストに ?api_key={MAIN_KEY}&client_id={CLIENT_ID} を渡します
• カスタム API キーを持つクライアント： クライアント自身の API キーを直接使用し、client_id パラメーターは指定しません

TypeScript のパターン

const SMARTLEAD_API = "https://server.smartlead.ai/api/v1";
const API_KEY = process.env.SMARTLEAD_API_KEY;

// GET example
const res = await fetch(`${SMARTLEAD_API}/campaigns/${campaignId}?api_key=${API_KEY}`);
const campaign = await res.json();

// POST example (add leads)
const res = await fetch(`${SMARTLEAD_API}/campaigns/${campaignId}/leads?api_key=${API_KEY}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ lead_list: leads.slice(0, 100) }),
});

パフォーマンスのヒント：メールアカウント一覧をキャッシュする

スクリプト内で /email-accounts を数回以上呼び出す場合は、最初に一度だけページネーションを行い、結果をメモリに保持します。Smartlead のページネーションでは 1 ページあたり 100 件が返されます。受信トレイが数千件あるアカウントでは、すべて取得するのに 30 秒以上かかります。

スクリプト間でキャッシュを永続化するには、一覧をローカルの JSON ファイルに書き込み、タイマー（例：1 時間ごと）で更新します。/smartlead-inbox-manager スキルには、このパターンを実装したスクリプトがあります。

---

次に行うこと

これはリファレンススキルのため、直接の次のステップはありません。Smartlead と連携するすべてのスキル（/smartlead-inbox-manager、/smartlead-campaign-upload-public、/email-deliverability-audit、/positive-reply-scoring、/deliverability-incident-response など）で使用されます。

ここに移動する前に使用していたスキルに戻ってください。

関連スキル

• Smartlead を扱うすべてのスキルで、このリファレンスを使用します。