# 이메일 위험도 일괄 검사



이메일 주소를 한 번에 100건까지 받아 형식·일회용 메일·무료 메일·공용 주소 여부와 위험 등급을 돌려줍니다.



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/email_risk_batch 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.items` (array): 조회 결과 항목 목록입니다. 항목이 없으면 빈 배열이며, 각 항목의 필드 구성은 서비스마다 다릅니다.

- `data.items[].email` (string): 검사한 주소입니다. 앞뒤 공백을 지운 값입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.items[].valid_syntax` (boolean): 주소 형식이 맞는지 여부입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.items[].domain` (string): @ 뒤 도메인입니다. 형식이 맞지 않으면 null입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.

- `data.items[].disposable` (boolean): 짧은 기간만 쓰고 버리는 일회용 메일 도메인이면 true입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.items[].free` (boolean): 누구나 무료로 만드는 메일 도메인이면 true입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.items[].role_account` (boolean): info·admin·support처럼 여러 사람이 함께 쓰는 공용 주소면 true입니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.items[].risk` (string): 위험 등급입니다.high: 형식 오류 또는 일회용 메일medium: 무료 메일 또는 공용 주소low: 그 밖의 주소 가능한 값은 3가지입니다. high = 높은 해상도·긴 문맥처럼 정확도를 우선하는 값입니다. 토큰·처리 시간이 늘어납니다. medium = 중간 길이 구간(약 4~20분)만 결과에 포함하는 값입니다. low = 낮은 해상도·짧은 문맥처럼 비용과 속도를 우선하는 값입니다.

- `data.summary` (object): 공고의 짧은 요약입니다. 본문 전체는 description_html에서 확인하세요.

- `data.summary.total` (integer): 상태 집계 대상 택배사의 전체 수입니다. 조회 가능·점검 중인 수를 합한 값과 일치합니다.

- `data.summary.invalid` (integer): 'invalid' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.summary.disposable` (integer): 'disposable' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.summary.free` (integer): 'free' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.summary.role_account` (integer): 'role_account' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.summary.high` (integer): 'high' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.summary.medium` (integer): 'medium' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.summary.low` (integer): 'low' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `data.error` (string): 오류 원인을 설명하는 문구입니다. 성공 응답에는 없거나 빈 문자열입니다.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/email_risk_batch



### 입력

- `emails` (string, 필수): 이메일 주소를 줄바꿈 또는 쉼표로 구분해 최대 100건 (예: a@example.com, b@example.com)



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "description": "검사한 주소입니다. 앞뒤 공백을 지운 값입니다."
              },
              "valid_syntax": {
                "type": "boolean",
                "description": "주소 형식이 맞는지 여부입니다."
              },
              "domain": {
                "type": "string",
                "description": "@ 뒤 도메인입니다. 형식이 맞지 않으면 null입니다.",
                "nullable": true
              },
              "disposable": {
                "type": "boolean",
                "description": "짧은 기간만 쓰고 버리는 일회용 메일 도메인이면 true입니다."
              },
              "free": {
                "type": "boolean",
                "description": "누구나 무료로 만드는 메일 도메인이면 true입니다."
              },
              "role_account": {
                "type": "boolean",
                "description": "info·admin·support처럼 여러 사람이 함께 쓰는 공용 주소면 true입니다."
              },
              "risk": {
                "type": "string",
                "description": "위험 등급입니다.high: 형식 오류 또는 일회용 메일medium: 무료 메일 또는 공용 주소low: 그 밖의 주소"
              }
            }
          },
          "description": "보낸 순서대로 담긴 건별 결과입니다. 주소 하나가 잘못돼도 나머지는 그대로 판정합니다."
        },
        "summary": {
          "type": "object",
          "properties": {
            "total": {
              "type": "integer"
            },
            "invalid": {
              "type": "integer"
            },
            "disposable": {
              "type": "integer"
            },
            "free": {
              "type": "integer"
            },
            "role_account": {
              "type": "integer"
            },
            "high": {
              "type": "integer"
            },
            "medium": {
              "type": "integer"
            },
            "low": {
              "type": "integer"
            }
          },
          "description": "건수 요약입니다. total, invalid, disposable, free, role_account, high, medium, low가 들어 있습니다."
        },
        "success": {
          "type": "integer"
        },
        "error": {
          "type": "string",
          "description": "실패 사유 문구입니다. 정상 응답에는 없습니다."
        }
      },
      "description": "검사 결과 묶음입니다. 실패하면 아래 필드 대신 error 문구가 들어 있습니다."
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "cost": {
          "type": "integer",
          "description": "이번 호출에서 차감된 포인트입니다. data.error가 있는 실패 응답은 0입니다."
        },
        "ms": {
          "type": "integer",
          "description": "요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다."
        },
        "pl_id": {
          "type": "integer"
        }
      },
      "description": "호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다."
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "items": [
      {
        "email": "user@gmail.com",
        "valid_syntax": true,
        "domain": "gmail.com",
        "disposable": false,
        "free": true,
        "role_account": false,
        "risk": "medium"
      },
      {
        "email": "temp@mailinator.com",
        "valid_syntax": true,
        "domain": "mailinator.com",
        "disposable": true,
        "free": false,
        "role_account": false,
        "risk": "high"
      },
      {
        "email": "admin@example.com",
        "valid_syntax": true,
        "domain": "example.com",
        "disposable": false,
        "free": false,
        "role_account": true,
        "risk": "medium"
      }
    ],
    "summary": {
      "total": 3,
      "invalid": 0,
      "disposable": 1,
      "free": 1,
      "role_account": 1,
      "high": 1,
      "medium": 2,
      "low": 0
    },
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 20,
    "ms": 12,
    "pl_id": 50234
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/email_risk_batch' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'emails=user@gmail.com, temp@mailinator.com, admin@example.com'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("emails", "user@gmail.com, temp@mailinator.com, admin@example.com");
const response = await fetch("https://apick.app/rest/email_risk_batch", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("emails", (None, "user@gmail.com, temp@mailinator.com, admin@example.com")),
]
response = requests.request("POST", "https://apick.app/rest/email_risk_batch",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'emails' => 'user@gmail.com, temp@mailinator.com, admin@example.com',
];
$curl = curl_init('https://apick.app/rest/email_risk_batch');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## 사용 예시 1. 가입 신청 목록 한 번에 거르기

