즉시 MCP 서버

Instantly API v2 용 MCP 서버로, 이메일 캠페인 및 리드 관리 기능에 대한 액세스를 제공합니다.

Instantly API에 대하여

Instantly API v2는 다음을 포함하여 Instantly 플랫폼의 다양한 리소스와 기능에 대한 액세스를 제공하는 RESTful API입니다.

• 캠페인 관리

• 리드 관리

• 이메일 처리 및 검증

• 해석학

• 계정 관리

• 차단 목록 관리

• 그리고 더 많은 것

이 MCP 서버는 가장 일반적으로 사용되는 기능에 쉽게 액세스할 수 있도록 이러한 엔드포인트의 하위 집합을 구현합니다.

API 참조

Instantly API v2 전체 문서는 다음에서 확인할 수 있습니다.

• API 탐색기

• API 스키마

• 분석 엔드포인트

모든 API 요청에 대한 기본 URL은 https://api.instantly.ai/api/v2 입니다.

도구

이 MCP 서버는 Instantly API v2 엔드포인트에 매핑되는 다음 도구를 구현합니다.

1. instantly_create_lead

   • API 엔드포인트 : POST /api/v2/leads

   • 새로운 리드를 생성하세요

   • 입력:

     • email (문자열)

     • first_name (선택적 문자열)

     • last_name (선택적 문자열)

     • company_name (선택적 문자열)

     • campaign (선택적 문자열, UUID)

     • list_id (선택적 문자열, uuid)

     • personalization (선택 문자열)

     • website (선택 문자열)

     • phone (선택적 문자열)

     • custom_variables (선택적 객체)

2. instantly_get_lead

   • API 엔드포인트 : GET /api/v2/leads/{id}

   • ID로 리드 세부 정보 가져오기

   • 입력: id (문자열, uuid)

   • 반품: 리드 세부 정보

3. instantly_list_leads

   • API 엔드포인트 : POST /api/v2/leads/list

   • 선택적 필터를 사용하여 리드 나열

   • 입력:

     • campaign (선택적 문자열, UUID)

     • list_id (선택적 문자열, uuid)

     • limit (선택적 숫자)

     • starting_after (선택적 문자열)

   • 반환: 리드 배열

4. instantly_update_lead

   • API 엔드포인트 : PATCH /api/v2/leads/{id}

   • 리드 정보 업데이트

   • 입력:

     • id (문자열, UUID)

     • first_name (선택적 문자열)

     • last_name (선택적 문자열)

     • company_name (선택적 문자열)

     • personalization (선택 문자열)

     • website (선택 문자열)

     • phone (선택적 문자열)

     • custom_variables (선택적 객체)

5. instantly_delete_lead

   • API 엔드포인트 : DELETE /api/v2/leads/{id}

   • 리드 삭제

   • 입력: id (문자열, uuid)

6. instantly_list_campaigns

   • API 엔드포인트 : GET /api/v2/campaigns

   • 페이지 매김 지원이 있는 캠페인 목록

   • 입력:

     • limit (선택적 숫자, 기본값 5, 최대 100)

     • starting_after (선택적 문자열) - 페이지 매김의 경우 이전 응답의 next_starting_after 값을 사용합니다.

     • status (선택적 숫자) - 상태별로 캠페인 필터링(0: 초안, 1: 활성, 2: 일시 중지, 3: 완료, 4: 실행 중인 하위 시퀀스)

   • 반환: 페이지 정보가 포함된 캠페인 배열

   • 쪽수 매기기:

     • 첫 번째 요청: starting_after 없이 호출

     • 이후 페이지: 이전 응답의 next_starting_after 값을 사용합니다.

     • 더 이상 페이지가 없으면 응답에 next_starting_after 값이 포함되지 않습니다.

   • 예: 활성 캠페인만 가져오려면 status: 1 사용합니다.

7. instantly_get_campaign

   • API 엔드포인트 : GET /api/v2/campaigns/{id}

   • 캠페인 세부 정보 받기

   • 입력: id (문자열, uuid)

   • 반품: 캠페인 세부 정보

8. instantly_get_warmup_analytics

   • API 엔드포인트 : POST /api/v2/accounts/warmup-analytics

   • 지정된 이메일 계정에 대한 워밍업 분석 받기

   • 입력: emails (문자열 배열)

   • 반환: 이메일 워밍업 성능에 대한 상태 점수 및 측정항목

   • 이메일 전달성 및 계정 상태 모니터링에 유용합니다.

