시작하기

guide — 온보딩/사용법 안내 ★ 먼저 호출

처음 사용 시 가장 먼저 호출하는 도구입니다. 도구 목록, 요금, 발송 흐름을 주제별로 안내합니다.

{
  "topic": "all"  // all | sms | email | mms | alimtalk | image | pricing | report (기본: all)
}

💰 무료

send_sms — 단문 문자 발송

90자 이내의 단문 문자(SMS)를 발송합니다.

{
  "receiver": "01012345678",  // 수신번호
  "message": "안녕하세요, 내일 오전 10시 미팅입니다.",  // 최대 90자
  "sender": "01012345678"  // 선택 — 승인된 발신번호 중 선택(get_sender 조회). 미지정 시 기본 발신번호
}

💰 단가: 17원/건

send_lms — 장문 문자 발송

2,000자 이내의 장문 문자(LMS)를 발송합니다.

{
  "receiver": "01012345678",
  "message": "안녕하세요.\n\n이번 행사 안내를 드립니다.\n...",  // 최대 2000자
  "title": "7월 행사 안내",  // 선택 — LMS 제목(수신 단말에 표시, 최대 120자). 미지정 시 제목 없이 발송
  "sender": "01012345678"  // 선택 — 승인된 발신번호 중 선택(get_sender 조회). 미지정 시 기본 발신번호
}

💰 단가: 40원/건

send_bulk — 대량 문자 발송

여러 수신자에게 동일한 문자를 한 번에 발송합니다.

{
  "receivers": ["01012345678", "01087654321", "01099998888"],
  "message": "공지 내용입니다.",
  "type": "SMS",  // "SMS" 또는 "LMS"
  "title": "공지",  // 선택 — type=LMS일 때만 적용되는 LMS 제목. 미지정 시 제목 없이 발송
  "sender": "01012345678"  // 선택 — 승인된 발신번호 중 선택(get_sender 조회). 미지정 시 기본 발신번호
}

💰 단가: 타입에 따라 건당 동일 요금

send_bulk_template — 대량 개인화 발송 ★ #{변수} 치환

수신자별로 #{변수명}을 실제 값으로 치환해 개인화된 문자를 한 번에 발송합니다. 예: template="#{이름} #{직함}님 안녕하세요" + 수신자별 vars. 최대 500명까지 지원하며, 필요한 변수가 누락된 수신자는 발송 없이 자동 스킵됩니다(임의로 빈 값 치환하지 않음).

파라미터

{
  "recipients": [
    { "phone": "01012345678", "vars": { "이름": "김철수", "직함": "과장" } },
    { "phone": "01087654321", "vars": { "이름": "이영희", "직함": "대리" } }
  ],
  "template": "#{이름} #{직함}님 안녕하세요. 다음 주 회의 일정 안내드립니다.",
  "type": "SMS",
  "dry_run": true
}

{
  "dryRun": true,
  "발송예정": 2,
  "스킵": [ { "phone": "010****5678", "reason": "MISSING_VARS", "missing": ["직함"] } ],
  "LMS승격": 0,
  "예상비용": "34원",
  "샘플": ["김철수 과장님 안녕하세요...", "이영희 대리님 안녕하세요..."]
}

💰 단가: 채널별 건당 요금 적용 (SMS 17원 / LMS 40원, 자동 승격분은 LMS 단가)

create_bulk_upload_session — 대량 개인화 발송 파일 업로드 세션

수신자 목록(전화번호 + 변수 열)이 담긴 CSV/XLSX 파일을 브라우저에서 업로드받기 위한 세션을 생성합니다. 파라미터는 없습니다. 발급된 링크는 30분간 유효하며, 첫 행을 헤더로 인식하고 전화번호/휴대폰/휴대전화/phone/mobile(대소문자 무관) 중 하나의 열 이름을 자동으로 전화번호 열로 인식합니다. 파일은 최대 5MB, 최대 10,000행까지 지원합니다.

