mcpField
I
instantly-api

instantly-api

github.com/cold-iqマーケティング・グロース347 回インストール2 週間前に更新
リポジトリ

instantly-api について

instantly-apiは、ColdIQ経由でInstantlyを操作するマーケティングスキルです。メールキャンペーンの管理、リード登録、分析に対応し、ユーザー自身のInstantlyアカウントを使ってInstantly v2のパスを維持します。

主な機能

  1. 01キャンペーンの作成・参照・更新・有効化・一時停止
  2. 02リードの個別または一括追加
  3. 03キャンペーンと日次分析の確認
  4. 04メールアドレスの検証
  5. 05リード変数によるパーソナライズ

活用シーン

  1. 01メールキャンペーンの作成とリード登録
  2. 02シーケンスを確認してからキャンペーンを有効化
  3. 03返信・開封・バウンスによる成果評価

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cold-iq/coldiq-marketplace-skills --skill instantly-api

インストール後、Claude Code で/instantly-apiを入力して読み込まれたか確認します。

詳細

Instantly API

ColdIQ の再販 Instantly エンドポイント /v1/instantly/* を介して、Instantly でキャンペーンを作成し、リードを読み込み、分析データを取得します（Instantly v2 のパスを維持し、ColdIQ キーは 1 つ。BYOK — 自分の Instantlу アカウントを接続。無料で、ColdIQ クレジットは不要です）。

ColdIQ Marketplace エンドポイント

タスクメソッドパスクレジットエンドポイント ID備考
キャンペーンを作成POST/v1/instantly/campaigns無料instantly.campaigns.createColdIQ のデフォルトを使用
キャンペーンを一覧表示GET/v1/instantly/campaigns無料instantly.campaigns.listステータスでフィルター
キャンペーンを取得GET/v1/instantly/campaigns/{id}無料instantly.campaigns.getシーケンスを確認
キャンペーンを更新PATCH/v1/instantly/campaigns/{id}無料instantly.campaigns.patch部分更新
キャンペーンを有効化POST/v1/instantly/campaigns/{id}/activate無料instantly.campaigns.activate空の本文 {}。ユーザーに確認
キャンペーンを一時停止POST/v1/instantly/campaigns/{id}/pause無料instantly.campaigns.pause空の本文 {}
リードを 1 件追加POST/v1/instantly/leads無料instantly.leads.createcampaign を使用し、campaign_id は使わない
リードを一括追加POST/v1/instantly/leads/add無料instantly.leads.add
リードを一覧表示POST/v1/instantly/leads/list無料instantly.leads.listGET /leads は 404 を返す
キャンペーン分析GET/v1/instantly/campaigns/analytics無料instantly.campaigns.analytics返信／開封／バウンス
日次分析GET/v1/instantly/campaigns/analytics/daily無料instantly.campaigns.analytics.daily日別
メールを検証POST/v1/instantly/email-verification無料instantly.email_verification.create

推奨キャンペーン設定

新しいキャンペーンすべてに適用する、到達率を優先した基本設定です。

{
  "email_gap": 15, "random_wait_max": 7, "text_only": true, "first_email_text_only": true,
  "daily_limit": 9999, "stop_on_reply": true, "match_lead_esp": true,
  "link_tracking": false, "open_tracking": false,
  "campaign_schedule": { "schedules": [{ "name": "Weekday schedule",
    "timing": { "from": "08:00", "to": "14:00" },
    "days": { "1": true, "2": true, "3": true, "4": true, "5": false },
    "timezone": "America/Detroit" }] }
}

text_only、リンク／開封トラッキングなし、ESP マッチングをすべて有効にすると、到達率が最大化されます。

注意点（最初にお読みください）

  1. タイムゾーン： America/New_York ではなく、America/Detroit を使用してください（Instantly は New_York を拒否します）。
  2. スケジュールの曜日： 日曜日を起点とするゼロインデックスです（0=日 … 6=土）。
  3. 有効化／一時停止： 空の JSON 本文 {} を送信してください。
  4. リードの削除： 本文を送信せず、Content-Type ヘッダーも付けないでください。
  5. リードの一覧表示： POST /v1/instantly/leads/list を使用してください（GET は 404 を返します）。
  6. リードのフィールド名： campaign（UUID）を使用し、campaign_id は使わないでください。誤ったキーを使うと、リードがキャンペーンに紐付けられず、組織のプールに追加されてしまいます。
  7. HTML エスケープ： 本文中の > は > にする必要があります（例：「Predictable > random」）。
  8. リードの重複排除： デフォルトではキャンペーンをまたいでリードの重複が排除されます。強制的に追加するには skip_if_in_campaign: false を設定してください。

HTML メールの書式設定

text_only: true の場合でも、Instantly は HTML の <div> を保存します。各行を個別の <div> に入れ、空行は <div><br /></div> とし、<p> は使わず、>／< は HTML エンコードしてください。署名は <div>{{accountSignature}}</div> とします。

import html
def to_instantly_html(plain):
    return ''.join('<div><br /></div>' if not l.strip() else f'<div>{html.escape(l.strip())}</div>'
                   for l in plain.strip().split('\n'))

変数

基本変数（リードから自動取得）：{{firstName}}、{{lastName}}、{{companyName}}、{{email}}、 {{website}}、{{personalization}}、{{accountSignature}}。カスタム変数：リードの payload に含まれる任意のキーが {{key}} として使用できます（例：{{Idea1}}、{{Idea2}}、{{Idea3}}、{{SL}}）。 スピンタックス：{{RANDOM|Hey|Hi|Hello}} {{firstName}},。

ワークフロー

キャンペーンの一括開始

  1. ColdIQ のデフォルト設定とシーケンスを使ってキャンペーンを作成します。 → POST /v1/instantly/campaigns · 無料 · instantly.campaigns.create
  2. ペイロード変数を使ってリードを追加します（ループまたは一括）。 → POST /v1/instantly/leads · 無料 · instantly.leads.create 
    { "campaign": "campaign-uuid", "email": "[email protected]", "first_name": "John",
  "company_name": "Acme", "payload": { "Idea1": "...", "Idea2": "...", "Idea3": "..." } }
  3. シーケンスが適切であることを確認します。 → GET /v1/instantly/campaigns/{id} · 無料 · instantly.campaigns.get
  4. 送信アカウントを接続し（Instantly の UI）、その後キャンペーンを有効化します — 必ず事前にユーザーの確認を得てください。 → POST /v1/instantly/campaigns/{id}/activate · 無料 · instantly.campaigns.activate

パフォーマンスの確認

  1. 統計を集計します。 → GET /v1/instantly/campaigns/analytics · 無料 · instantly.campaigns.analytics
  2. 日次の推移を確認します。 → GET /v1/instantly/campaigns/analytics/daily · 無料 · instantly.campaigns.analytics.daily

ベンチマーク

指標停止継続拡大
肯定的な返信率<1%2–5%>5%
肯定的な返信1件あたりのメール数>5,0001,000–3,000<1,000
ミーティング予約率<0.5%1–2%>2%

安定して高い成果を上げている方法：AI が生成したキャンペーン案3つ（{{Idea1}}/{{Idea2}}/{{Idea3}}）をパーソナライズ用ペイロードとして使用します。バリアントごとに200件以上送信した後、返信率が1%未満のものは停止し、上位2～3つの勝者を軸に分岐します（勝者／改良／実験を70/20/10の割合で実施）。

コメント

Markdown 対応