9. instantly_test_account_vitals

   • API 엔드포인트 : POST /api/v2/accounts/test/vitals

   • Instantly 작업 공간에서 이메일 계정의 상태와 연결성을 테스트하세요.

   • 입력: accounts (문자열 배열) - 여러 이메일 주소를 한 번에 테스트할 수 있습니다.

   • 보고:

     • 전반적인 테스트 상태

     • 성공 및 실패 계정 요약

     • 공급자 세부 정보를 포함한 각 계정에 대한 자세한 정보

     • 실패한 계정에 대한 문제 해결 권장 사항

   • 이메일 계정 구성, 인증 및 API 액세스와 관련된 문제를 식별하는 데 도움이 됩니다.

   • 예: {"accounts": ["user@example.com", "sales@company.com"]}

10. instantly_get_campaign_analytics

• API 엔드포인트 : GET /api/v2/campaigns/analytics

• 지정된 기간 동안 캠페인에 대한 성과 지표를 얻으세요

• 입력:

  • id (선택적 문자열) - 특�� 캠페인의 캠페인 ID

  • start_date (문자열) - YYYY-MM-DD 형식의 시작 날짜

  • end_date (문자열) - YYYY-MM-DD 형식의 종료 날짜

• 반환: 오픈율, 응답율, 리드 수 및 기회 데이터를 포함한 포괄적인 측정항목

분석 엔드포인트

Instantly API는 이메일 캠페인과 계정의 성과를 모니터링하기 위한 강력한 분석 엔드포인트를 제공합니다.

1. Warmup 분석 받기

   • API 엔드포인트 : POST /api/v2/accounts/warmup-analytics

   • 설명 : 지정된 이메일 계정에 대한 워밍업 분석 데이터를 검색합니다.

   • 필수 범위 : accounts:read , accounts:all , all:read 또는 all:all

   • 요청 본문 :

     지엑스피1

   • 응답 : 보낸 이메일, 받은 편지함 배치, 스팸 배치 및 받은 이메일에 대한 일일 및 집계 데이터와 각 계정의 상태 점수를 제공합니다.

2. 테스트 계정 필수 정보

   • API 엔드포인트 : POST /api/v2/accounts/test/vitals

   • 설명 : 이메일 계정의 상태 및 연결성을 테스트합니다.

   • 필수 범위 : accounts:read , accounts:all , all:read 또는 all:all

   • 요청 본문 :

     { "accounts": ["user@example.com"] }

   • 응답 : 계정 상태 및 감지된 문제에 대한 자세한 정보가 포함된 성공 및 실패 목록을 반환합니다.

3. 캠페인 분석 받기

   • API 엔드포인트 : GET /api/v2/campaigns/analytics

   • 설명 : 하나 또는 여러 캠페인에 대한 성과 지표를 검색합니다.

   • 쿼리 매개변수 :

     • id (선택 사항): 특정 캠페인의 캠페인 ID

     • start_date : 분석 기간의 시작 날짜

     • end_date : 분석 기간의 종료일

   • 응답 : 다음을 포함한 포괄적인 캠페인 통계를 반환합니다.

     • 총 리드 수

     • 연락된 리드 수

     • 이메일 오픈 카운트

     • 답변 수

     • 반송 횟수

     • 구독 취소된 수

     • 완료된 카운트

     • 보낸 이메일 수

     • 새로운 리드가 연락된 횟수

     • 총 기회

     • 총 기회 가치

요청 매개변수와 응답 형식에 대한 자세한 내용은 Instantly Analytics API 설명서를 참조하세요.

추가 Instantly API 엔드포인트

Instantly API v2에는 다음을 포함하여 이 MCP 서버에 구현되지 않은 많은 다른 엔드포인트가 포함되어 있습니다.

• 캠페인 관리 :

  • 캠페인 생성: POST /api/v2/campaigns

  • 캠페인 활성화: POST /api/v2/campaigns/{id}/activate

  • 캠페인 일시 중지: POST /api/v2/campaigns/{id}/pause

  • 캠페인 업데이트: PATCH /api/v2/campaigns/{id}

