{
  "openapi": "3.1.0",
  "info": {
    "title": "DI3 Mail API",
    "version": "1.0.0",
    "description": "회사 도메인 메일 계정으로 메일을 보내고, 받은 메일을 조회하는 REST API입니다. API 키는 회사 관리자가 대시보드의 API 키 메뉴에서 발급합니다. 결제 중인 회사에서만 쓸 수 있으며, 발송 한도는 웹에서 보내는 메일과 같은 회사 한도(시간당·일일)를 함께 씁니다. 사람이 읽는 문서: https://mail.di3.kr/api-docs",
    "contact": {
      "name": "DI3 Mail 고객센터",
      "email": "support@di3.kr",
      "url": "https://mail.di3.kr/developers"
    },
    "termsOfService": "https://mail.di3.kr/terms"
  },
  "externalDocs": {
    "description": "API 문서",
    "url": "https://mail.di3.kr/api-docs"
  },
  "servers": [
    {
      "url": "https://mail.di3.kr/api"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "발송",
      "description": "메일 보내기와 발송 상태 조회"
    },
    {
      "name": "수신",
      "description": "계정·메일함·메일·첨부파일 조회와 메일 삭제"
    }
  ],
  "paths": {
    "/v1/send": {
      "post": {
        "tags": [
          "발송"
        ],
        "operationId": "sendMail",
        "summary": "메일 보내기",
        "description": "요청을 접수하면 바로 jobId를 돌려주고, 발송은 접수 순서대로 이어서 진행됩니다. 결과는 발송 상태 조회로 확인합니다. 수신자(to+cc+bcc)는 최대 50명입니다. 접수 전에 발송 한도를 확인하며, 한도를 넘으면 429를 돌려줍니다.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMailRequest"
              },
              "example": {
                "from": "noreply@company.co.kr",
                "fromName": "우리회사",
                "to": "customer@example.com",
                "subject": "주문이 접수되었어요",
                "text": "주문해 주셔서 감사합니다."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "발송 요청 접수",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendMailResponse"
                },
                "example": {
                  "success": true,
                  "jobId": "1024",
                  "status": "queued",
                  "message": "발송 요청이 접수되었습니다."
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (필수 값 누락, 형식 오류, 접근할 수 없는 계정 등)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API 키가 없거나 유효하지 않음, 비활성·만료된 키, 결제·회사 상태로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "회사 발송 한도(시간당 또는 일일) 초과",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/send/status/{jobId}": {
      "get": {
        "tags": [
          "발송"
        ],
        "operationId": "getSendStatus",
        "summary": "발송 상태 조회",
        "description": "같은 회사의 API 키로 접수한 작업만 조회됩니다. 다른 회사의 작업은 없는 작업과 같이 404입니다.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "발송 요청 때 받은 jobId",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "작업 상태",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendStatus"
                },
                "example": {
                  "jobId": "1024",
                  "status": "completed",
                  "result": {
                    "success": true,
                    "messageId": "72"
                  },
                  "attempts": 1,
                  "maxAttempts": 3
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (필수 값 누락, 형식 오류, 접근할 수 없는 계정 등)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API 키가 없거나 유효하지 않음, 비활성·만료된 키, 결제·회사 상태로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "작업을 찾을 수 없음",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/accounts": {
      "get": {
        "tags": [
          "수신"
        ],
        "operationId": "listAccounts",
        "summary": "접근할 수 있는 메일 계정 목록",
        "responses": {
          "200": {
            "description": "메일 계정 목록",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "email": {
                        "type": "string",
                        "format": "email"
                      }
                    },
                    "required": [
                      "email"
                    ]
                  }
                },
                "example": [
                  {
                    "email": "info@company.co.kr"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (필수 값 누락, 형식 오류, 접근할 수 없는 계정 등)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API 키가 없거나 유효하지 않음, 비활성·만료된 키, 결제·회사 상태로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/mailboxes": {
      "get": {
        "tags": [
          "수신"
        ],
        "operationId": "listMailboxes",
        "summary": "메일함 목록",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "조회할 메일 계정 주소. API 키에 허용 주소가 정해져 있으면 그 주소만 쓸 수 있습니다.",
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "info@company.co.kr"
          }
        ],
        "responses": {
          "200": {
            "description": "메일함 목록",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Mailbox"
                  }
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (필수 값 누락, 형식 오류, 접근할 수 없는 계정 등)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API 키가 없거나 유효하지 않음, 비활성·만료된 키, 결제·회사 상태로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages": {
      "get": {
        "tags": [
          "수신"
        ],
        "operationId": "listMessages",
        "summary": "메일 목록",
        "description": "최신 메일부터 돌려줍니다.",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "조회할 메일 계정 주소. API 키에 허용 주소가 정해져 있으면 그 주소만 쓸 수 있습니다.",
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "info@company.co.kr"
          },
          {
            "name": "mailbox",
            "in": "query",
            "required": false,
            "description": "메일함 경로 또는 이름. 생략하면 INBOX",
            "schema": {
              "type": "string",
              "default": "INBOX"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "한 페이지 개수 (최대 100)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "unseen",
            "in": "query",
            "required": false,
            "description": "true면 읽지 않은 메일만",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "메일 목록",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageList"
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (필수 값 누락, 형식 오류, 접근할 수 없는 계정 등)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API 키가 없거나 유효하지 않음, 비활성·만료된 키, 결제·회사 상태로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "메일함을 찾을 수 없음",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/{mailboxId}/{messageId}": {
      "get": {
        "tags": [
          "수신"
        ],
        "operationId": "getMessage",
        "summary": "메일 상세 (본문·첨부 목록)",
        "parameters": [
          {
            "name": "mailboxId",
            "in": "path",
            "required": true,
            "description": "메일함 ID (메일 목록 응답의 mailboxId)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "description": "메일 ID (메일 목록 응답의 id)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "조회할 메일 계정 주소. API 키에 허용 주소가 정해져 있으면 그 주소만 쓸 수 있습니다.",
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "info@company.co.kr"
          }
        ],
        "responses": {
          "200": {
            "description": "메일 상세",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageDetail"
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (필수 값 누락, 형식 오류, 접근할 수 없는 계정 등)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API 키가 없거나 유효하지 않음, 비활성·만료된 키, 결제·회사 상태로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "메일을 찾을 수 없음",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "수신"
        ],
        "operationId": "deleteMessage",
        "summary": "메일 삭제",
        "parameters": [
          {
            "name": "mailboxId",
            "in": "path",
            "required": true,
            "description": "메일함 ID (메일 목록 응답의 mailboxId)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "description": "메일 ID (메일 목록 응답의 id)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "조회할 메일 계정 주소. API 키에 허용 주소가 정해져 있으면 그 주소만 쓸 수 있습니다.",
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "info@company.co.kr"
          }
        ],
        "responses": {
          "200": {
            "description": "삭제됨",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "success"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (필수 값 누락, 형식 오류, 접근할 수 없는 계정 등)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API 키가 없거나 유효하지 않음, 비활성·만료된 키, 결제·회사 상태로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/{mailboxId}/{messageId}/attachments/{attachmentId}": {
      "get": {
        "tags": [
          "수신"
        ],
        "operationId": "downloadAttachment",
        "summary": "첨부파일 내려받기",
        "parameters": [
          {
            "name": "mailboxId",
            "in": "path",
            "required": true,
            "description": "메일함 ID (메일 목록 응답의 mailboxId)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "messageId",
            "in": "path",
            "required": true,
            "description": "메일 ID (메일 목록 응답의 id)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "attachmentId",
            "in": "path",
            "required": true,
            "description": "메일 상세 응답의 attachments[].id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "조회할 메일 계정 주소. API 키에 허용 주소가 정해져 있으면 그 주소만 쓸 수 있습니다.",
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "info@company.co.kr"
          }
        ],
        "responses": {
          "200": {
            "description": "첨부파일 원본 (Content-Type은 파일 형식에 따름)",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "잘못된 요청 (필수 값 누락, 형식 오류, 접근할 수 없는 계정 등)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API 키가 없거나 유효하지 않음, 비활성·만료된 키, 결제·회사 상태로 사용 불가",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "대시보드에서 발급한 API 키. 요청 헤더에 Authorization: Bearer <API 키>"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer"
          },
          "message": {
            "type": "string"
          }
        },
        "example": {
          "statusCode": 429,
          "message": "시간당 발송 한도를 초과했습니다."
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "AddressInput": {
        "description": "주소 하나, 쉼표로 구분한 여러 주소, 또는 주소 배열",
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      },
      "Attachment": {
        "type": "object",
        "required": [
          "filename",
          "content",
          "contentType"
        ],
        "properties": {
          "filename": {
            "type": "string"
          },
          "content": {
            "type": "string",
            "description": "base64로 인코딩한 파일 내용"
          },
          "contentType": {
            "type": "string",
            "example": "application/pdf"
          }
        }
      },
      "SendMailRequest": {
        "type": "object",
        "required": [
          "from",
          "to",
          "subject"
        ],
        "description": "html 또는 text 중 하나는 반드시 넣어야 합니다.",
        "properties": {
          "from": {
            "type": "string",
            "description": "발신 주소. 회사에 등록된 메일 계정이어야 하며, \"이름 <주소>\" 형식도 됩니다."
          },
          "fromName": {
            "type": "string",
            "description": "보내는 사람 표시 이름"
          },
          "to": {
            "$ref": "#/components/schemas/AddressInput"
          },
          "cc": {
            "$ref": "#/components/schemas/AddressInput"
          },
          "bcc": {
            "$ref": "#/components/schemas/AddressInput"
          },
          "subject": {
            "type": "string"
          },
          "html": {
            "type": "string",
            "description": "HTML 본문"
          },
          "text": {
            "type": "string",
            "description": "텍스트 본문"
          },
          "replyTo": {
            "type": "string",
            "description": "회신 주소"
          },
          "notifyEmail": {
            "type": "string",
            "format": "email",
            "description": "발송이 즉시 거부되어 반송될 때 실패 내용을 추가로 받을 주소"
          },
          "individualSend": {
            "type": "boolean",
            "default": false,
            "description": "true면 수신자마다 한 통씩 따로 보내 서로의 주소가 보이지 않습니다. 발송 한도는 실제 수신자 수만큼 차감됩니다."
          },
          "attachments": {
            "type": "array",
            "maxItems": 10,
            "description": "최대 10개, 파일당 25MB, 합계 50MB",
            "items": {
              "$ref": "#/components/schemas/Attachment"
            }
          }
        }
      },
      "SendMailResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "jobId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "const": "queued"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "SendStatus": {
        "type": "object",
        "properties": {
          "jobId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "주요 값: waiting(대기), active(발송 중), completed(완료), failed(실패), delayed(재시도 대기)"
          },
          "result": {
            "type": "object",
            "description": "status가 completed일 때",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "messageId": {
                "type": "string"
              },
              "error": {
                "type": "string"
              }
            }
          },
          "failedReason": {
            "type": "string",
            "description": "status가 failed일 때 오류 내용"
          },
          "attempts": {
            "type": "integer",
            "description": "시도한 횟수"
          },
          "maxAttempts": {
            "type": "integer",
            "description": "최대 시도 횟수"
          }
        }
      },
      "Mailbox": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "path": {
            "type": "string",
            "example": "INBOX"
          },
          "specialUse": {
            "type": [
              "string",
              "null"
            ],
            "description": "특수 메일함 표시 (예: \\Sent, \\Trash)"
          },
          "total": {
            "type": "integer"
          },
          "unseen": {
            "type": "integer"
          }
        }
      },
      "MessageSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "mailboxId": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "subject": {
            "type": "string"
          },
          "from": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Address"
              },
              {
                "type": "null"
              }
            ]
          },
          "to": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "cc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "isRead": {
            "type": "boolean"
          },
          "isFlagged": {
            "type": "boolean"
          },
          "hasAttachments": {
            "type": "boolean"
          },
          "intro": {
            "type": "string",
            "description": "본문 앞부분 미리보기"
          }
        }
      },
      "MessageList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageSummary"
            }
          },
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          }
        }
      },
      "MessageDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "mailboxId": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date-time"
          },
          "subject": {
            "type": "string"
          },
          "from": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Address"
              },
              {
                "type": "null"
              }
            ]
          },
          "to": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "cc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "bcc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "replyTo": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Address"
              },
              {
                "type": "null"
              }
            ]
          },
          "messageId": {
            "type": [
              "string",
              "null"
            ],
            "description": "메일의 Message-ID 헤더"
          },
          "isRead": {
            "type": "boolean"
          },
          "isFlagged": {
            "type": "boolean"
          },
          "html": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "filename": {
                  "type": "string"
                },
                "contentType": {
                  "type": "string"
                },
                "size": {
                  "type": "integer",
                  "description": "크기(바이트, 근사값)"
                }
              }
            }
          }
        }
      }
    }
  }
}