# 이메일 유효성 검사



이메일의 유효성 여부를 검사합니다.



인증: Authorization: Bearer $APICK_API_KEY

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

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



## POST /rest/check_email_valid 응답 필드

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

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

- `data.유효성` (boolean): 국가별 번호 체계상 형식이 유효한지 여부입니다. true여도 실제 개통·사용 중인지는 회선 상태(data.hlr)로 확인해야 합니다. true = 국가별 번호·주소 형식 검사를 통과한 경우, false = 형식이 맞지 않아 실제 존재 여부를 확인할 수 없는 경우입니다. 형식이 유효해도 실제 사용 중인지는 별도 조회가 필요합니다.

- `data.제공자` (string): 이 도메인의 메일을 실제로 받아 주는 메일 서비스의 도메인입니다. 회사 도메인이라도 구글·마이크로소프트 메일을 쓰면 google.com 등으로 옵니다. 확인하지 못하면 null입니다. null 허용.

- `data.도메인` (string): 주소의 @ 뒤 도메인입니다. 예: example.com 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.도메인상태` (string): 도메인의 메일 수신 상태입니다.ok: 메일을 받을 수 있는 도메인invalid: 도메인 이름 형식이 잘못됨no-service: 도메인 소유자가 메일을 받지 않는다고 설정함no-mail: 메일을 받을 서버 설정이 없음(도메인 오타일 가능성 큼)resolv-error: 일시적으로 확인하지 못함(잠시 후 다시 검사)

- `data.무료이메일여부` (boolean): gmail.com·naver.com처럼 누구나 무료로 만드는 메일 도메인이면 true입니다. 기업 전용 도메인이면 false입니다.

- `data.일회용이메일여부` (boolean): 짧은 기간만 쓰고 버리는 일회용 메일 도메인이면 true입니다. 가입 남용을 막으려면 true인 주소를 거절하세요. true = 일정 시간 뒤 폐기되는 일회용 주소로 판단된 경우, false = 계속 쓰는 일반 주소인 경우입니다. true면 실제 사용자 확인용으로 부적합합니다.

- `data.개인용이메일여부` (boolean): 개인이 쓰는 주소로 보이면 true입니다. 일회용 도메인이거나 info·admin·support처럼 여러 사람이 함께 쓰는 공용 주소면 false입니다.

- `data.MX-IP` (string): 이 도메인의 메일을 받는 서버의 IP 주소입니다. 확인하지 못하면 null입니다. null 허용.

- `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/check_email_valid



### 입력