// 파라미터 없음 — 그대로 호출
{}
// 응답
{
  "sessionId": "...",
  "uploadUrl": "https://mcp.imsend.kr/mcp/bulk-upload/{token}",
  "expiresIn": 1800,
  "안내": "위 링크를 열어 전화번호 열이 포함된 CSV/XLSX 파일을 업로드하세요(최대 5MB, 10000행). 업로드 완료 후 get_bulk_upload_session_status로 확인 → send_bulk_from_session으로 발송하세요."
}

전체 흐름

# 1단계: AI가 업로드 세션 생성
create_bulk_upload_session()
→ { sessionId, uploadUrl, expiresIn: 1800 }

# 2단계: AI가 사용자에게 업로드 링크 안내
"이 링크에서 전화번호 목록 파일을 업로드해주세요: [uploadUrl]"

# 3단계: 사용자가 브라우저에서 CSV/XLSX 업로드
→ 서버가 헤더 행 파싱 + 전화번호 열 자동 인식

# 4단계: AI가 업로드 상태 확인
get_bulk_upload_session_status(sessionId)
→ { uploaded: true, columns: [...], rowCount: 120, phoneColumn: "전화번호", sampleRows: [...] }

# 5단계: 템플릿으로 발송
send_bulk_from_session(sessionId, template: "#{이름}님 안내드립니다")

💰 무료 (발송은 send_bulk_from_session 호출 시 채널별 단가 적용)

get_bulk_upload_session_status — 업로드 세션 상태 조회

create_bulk_upload_session이 발급한 세션의 업로드 완료 여부, 열 목록, 행 수, 전화번호로 인식된 열, 샘플 데이터를 확인합니다.

// 파라미터
{ "sessionId": "..." }  // create_bulk_upload_session이 발급한 세션 ID

// 업로드 전 응답
{ "uploaded": false, "sent": false }

// 업로드 완료 후 응답
{
  "uploaded": true,
  "columns": ["이름", "전화번호", "직함"],
  "rowCount": 120,
  "phoneColumn": "전화번호",
  "sampleRows": [ { "이름": "김철수", "전화번호": "01012345678", "직함": "과장" } ],
  "sent": false
}

💰 무료

send_bulk_from_session — 업로드 세션으로 개인화 대량 발송

업로드된 파일의 각 행을 수신자로 사용해 #{열이름} 치환 방식으로 개인화 발송합니다. 먼저 create_bulk_upload_session/get_bulk_upload_session_status로 업로드를 확인하세요. 응답 형식은 send_bulk_template과 동일합니다. 같은 세션으로 재발송은 불가합니다(1세션 1회 발송, 이중발송 방지).

파라미터

{
  "sessionId": "...",
  "template": "#{이름}님, #{직함}님께 안내드립니다.",
  "type": "SMS"
}

💰 단가: 채널별 건당 요금 적용 (SMS 17원 / LMS 40원, 자동 승격분은 LMS 단가)

send_mms — MMS 이미지 문자 발송

서버에 업로드된 이미지 경로(imagePath)로 MMS를 발송합니다. 이미지는 JPG/PNG/GIF 형식, 최대 2MB까지 지원합니다. 먼저 get_upload_url 또는 send_mms_upload로 이미지를 업로드해 savedPath를 받은 뒤 호출합니다.

{
  "receiver": "01012345678",
  "message": "이미지와 함께 발송하는 MMS입니다.",
  "imagePath": "/opt/imsend/uploads/mms/1700000000_photo.jpg"
}

💰 단가: 90원/건

send_mms_now — Base64 MMS 통합 발송

Base64 이미지를 1번 호출로 업로드+발송합니다. 파일 없이 즉시 보낼 때 사용하며, Claude.ai 본문에서 안정적입니다(GPT 환경은 truncation 주의). 서버에서 자동 640px 리사이즈 + JPG 변환합니다.

