DI3 Mail 메일 발송 API 문서

API Key를 사용하여 메일을 발송하고 수신 메일을 조회할 수 있습니다. API 소개 보기 · OpenAPI 명세(JSON)

인증

모든 API 요청에 Authorization 헤더가 필요합니다.

API Key는 회사 관리자가 대시보드의 API 키 메뉴(/dashboard/api-keys)에서 직접 발급·재발급할 수 있습니다.

메일 발송

POST/api/v1/send

요청을 접수하면 즉시 jobId가 반환되고, 실제 발송은 접수 순서대로 이어서 진행됩니다(결과는 발송 상태 조회로 확인). 접수 전에 발송 한도를 먼저 확인하므로, 한도를 넘는 요청은 429로 거절됩니다.

요청 파라미터

파라미터타입필수설명
fromstringO발신 메일 주소 또는 RFC 형식 ("이름" <주소>)
fromNamestring-보낸사람 표시 이름 (예: "홍길동")
tostring | string[]O수신자 (배열 또는 콤마 구분 문자열)
ccstring | string[]-참조 (Carbon Copy)
bccstring | string[]-숨은참조 (Blind Carbon Copy)
subjectstringO메일 제목
htmlstring*HTML 본문 (html 또는 text 중 하나 필수)
textstring*텍스트 본문
replyTostring-회신 주소
notifyEmailstring-발송 실패(반송) 시 실패 내용을 통보받을 이메일 (미입력 시 추가 통보 없음)
individualSendboolean-개별 발송 — true면 to/cc/bcc를 합쳐 각 수신자에게 따로 발송(수신자끼리 주소 미노출). 한 번에 최대 50명, 한도는 수신자 수만큼 차감
attachmentsarray-첨부파일 목록 (아래 참조)

attachments 객체

필드타입설명
filenamestring파일명 (예: report.pdf)
contentstringbase64 인코딩된 파일 내용
contentTypestringMIME 타입 (예: application/pdf)

요청 예시

curl -X POST https://mail.di3.kr/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "info@example.com",
    "fromName": "홍길동",
    "to": ["recipient1@example.com", "recipient2@example.com"],
    "cc": ["manager@example.com"],
    "subject": "안녕하세요",
    "html": "<h1>제목</h1><p>본문 내용입니다.</p>",
    "replyTo": "reply@example.com",
    "notifyEmail": "alert@example.com"
  }'
notifyEmail (반송 알림): 수신자 주소 오류·스팸 차단 등으로 발송이 즉시 거부되어 반송될 경우, 해당 실패 내용을 이 주소로도 이메일 발송해 드립니다. 선택 필드이며, 넣지 않으면 추가 통보는 보내지 않습니다. (상대 서버가 일단 수신 후 지연 반송하거나 스팸함으로 조용히 분류하는 경우는 감지되지 않습니다.)
individualSend (개별 발송): true로 보내면 to/cc/bcc를 모두 합쳐 각 수신자에게 한 통씩 개별 발송하며, 각 메일의 받는사람에는 본인 주소만 표시되어 수신자끼리 서로의 주소를 볼 수 없습니다. 한 번에 최대 50명까지 지정할 수 있고, 발송 한도는 실제 수신자 수만큼 차감됩니다. 넣지 않거나 false면 모든 수신자에게 한 통으로 발송됩니다.

첨부파일 포함 예시

curl -X POST https://mail.di3.kr/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "info@example.com",
    "to": ["recipient@example.com"],
    "subject": "첨부파일 테스트",
    "html": "<p>첨부파일을 확인해주세요.</p>",
    "attachments": [
      {
        "filename": "report.pdf",
        "content": "BASE64_ENCODED_CONTENT",
        "contentType": "application/pdf"
      }
    ]
  }'
base64 변환: Linux/Mac에서 base64 -i file.pdf 명령으로 변환할 수 있습니다.

응답

// 접수 성공 (200)
{
  "success": true,
  "jobId": "123",
  "status": "queued",
  "message": "발송 요청이 접수되었습니다."
}

// 검증 실패 (400)
{ "statusCode": 400, "message": "에러 메시지" }

// 인증 실패 (403)
{ "statusCode": 403, "message": "유효하지 않은 API 키입니다." }

// 한도 초과 (429)
{ "statusCode": 429, "message": "시간당 발송 한도를 초과했습니다." }

발송 상태 조회

GET/api/v1/send/status/:jobId
curl https://mail.di3.kr/api/v1/send/status/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

응답

{
  "jobId": "123",
  "status": "completed",       // waiting | active | completed | failed
  "result": {
    "success": true,
    "messageId": "72"
  },
  "attempts": 1,
  "maxAttempts": 3
}
실패 시 자동으로 최대 3회 재시도됩니다. status가 failed인 경우 failedReason에 오류 내용이 포함됩니다.