- `email` (string, 필수): 검증할 이메일 주소입니다. @와 도메인을 포함한 전체 주소를 보내며, 형식이 맞지 않으면 조회 전에 거부됩니다.



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "이메일": {
          "type": "string",
          "description": "검사한 이메일 주소입니다. 앞뒤 공백을 지운 값입니다."
        },
        "유효성": {
          "type": "boolean",
          "description": "메일을 보낼 수 있는 주소인지 종합 판정입니다. 형식이 맞고 도메인상태가 ok일 때만 true입니다. 가입 허용 여부는 이 값으로 먼저 판단하세요."
        },
        "제공자": {
          "type": "string",
          "description": "이 도메인의 메일을 실제로 받아 주는 메일 서비스의 도메인입니다. 회사 도메인이라도 구글·마이크로소프트 메일을 쓰면 google.com 등으로 옵니다. 확인하지 못하면 null입니다.",
          "nullable": true
        },
        "도메인": {
          "type": "string",
          "description": "주소의 @ 뒤 도메인입니다. 예: example.com"
        },
        "도메인상태": {
          "type": "string",
          "description": "도메인의 메일 수신 상태입니다.ok: 메일을 받을 수 있는 도메인invalid: 도메인 이름 형식이 잘못됨no-service: 도메인 소유자가 메일을 받지 않는다고 설정함no-mail: 메일을 받을 서버 설정이 없음(도메인 오타일 가능성 큼)resolv-error: 일시적으로 확인하지 못함(잠시 후 다시 검사)"
        },
        "무료이메일여부": {
          "type": "boolean",
          "description": "gmail.com·naver.com처럼 누구나 무료로 만드는 메일 도메인이면 true입니다. 기업 전용 도메인이면 false입니다."
        },
        "일회용이메일여부": {
          "type": "boolean",
          "description": "짧은 기간만 쓰고 버리는 일회용 메일 도메인이면 true입니다. 가입 남용을 막으려면 true인 주소를 거절하세요."
        },
        "개인용이메일여부": {
          "type": "boolean",
          "description": "개인이 쓰는 주소로 보이면 true입니다. 일회용 도메인이거나 info·admin·support처럼 여러 사람이 함께 쓰는 공용 주소면 false입니다."
        },
        "MX-IP": {
          "type": "string",
          "description": "이 도메인의 메일을 받는 서버의 IP 주소입니다. 확인하지 못하면 null입니다.",
          "nullable": true
        },
        "success": {
          "type": "integer",
          "description": "처리 상태입니다. 1이면 검사가 끝난 정상 응답(요금 차감), 0이면 실패 응답(차감 없음)입니다."
        },
        "error": {
          "type": "string",
          "description": "실패 사유 문구입니다. 정상 응답에는 없으며, 값이 있으면 아래 오류 응답 표에서 원인과 조치를 확인하세요."
        }
      },
      "description": "검사 결과 묶음입니다. 실패하면 아래 필드 대신 error 문구가 들어 있습니다."
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "요청을 정상적으로 받아 처리했는지 여부입니다. 주소가 쓸 만한지는 data.유효성으로 확인하세요."
        },
        "cost": {
          "type": "integer",
          "description": "이번 호출에서 차감된 포인트입니다. data.error가 있는 실패 응답은 0입니다."
        },
        "ms": {
          "type": "integer",
          "description": "요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다. 네트워크 왕복 시간은 포함되지 않습니다."
        },
        "pl_id": {
          "type": "integer",
          "description": "포인트 차감 기록 번호입니다. 차감이 있었던 호출에만 값이 있으며 과금 문의 때 사용합니다."
        }
      },
      "description": "호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다."
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "이메일": "user@gmail.com",
    "유효성": true,
    "제공자": "google.com",
    "도메인": "gmail.com",
    "도메인상태": "ok",
    "무료이메일여부": true,
    "일회용이메일여부": false,
    "개인용이메일여부": true,
    "MX-IP": "172.253.118.26",
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 10,
    "ms": 248,
    "pl_id": 405
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/check_email_valid' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'email=user@gmail.com'

```

### Node.js (서버 ESM)

```javascript