이벤트 신청으로 받은 주소 목록에서 일회용 메일과 형식 오류를 한 번에 골라낼 때 씁니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/email_risk_batch' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'emails=user@gmail.com, temp@mailinator.com, admin@example.com'

```

- `data.items[].risk`가 `high`인 항목만 가입을 막습니다.

- `data.summary.disposable`·`invalid`로 걸러진 건수를 함께 기록합니다.

## 사용 예시 2. 기업 고객 명단에서 무료 메일 빼기

기업 고객만 받는 서비스에서 무료 메일 주소를 따로 표시할 때 씁니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/email_risk_batch' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'emails=buyer@example.com, someone@naver.com'

```

- `data.items[].free`가 true이면 무료 메일이므로 기업 확인 절차를 따로 안내합니다.

- 실제 수신 가능 여부까지 봐야 하면 이메일 유효성 검사로 한 건씩 확인합니다.

## 코드·오류

### 업무 실패 응답

입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요.

```json

{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}

```

## 상세 기능·요금

제공 정보 주소 목록을 한 번에 100건까지 보내면 건별로 형식·일회용 메일·무료 메일·공용 주소 여부와 위험 등급을 돌려줍니다. 가입 화면에서 받은 목록을 한 번에 걸러 내거나, 쌓아 둔 주소 목록에서 다시 볼 주소를 골라낼 때 씁니다. 도메인 목록으로 판정하므로 빠르지만 메일 서버(MX)까지 확인하지는 않습니다. 실제 수신 가능 여부까지 보려면 이메일 유효성 검사를 함께 쓰세요. Method URL POST https://apick.app/rest/email_risk_batch

## 상세 요청

Header 이름 필수 설명 Authorization 필수 Bearer 인증키. 예: Authorization: Bearer 발급받은_API_키

## 상세 응답

Body 필드 타입 설명 data Object 검사 결과 묶음입니다. 실패하면 아래 필드 대신 error 문구가 들어 있습니다. items Array 보낸 순서대로 담긴 건별 결과입니다. 주소 하나가 잘못돼도 나머지는 그대로 판정합니다. items[].email String 검사한 주소입니다. 앞뒤 공백을 지운 값입니다. items[].valid_syntax Boolean 주소 형식이 맞는지 여부입니다. items[].domain String | null @ 뒤 도메인입니다. 형식이 맞지 않으면 null입니다. items[].disposable Boolean 짧은 기간만 쓰고 버리는 일회용 메일 도메인이면 true입니다. items[].free Boolean 누구나 무료로 만드는 메일 도메인이면 true입니다. items[].role_account Boolean info·admin·support처럼 여러 사람이 함께 쓰는 공용 주소면 true입니다. items[].risk String 위험 등급입니다.high: 형식 오류 또는 일회용 메일medium: 무료 메일 또는 공용 주소low: 그 밖의 주소 summary Object 건수 요약입니다. total, invalid, disposable, free, role_account, high, medium, low가 들어 있습니다. error String 실패 사유 문구입니다. 정상 응답에는 없습니다. api Object 호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다. cost Integer 이번 호출에서 차감된 포인트입니다. data.error가 있는 실패 응답은 0입니다. ms Integer 요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다. 가입을 막을지 판단할 때는 risk가 high인 항목만 보면 됩니다. 무료 메일을 허용하는 서비스라면 medium은 통과시키세요.

## 상세 코드·정책

오류 응답 HTTP data.error 원인·조치 400 이메일 목록이 필요합니다. emails가 비어 있습니다. 주소를 하나 이상 보내세요. 400 이메일은 한 번에 100건까지 검사할 수 있습니다. 100건을 넘겨 보냈습니다. 나눠서 호출하세요. 오류 응답은 data.success 0, api.cost 0이며 요금이 차감되지 않습니다.

## 상세 예제

요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "items": [ { "email": "user@gmail.com", "valid_syntax": true, "domain": "gmail.com", "disposable": false, "free": true, "role_account": false, "risk": "medium" }, { "email": "temp@mailinator.com", "valid_syntax": true, "domain": "mailinator.com", "disposable": true, "free": false, "role_account": false, "risk": "high" }, { "email": "admin@example.com", "valid_syntax": true, "domain": "example.com", "disposable": false, "free": false, "role_account": true, "risk": "medium" } ], "summary": { "total": 3, "invalid": 0, "disposable": 1, "free": 1, "role_account": 1, "high": 1, "medium": 2, "low": 0 }, "success": 1 }, "api": { "success": true, "cost": 20, "ms": 12, "pl_id": 50234 } } 호출 예시 같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기