• 이메일 :

  • 이메일에 답장: POST /api/v2/emails/reply

  • 이메일 목록: GET /api/v2/emails

  • 이메일 받기: GET /api/v2/emails/{id}

  • 읽지 않은 이메일 개수 세기: GET /api/v2/emails/unread/count

• 계정 관리 :

  • 이제 이 엔드포인트를 MCP 서버에서 도구로 사용할 수 있습니다! 아래 "계정 관리 도구" 섹션을 참조하세요.

• 이메일 확인 :

  • 이메일 확인: POST /api/v2/email-verification

• 리드 목록 :

  • 목록 생성: POST /api/v2/lead-lists

  • 리드 목록 나열: GET /api/v2/lead-lists

사용 가능한 모든 엔드포인트에 대한 전체 참조는 Instantly API Explorer를 참조하세요.

설정

API 키

Instantly 계정 설정에서 Instantly API 키를 받으세요.

1. Instantly 대시보드에서 통합으로 이동하세요

2. 왼쪽 사이드바에서 "API 키" 섹션을 클릭하세요.

3. "API 키 생성" 버튼을 클릭하세요

4. API 키의 이름을 입력하세요

5. 이 키가 액세스할 수 있는 범위를 선택하세요.

6. API 키를 생성하고 복사하세요(참고: 한 번만 표시됩니다)

Claude Desktop과 함께 사용

claude_desktop_config.json 에 다음을 추가하세요.

도커

엔피엑스

짓다

Docker 빌드:

입증

Instantly API v2는 Bearer 토큰 인증을 사용합니다. API 키는 모든 요청의 Authorization 헤더에 포함되어야 합니다.

환경 변수를 통해 API 키를 제공하면 MCP 서버가 이를 자동으로 처리합니다.

특허

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 약관에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.

계정 관리 도구

이 MCP 서버는 계정 관리를 위해 다음 도구를 구현합니다.

1. instantly_create_account

   • API 엔드포인트 : POST /api/v2/accounts

   • Instantly에서 새 이메일 계정을 만드세요

   • 입력:

     • email (문자열): 계정의 이메일 주소

     • first_name (문자열): 계정과 연결된 이름

     • last_name (문자열): 계정과 연결된 성

     • provider_code (숫자): 공급자 코드(1: 사용자 지정 IMAP/SMTP, 2: Google, 3: Microsoft, 4: AWS)

     • imap_username (문자열): IMAP 사용자 이름

     • imap_password (문자열): IMAP 비밀번호

     • imap_host (문자열): IMAP 호스트(예: imap.gmail.com)

     • imap_port (숫자): IMAP 포트(예: 993)

     • smtp_username (문자열): SMTP 사용자 이름

     • smtp_password (문자열): SMTP 비밀번호

     • smtp_host (문자열): SMTP 호스트(예: smtp.gmail.com)

     • smtp_port (숫자): SMTP 포트(예: 587)

     • daily_limit (선택적 숫자): 일일 이메일 전송 제한

     • tracking_domain_name (선택 문자열): 추적 도메인 이름

2. instantly_list_accounts

   • API 엔드포인트 : GET /api/v2/accounts

   • 자동 페이지 매김 기능으로 즉시 이메일 계정 나열

   • 입력:

     • limit (선택적 숫자): 페이지당 반환할 계정 수(최대 100개, 기본값 10개)

     • starting_after (선택적 문자열): 이전 페이지의 마지막 항목 ID - 페이지 매김에 사용됨

     • search (선택 문자열): 계정을 필터링할 검색어

     • status (선택적 숫자): 상태 필터(1: 활성, 2: 일시 중지, -1: 연결 오류, -2: 소프트 바운스 오류, -3: 전송 오류)

     • provider_code (선택적 숫자): 공급자 코드 필터(1: 사용자 지정 IMAP/SMTP, 2: Google, 3: Microsoft, 4: AWS)

     • fetch_all (선택 사항, 부울): 모든 페이지를 자동으로 가져와서 포괄적인 요약을 제공할지 여부입니다. 이 옵션을 사용하여 모든 계정에 대한 정보를 가져올 수 있습니다.

   • 쪽수 매기기:

     • 기본 동작: 다음 페이지에 대한 링크가 포함된 단일 페이지 결과를 반환합니다.

     • fetch_all=true : 모든 페이지를 자동으로 가져와서 다음을 포함한 모든 계정의 포괄적인 요약을 반환합니다.

       • 총 계정 수

       • 제공자별 계정 분포

       • 상태별 계정 분포

       • 참고용 계정 샘플