const form = new FormData();
form.append("email", "user@gmail.com");
const response = await fetch("https://apick.app/rest/check_email_valid", {
  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 = [
    ("email", (None, "user@gmail.com")),
]
response = requests.request("POST", "https://apick.app/rest/check_email_valid",
    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 = [
    'email' => 'user@gmail.com',
];
$curl = curl_init('https://apick.app/rest/check_email_valid');
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/check_email_valid' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'email=user@example.com'

```

- `data.유효성`이 true이면 사용할 수 있는 주소입니다.

- `data.도메인상태`가 `no-mail`이면 도메인 오타일 가능성이 크므로 다시 입력받습니다.

## 사용 예시 2. 일회용·공용 주소 거르기

체험판 남용을 막거나 담당자 개인 주소만 받으려 할 때 사용합니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/check_email_valid' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'email=info@example.com'

```

- `data.일회용이메일여부`가 true이면 가입을 막습니다.

- `data.개인용이메일여부`가 false이면 info·admin 같은 공용 주소입니다.

## 사용 예시 3. 기업 메일만 받기

기업 고객 전용 서비스에서 무료 메일 주소를 구분합니다.

```bash

curl --fail-with-body --request POST 'https://apick.app/rest/check_email_valid' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'email=user@gmail.com'

```

- `data.무료이메일여부`가 true이면 회사 메일 주소를 다시 요청합니다.

- 형식이 틀린 주소는 "이메일 형식이 맞지 않습니다."(HTTP 400)이며 요금이 차감되지 않습니다.

## 코드·오류

### 업무 실패 응답

입력 오류·대상 없음·일시 실패는 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
  }
}

```

## 상세 기능·요금

제공 정보 이메일 주소 하나를 보내면 형식이 맞는지, 그 도메인이 메일을 받을 수 있는지, 무료 메일·일회용 메일·공용 주소(info, admin 등)인지를 한 번에 알려 줍니다. 회원 가입·뉴스레터 신청 화면에서 오타 주소와 일회용 메일을 걸러 내거나, 기업 고객만 받아야 할 때 무료 메일 주소를 구분하는 데 사용합니다. 도메인이 메일을 받을 수 있는지까지 확인합니다. 그 주소의 받은편지함까지 확인하려면 인증 메일을 함께 쓰세요. Method URL POST https://apick.app/rest/check_email_valid

## 상세 요청

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

## 상세 응답

Body 필드 타입 설명 data Object 검사 결과 묶음입니다. 실패하면 아래 필드 대신 error 문구가 들어 있습니다. 이메일 String 검사한 이메일 주소입니다. 앞뒤 공백을 지운 값입니다. 유효성 Boolean 메일을 보낼 수 있는 주소인지 종합 판정입니다. 형식이 맞고 도메인상태가 ok일 때만 true입니다. 가입 허용 여부는 이 값으로 먼저 판단하세요. 제공자 String | null 이 도메인의 메일을 실제로 받아 주는 메일 서비스의 도메인입니다. 회사 도메인이라도 구글·마이크로소프트 메일을 쓰면 google.com 등으로 옵니다. 확인하지 못하면 null입니다. 도메인 String 주소의 @ 뒤 도메인입니다. 예: example.com 도메인상태 String 도메인의 메일 수신 상태입니다.ok: 메일을 받을 수 있는 도메인invalid: 도메인 이름 형식이 잘못됨no-service: 도메인 소유자가 메일을 받지 않는다고 설정함no-mail: 메일을 받을 서버 설정이 없음(도메인 오타일 가능성 큼)resolv-error: 일시적으로 확인하지 못함(잠시 후 다시 검사) 무료이메일여부 Boolean gmail.com·naver.com처럼 누구나 무료로 만드는 메일 도메인이면 true입니다. 기업 전용 도메인이면 false입니다. 일회용이메일여부 Boolean 짧은 기간만 쓰고 버리는 일회용 메일 도메인이면 true입니다. 가입 남용을 막으려면 true인 주소를 거절하세요. 개인용이메일여부 Boolean 개인이 쓰는 주소로 보이면 true입니다. 일회용 도메인이거나 info·admin·support처럼 여러 사람이 함께 쓰는 공용 주소면 false입니다. MX-IP String | null 이 도메인의 메일을 받는 서버의 IP 주소입니다. 확인하지 못하면 null입니다. error String 실패 사유 문구입니다. 정상 응답에는 없으며, 값이 있으면 아래 오류 응답 표에서 원인과 조치를 확인하세요. success Integer 처리 상태입니다. 1이면 검사가 끝난 정상 응답(요금 차감), 0이면 실패 응답(차감 없음)입니다. api Object 호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다. success Boolean 요청을 정상적으로 받아 처리했는지 여부입니다. 주소가 쓸 만한지는 data.유효성으로 확인하세요. cost Integer 이번 호출에서 차감된 포인트입니다. data.error가 있는 실패 응답은 0입니다. ms Integer 요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다. 네트워크 왕복 시간은 포함되지 않습니다. pl_id Integer 포인트 차감 기록 번호입니다. 차감이 있었던 호출에만 값이 있으며 과금 문의 때 사용합니다. 판정 예: 유효성이 false이고 도메인상태가 no-mail이면 도메인 오타를 의심해 다시 입력받고, resolv-error이면 잠시 후 다시 검사합니다. 일회용이메일여부가 true이면 가입을 막을 수 있습니다. 유효성이 false여도 검사가 끝난 정상 응답이므로 data.success가 1입니다. 실제 차감 금액은 api.cost로 확인하세요.

## 상세 코드·정책

오류 응답 HTTP data.error 원인·조치 400 이메일 형식이 맞지 않습니다. email이 없거나 @·도메인이 빠진 주소입니다. 검사하지 않으며 요금도 차감되지 않습니다. 424 이메일 검사에 실패했습니다. 일시적인 실패입니다. 잠시 후 다시 요청하세요. 오류 응답은 data.success 0, api.cost 0이며 요금이 차감되지 않습니다.

## 상세 예제

요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "이메일": "user@gmail.com", "유효성": true, "제공자": "google.com", "도메인": "gmail.com", "도메인상태": "ok", "무료이메일여부": true, "일회용이메일여부": false, "개인용이메일여부": true, "MX-IP": "172.253.118.26", "success": 1 }, "api": { "success": true, "cost": 10, "ms": 248, "pl_id": 405 } } 호출 예시 같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기