{
  "receiver": "01012345678",
  "message": "이미지 보내드립니다.",
  "imageBody": "Base64인코딩값",  // JPG/PNG/GIF, 최대 2MB
  "imageName": "photo.jpg",       // 선택 (기본: image.jpg)
  "sender": "01012345678"         // 선택 — 승인된 발신번호 중 선택(get_sender 조회)
}

💰 단가: 90원/건

send_mms_upload — Base64 이미지 업로드 구버전

Base64 이미지를 서버에 업로드하고 savedPath/imageUrl을 반환합니다. 반환된 savedPath를 send_mms의 imagePath로 사용합니다. ⚠️ GPT 환경에서 truncation이 발생할 수 있어 send_mms_now 또는 업로드 세션 방식을 권장합니다.

{
  "imageBody": "Base64인코딩값",  // JPG/PNG/GIF, 최대 2MB
  "imageName": "photo.jpg"        // 선택 (기본: image.jpg)
}

💰 무료 (발송은 send_mms 단가 적용)

get_upload_url — Pre-signed 업로드 URL 발급

MMS 이미지 또는 이메일 본문 이미지를 업로드할 URL을 발급합니다. AI가 curl/requests로 직접 binary 업로드하므로 Base64 방식보다 빠르고 대용량에 적합합니다.

📱 MMS 이미지 업로드 (3단계)

# 1단계: 업로드 URL 발급 (send_mms 도구 사용)
get_upload_url(type="mms", fileName="photo.jpg")
# → uploadUrl, savedPath 반환

# 2단계: AI가 직접 이미지 PUT 업로드 (bash)
curl -X PUT "https://mcp.imsend.kr/mcp/upload/{token}" \
     --data-binary @photo.jpg \
     -H "Content-Type: application/octet-stream"
# 또는 Python
# import requests
# requests.put(uploadUrl, data=open('photo.jpg','rb'), headers={'Content-Type':'application/octet-stream'})

# 3단계: MMS 발송
send_mms(receiver="01012345678", message="이미지 발송", imagePath="{savedPath}")

📧 이메일 본문 이미지 업로드 (3단계)

# 1단계: 업로드 URL 발급
get_upload_url(type="email", fileName="banner.png")
# → uploadUrl, savedPath, imageUrl 반환

# 2단계: 이미지 PUT 업로드
curl -X PUT "https://mcp.imsend.kr/mcp/upload/{token}" \
     --data-binary @banner.png \
     -H "Content-Type: application/octet-stream"

# 3단계: 이메일 발송 (imageUrl을 본문에 삽입)
send_email(to="user@example.com", subject="...", content="<img src='https://imsend.kr/uploads/email/...'>")

🔄 환경별 권장 업로드 방식

💰 무료 (발송 시 해당 도구 단가 적용)

get_image_upload_url — 이미지 업로드 페이지 URL 발급 ★ 권장

사용자가 브라우저에서 직접 이미지를 올릴 수 있는 전용 업로드 페이지를 발급합니다. Base64 변환 없이 MMS/이메일 이미지를 처리하는 권장 방식입니다. Claude웹·ChatGPT웹·모바일 모든 환경에서 동작합니다.

파라미터

반환값

{
  "uploadPageUrl": "https://mcp.imsend.kr/mcp/image-upload/{token}",
  "token": "{token}",
  "expiresIn": "15분",
  "instruction": "아래 URL을 사용자에게 안내하세요. 업로드 완료 후 check_upload_status를 호출하세요.",
  "nextStep": "check_upload_status(token)"
}

전체 흐름 (MMS 예시)

# 1단계: 업로드 링크 발급
get_image_upload_url(type="mms")
→ uploadPageUrl: "https://mcp.imsend.kr/mcp/image-upload/abc123"

# 2단계: 사용자에게 안내
"이미지를 여기서 업로드해주세요 (15분 유효):
 https://mcp.imsend.kr/mcp/image-upload/abc123"

# 3단계: 사용자가 링크 클릭 → 파일 선택 → 업로드

