DI3 Mail API 소개 시작하기 인증 모든 API 요청에 Authorization 헤더가 필요합니다.
API Key는 회사 관리자가 대시보드의 API 키 메뉴(/dashboard/api-keys)에서 직접 발급·재발급할 수 있습니다.
메일 발송 POST /api/v1/send
요청을 접수하면 즉시 jobId가 반환되고, 실제 발송은 접수 순서대로 이어서 진행됩니다(결과는 발송 상태 조회로 확인). 접수 전에 발송 한도를 먼저 확인하므로, 한도를 넘는 요청은 429로 거절됩니다.
요청 파라미터 파라미터 타입 필수 설명 from string O 발신 메일 주소 또는 RFC 형식 ("이름" <주소>) fromName string - 보낸사람 표시 이름 (예: "홍길동") to string | string[] O 수신자 (배열 또는 콤마 구분 문자열) cc string | string[] - 참조 (Carbon Copy) bcc string | string[] - 숨은참조 (Blind Carbon Copy) subject string O 메일 제목 html string * HTML 본문 (html 또는 text 중 하나 필수) text string * 텍스트 본문 replyTo string - 회신 주소 notifyEmail string - 발송 실패(반송) 시 실패 내용을 통보받을 이메일 (미입력 시 추가 통보 없음) individualSend boolean - 개별 발송 — true면 to/cc/bcc를 합쳐 각 수신자에게 따로 발송(수신자끼리 주소 미노출). 한 번에 최대 50명, 한도는 수신자 수만큼 차감 attachments array - 첨부파일 목록 (아래 참조)
attachments 객체 필드 타입 설명 filename string 파일명 (예: report.pdf) content string base64 인코딩된 파일 내용 contentType string MIME 타입 (예: 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 쿼리 파라미터가 필요합니다.
엔드포인트 목록 Method Path 설명 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 잘못된 요청 (필수 파라미터 누락, 잘못된 형식 등) 403 API 키 인증 실패, 비활성 키, 만료된 키, 구독 정지 404 리소스를 찾을 수 없음 (메일, 메일함 등) 429 발송 한도 초과 (시간당 또는 일일) 500 서버 내부 오류
API Key 발급은 대시보드 > API 키 메뉴에서 할 수 있습니다. 그 밖의 문의는 support@di3.kr로 연락해주세요.