3. instantly_get_account

   • API 엔드포인트 : GET /api/v2/accounts/{email}

   • Instantly에서 특정 이메일 계정의 세부 정보를 얻으세요

   • 입력: email (문자열): 검색할 계정의 이메일 주소

4. instantly_update_account

   • API 엔드포인트 : PATCH /api/v2/accounts/{email}

   • Instantly에서 기존 이메일 계정 업데이트

   • 입력:

     • email (문자열): 업데이트할 계정의 이메일 주소

     • first_name (선택적 문자열): 계정과 관련된 이름

     • last_name (선택적 문자열): 계정과 연결된 성

     • daily_limit (선택적 숫자): 일일 이메일 전송 제한

     • tracking_domain_name (선택 문자열): 추적 도메인 이름

     • skip_cname_check (선택적 부울): 추적 도메인에 대한 CNAME 확인을 건너뛸지 여부

     • remove_tracking_domain (선택적 부울): 계정에서 추적 도메인을 제거할지 여부

5. instantly_delete_account

   • API 엔드포인트 : DELETE /api/v2/accounts/{email}

   • 즉시 이메일 계정 삭제

   • 입력: email (문자열): 삭제할 계정의 이메일 주소

6. instantly_pause_account

   • API 엔드포인트 : POST /api/v2/accounts/{email}/pause

   • 즉시 이메일 계정 일시 중지

   • 입력: email (문자열): 일시 중지할 계정의 이메일 주소

7. instantly_resume_account

   • API 엔드포인트 : POST /api/v2/accounts/{email}/resume

   • 일시 중지된 이메일 계정을 즉시 재개합니다.

   • 입력: email (문자열): 재개할 계정의 이메일 주소

도구 테스트 상태

이 MCP 서버에 구현된 모든 도구가 Instantly API v2에서 제대로 작동하는지 확인하기 위해 철저한 테스트를 거쳤습니다. 테스트 진행 상황은 다음과 같습니다.

테스트 프로세스와 결과에 대한 자세한 내용은 저장소의 Testing.md를 참조하세요.

알려진 문제

• instantly_list_leads 도구는 현재 특정 이메일 필터 없이 리드를 나열하려고 할 때 "잘못된 이메일 주소" API 오류를 반환합니다. 이 문제를 해결하기 위해 다음을 포함한 여러 가지 방법을 시도해 보았습니다.

  • 이메일 검색을 위한 contacts 배열 매개변수 사용

  • 빈 요청 본문으로 자동 재시도 구현

  • 다양한 매개변수 서식 접근 방식 우리는 향후 릴리스에서 이 문제를 해결하기 위해 계속 노력할 것입니다.

개발을 위한 설정

이 프로젝트에 기여하거나 개발을 위해 로컬로 실행하고 싶다면:

1. 저장소를 복제합니다.

   git clone https://github.com/bcharleson/Instantly-MCP.git cd Instantly-MCP

2. 종속성 설치:

   npm install

3. Instantly API 키로 루트 디렉토리에 .env 파일을 만듭니다.

   INSTANTLY_API_KEY=your_api_key_here

   ⚠️ 중요 : .env 파일이나 API 키를 버전 관리 시스템에 커밋하지 마세요. .env 파일은 실수로 커밋되는 것을 방지하기 위해 .gitignore 파일에 포함됩니다.

4. 프로젝트를 빌드하세요:

   npm run build

5. 서버를 실행합니다:

   node dist/index.js

기여하다

참여를 환영합니다! 참여하고 싶으신 분은 다음과 같습니다.

1. 저장소를 포크하세요

2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )

3. 변경 사항을 만드세요

4. 변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )

5. 브랜치에 푸시( git push origin feature/amazing-feature )

6. 풀 리퀘스트 열기

풀 리퀘스트를 제출하기 전에 다음 사항을 확인하세요.

• 귀하의 코드는 프로젝트의 코딩 스타일을 따릅니다.

• 새로운 기능에 대한 테스트를 추가했습니다.

• 모든 테스트 통과

• 필요한 경우 문서를 업데이트했습니다.