# 4단계: 업로드 완료 확인
check_upload_status(token="abc123")
→ { done: true, imageUrl: "https://imsend.kr/uploads/mms/xxx.jpg" }

# 5단계: MMS 발송
send_mms_from_url(receiver="01012345678", message="이미지 발송", imageUrl="https://imsend.kr/uploads/mms/xxx.jpg")

🤖 ChatGPT 환경 (Python container)

# 1단계: get_image_upload_url(type="mms") 로 token 발급
# 2단계: ChatGPT Python container에서 실행
import requests
files = {"file": open("/mnt/data/photo.jpg", "rb")}
r = requests.post(
    "https://mcp.imsend.kr/mcp/image-upload/{token}",  # token 교체
    files=files
)
result = r.json()
# result: {"success": true, "imageUrl": "https://imsend.kr/uploads/mms/xxx.jpg"}

# 3단계: MCP 도구 호출
# send_mms_from_url(receiver="01012345678", message="발송내용", imageUrl=result["imageUrl"])

check_upload_status — 업로드 완료 확인

get_image_upload_url 발급 후 사용자가 이미지를 업로드했는지 확인합니다. 완료 시 imageUrl을 반환합니다.

파라미터

반환값 예시

// 완료 시
{ "done": true, "imageUrl": "https://imsend.kr/uploads/mms/xxx.jpg", "fileName": "photo.jpg", "fileSize": 512000 }

// 대기 중
{ "done": false, "message": "아직 업로드 중입니다. 잠시 후 다시 확인하세요." }

// 만료
{ "done": false, "expired": true, "message": "토큰이 만료됐거나 존재하지 않습니다." }

send_mms_from_url — URL로 MMS 발송 ★ 권장

이미지 URL로 MMS를 발송합니다. check_upload_status에서 받은 imageUrl 또는 공개 이미지 URL을 사용합니다. Base64 없음.

파라미터

send_mms_from_url(
  receiver="01012345678",
  message="이미지 보내드립니다.",
  imageUrl="https://imsend.kr/uploads/mms/1234567890_photo.jpg"
)

send_email — 이메일 발송

HTML을 지원하는 이메일을 발송합니다. 파일 첨부도 지원합니다.

// 기본 발송
{
  "to": "user@example.com",
  "subject": "이메일 제목",
  "content": "<h1>안녕하세요</h1><p>이메일 내용입니다.</p>"
}

// 파일 첨부 발송
{
  "to": "user@example.com",
  "subject": "첨부파일 포함 이메일",
  "content": "<p>파일을 첨부했습니다.</p>",
  "attachments": [
    { "fileName": "report.pdf", "fileBody": "JVBERi0xLjQ..." }
  ]
}

💰 단가: 1.5원/건

send_email_now — 이메일 통합 발송 (본문 이미지 1-step) ★ 권장

Base64 이미지 1번 전달로 본문 자동 삽입 후 이메일을 발송합니다. content에 {{IMAGE_URL}} 플레이스홀더를 두면 그 위치에, 없으면 본문 하단에 자동 삽입됩니다. 이미지 없이 텍스트만 보내도 됩니다.

{
  "to": "user@example.com",
  "subject": "이미지 포함 이메일",
  "content": "<p>본문입니다.</p>{{IMAGE_URL}}",
  "imageBody": "Base64값",
  "imageName": "banner.jpg"
}

💰 단가: 1.5원/건

create_mms_upload_session — MMS 자동발송 세션 ★★ 전 환경 1순위

MMS 이미지 발송을 위한 자동발송 세션을 생성합니다. 업로드 링크를 사용자에게 안내하면, 사용자가 이미지를 업로드하는 즉시 서버가 자동으로 MMS를 발송하고 페이지에서 결과를 표시합니다. AI 폴링 불필요 · Claude/GPT/모바일 통일

파라미터

전체 흐름

# 1단계: AI가 세션 생성
create_mms_upload_session(receiver="01012345678", message="이미지 보내드립니다")
→ { sessionId, uploadPageUrl, expiresIn: "15분" }