메일 수신 (조회)

IMAP/POP3 포트 없이 HTTPS만으로 메일을 조회할 수 있습니다. 모든 요청에 email 쿼리 파라미터가 필요합니다.

엔드포인트 목록

MethodPath설명
GET/api/v1/accounts접근 가능한 메일 계정 목록
GET/api/v1/mailboxes?email=...메일함 목록 (INBOX, Sent Mail 등)
GET/api/v1/messages?email=...&mailbox=...&page=1&limit=20메일 목록 (페이징, unseen 필터)
GET/api/v1/messages/:mailboxId/:messageId?email=...메일 상세 (본문, 첨부 목록)
GET/api/v1/messages/:mailboxId/:messageId/attachments/:attId?email=...첨부파일 다운로드
DELETE/api/v1/messages/:mailboxId/:messageId?email=...메일 삭제
GET/api/v1/send/status/:jobId발송 작업 상태 조회

메일 목록 조회 예시

# 받은편지함 최신 20건
curl "https://mail.di3.kr/api/v1/messages?email=info@example.com&mailbox=INBOX&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 안 읽은 메일만
curl "https://mail.di3.kr/api/v1/messages?email=info@example.com&mailbox=INBOX&unseen=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

메일 상세 조회 예시

# mailboxId, messageId는 목록 조회 응답에서 확인
curl "https://mail.di3.kr/api/v1/messages/{mailboxId}/{messageId}?email=info@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

첨부파일 다운로드

curl -o file.pdf \
  "https://mail.di3.kr/api/v1/messages/{mailboxId}/{messageId}/attachments/{attachmentId}?email=info@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

웹훅 (새 메일·수신 확인 알림)

새 메일이 도착하거나 내가 보낸 메일을 상대가 열면, 등록해 둔 곳으로 알림을 보냅니다. API 키가 아니라 각 사용자가 웹메일의 메일 설정 > 웹훅에서 등록하며, 그 사용자의 기본 메일 계정 기준으로 동작합니다.

항목내용
보낼 곳HTTP 주소, Telegram, Discord, Notion 데이터베이스
이벤트new_mail (새 메일 도착), read_receipt (수신 확인을 켜고 보낸 메일을 상대가 열람)
등록 개수메일 계정당 최대 10개
HTTP 요청POST (PUT·PATCH 선택 가능), Content-Type: application/json
응답 대기10초 안에 2xx로 응답하지 않으면 실패로 처리하며, 다시 보내지 않습니다

HTTP 웹훅 본문 예시 — new_mail

{
  "event": "new_mail",
  "payload": {
    "from": "customer@example.com",
    "to": "info@company.co.kr",
    "subject": "견적 문의드립니다",
    "preview": "안녕하세요. 견적을 받고 싶어...",
    "date": "2026-11-04T09:30:00.000Z",
    "mailbox": "메일함 ID"
  },
  "timestamp": "2026-11-04T09:30:01.000Z"
}

HTTP 웹훅 본문 예시 — read_receipt

{
  "event": "read_receipt",
  "payload": {
    "subject": "견적서 보내드립니다",
    "email": "customer@example.com",
    "openedAt": "2026-11-04T10:12:00.000Z"
  },
  "timestamp": "2026-11-04T10:12:00.500Z"
}
요청에 서명은 붙지 않습니다. 받는 쪽에서 우리 서비스가 보낸 요청인지 가리려면, 웹훅 주소에 추측하기 어려운 값을 넣어 두고 (예: https://example.com/hooks/긴-무작위-값) 그 주소로 온 요청만 받도록 하세요.

제한 사항

항목제한
수신자 (to + cc + bcc)최대 50명
첨부파일 개수최대 10개
첨부파일 크기 (개별)25MB
첨부파일 크기 (전체)50MB
발송 한도업체별 설정 (시간당/일일)
구독 상태미결제/정지/만료 시 API 사용 불가
발송 한도: 웹에서 보내는 메일과 API로 보내는 메일은 동일한 카운터를 공유합니다. 한도 변경이 필요한 경우 담당자에게 문의하세요.

에러 코드

코드설명
400잘못된 요청 (필수 파라미터 누락, 잘못된 형식 등)
403API 키 인증 실패, 비활성 키, 만료된 키, 구독 정지
404리소스를 찾을 수 없음 (메일, 메일함 등)
429발송 한도 초과 (시간당 또는 일일)
500서버 내부 오류
API Key 발급은 대시보드 > API 키 메뉴에서 할 수 있습니다. 그 밖의 문의는 support@di3.kr로 연락해주세요.
홈API 소개이용약관개인정보처리방침