# 2단계: AI가 사용자에게 링크 안내
"이미지를 여기서 업로드해주세요: [링크]"

# 3단계: 사용자가 링크 클릭 → 이미지 선택 → 업로드
→ 서버: PNG/WEBP → JPG 640px 자동 변환
→ 서버: MMS 자동 발송
→ 페이지: "✅ 문자 전송이 완료되었습니다!" 표시 → 자동 닫힘(PC) / 닫기 버튼(모바일)

# 4단계 (선택): AI가 결과 확인
get_mms_upload_session_status(sessionId)
→ { uploaded: true, sendStatus: "DELIVERED", mseq: 12345 }

💰 단가: 90원/건

create_image_upload_session — curl 자동화 업로드 세션 ★ bash 자동화

Claude Desktop 등 bash 실행 환경에서 로컬 파일을 curl -F로 업로드하기 위한 세션을 생성합니다. 응답의 curl 명령으로 업로드한 뒤 send_mms_from_session으로 발송합니다(사람/브라우저 개입 불필요).

// 파라미터
{ "receiver": "01012345678", "message": "이미지 보내드립니다." }
// 응답
{ "session_id": "...", "upload_url": "...", "curl": "curl -F \"file=@/path/to/image.jpg\" \"...\"", "expires_in": 900 }

💰 무료 (발송은 MMS 90원/건 적용)

send_mms_from_session — 세션으로 MMS 발송

create_image_upload_session의 session_id로 업로드된 이미지를 MMS 발송합니다. 중복 호출해도 1회만 발송됩니다(idempotent). wait/wait_timeout_sec로 발송 결과까지 대기할 수 있습니다.

{
  "session_id": "...",          // create_image_upload_session의 session_id
  "wait": true,                  // 선택, true면 60초 대기(별칭)
  "wait_timeout_sec": 60,         // 선택, 0=즉시반환 (1~110, 초과 시 110 클램프)
  "sender": "01012345678"         // 선택 — 승인된 발신번호 중 선택(get_sender 조회)
}

💰 단가: 90원/건

get_mms_upload_session_status — 세션 발송 결과 조회

create_mms_upload_session 이후 업로드/발송 상태를 폴링합니다. uploaded, sendStatus, mseq를 반환합니다.

{ "sessionId": "..." }  // create_mms_upload_session으로 발급받은 sessionId

💰 무료

send_alimtalk — 카카오 알림톡 발송

카카오톡을 통해 알림톡을 발송합니다. 카카오톡 미수신 시 LMS로 자동 대체 발송됩니다.

📋 MCP 공용 템플릿 미리보기

※ 템플릿은 카카오 심사 완료 후 사용 가능합니다. 현재 심사 진행 중.

💰 단가: 15원/건 (failover LMS 대체 발송 시에도 알림톡 단가 15원으로 차감. failover 활성 시 LMS 단가까지 잔액만 확인)

📋 MCP 공용 템플릿 변수 목록

Claude 웹 등 AI 클라이언트에서 템플릿변수를 바로 확인할 수 있도록 정리했습니다. JSON API: GET /api/v1/alimtalk/templates/public

JSON API 제공: GET https://imsend.kr/api/v1/alimtalk/templates/public — Claude 등 AI가 자동으로 읽어 변수명을 확인할 수 있습니다.

send_email_image_upload — 이메일 본문 이미지 업로드

이메일 본문에 삽입할 이미지를 서버에 업로드합니다. 반환된 imageUrl을 send_email의 content에 <img src="..."> 형태로 사용하세요.

// 1단계: 이미지 업로드
{ "imageBody": "Base64값", "imageName": "banner.jpg" }
// 응답
{ "imageUrl": "https://imsend.kr/uploads/email/2026/05/1234_banner.jpg" }

// 2단계: 이메일 본문에 삽입
{
  "to": "user@example.com",
  "subject": "이미지 포함 이메일",
  "content": "<p>본문입니다.</p><img src='https://imsend.kr/uploads/email/...' />"
}

※ 업로드된 이미지는 90일 후 자동 삭제됩니다.

💰 무료

check_balance — 잔여 포인트 조회

현재 잔여 포인트를 조회합니다.

// 파라미터 없음
// 응답 예시
{
  "balance": 4980,
  "available": 4680,
  "pendingReserved": 300,
  "unit": "KRW",
  "note": "available = 발송 가능액(명목잔액에서 결과 대기중 예약액 제외)"
}

실제 발송 가능 여부는 balance(명목잔액)가 아니라 available(가용잔액)로 판단됩니다. pendingReserved는 방금 발송해 아직 통신사 결과가 확정되지 않은 건에 대해 미리 잡아둔 예약액입니다.

💰 무료

get_history — 발송 이력 조회

최근 발송 이력을 조회합니다. 실패 건에는 error_code와 error_reason이 포함됩니다.

// 요청
{ "limit": 20 }

// 응답 예시 (성공)
{ "msg_type": "S", "receiver": "01012345678", "status": "DELIVERED", "unit_price": 10 }

// 응답 예시 (실패)
{ "msg_type": "S", "receiver": "01012345678", "status": "FAILED",
  "unit_price": 10, "error_code": "211", "error_reason": "수신거부 또는 번호 오류" }

💰 무료

get_result — 단건 발송 결과 조회

발송 시 반환된 mseq로 실시간 결과(DELIVERED/FAILED/사유)를 조회합니다.

{ "mseq": 19500 }  // send_sms/send_mms/send_alimtalk 발송 시 반환된 값

💰 무료

get_sender — 발신번호 조회

현재 기본 발신번호와 본인인증이 완료된 개인 발신번호(mySenders) 목록을 반환합니다. 파라미터는 없습니다.

// 응답 예시
{ "sender": "033-911-6510", "mySenders": [{ "phone": "01012345678", "verifiedAt": "..." }] }

💰 무료

register_sender_number — 개인 발신번호 등록 (NICE 본인확인)

NICE 본인확인으로 개인 발신번호를 등록합니다. 응답의 authUrl을 사용자에게 안내하고, 인증 완료 후 verify_sender_status로 결과를 확인합니다.

{ "phone": "01012345678" }  // 선택 (NICE 인증 결과와 일치해야 등록)
// 응답: { "sessionId": "...", "authUrl": "...", "expiresIn": ... }

💰 무료

verify_sender_status — 본인확인 상태 조회

register_sender_number 응답의 sessionId로 NICE 본인확인 진행 상태(VERIFIED/PENDING/FAILED/EXPIRED)를 폴링합니다.

{ "sessionId": "..." }  // register_sender_number 응답의 sessionId

💰 무료

charge_point — 포인트 충전 (카카오페이)

카카오페이 결제 링크(authUrl)를 생성합니다. 사용자가 링크를 열어 결제를 완료하면 포인트가 자동 적립됩니다. 모바일에서는 카카오톡 결제 화면으로 자동 연결됩니다.

{
  "amount": 10000  // 충전 금액: 5000, 10000, 30000 중 하나
}

// 응답
{
  "authUrl": "https://...",   // 카카오페이 결제 링크 — 사용자에게 안내
  "sessionId": "...",          // 충전 상태 조회용 (get_charge_status)
  "amount": 10000,
  "expiresIn": 900             // 결제 링크 유효시간(초)
}

📌 결제 완료 여부는 get_charge_status(sessionId) 또는 check_balance로 확인합니다.

💰 무료 (결제 금액만 청구)

get_charge_status — 카카오페이 충전 상태 조회

charge_point 응답의 sessionId로 결제 진행 상태를 폴링합니다. 결제 완료 시 적립 금액과 잔액이 반환됩니다.

{ "sessionId": "..." }  // charge_point 응답의 sessionId

💰 무료