---
title: "Check email addresses"
method: POST
path: "/email-recipients/check"
tags: ["Email"]
---

# Check email addresses

`POST /email-recipients/check`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/email-recipients/check`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `messages:read`)

Checks one address or up to 50 the way sending does before the first email to someone: the format, this project's suppression list (an earlier hard bounce or spam complaint, or an unsubscribe), likely typos of big mail domains (gmial.com), throwaway domains, and whether the domain exists and accepts email (MX, or an A record without MX). Sends nothing and stores nothing. Use it on addresses from a form or an import before sending. At most 30 calls per minute per project.

## Request body

- object
  - `email` string: One address to check.
  - `emails` string[]: Or a list of 1 to 50 addresses.

## Response `200`

One result per address, in the order sent.

- object
  - `data` object[], required
    - `email` string, required
    - `result` 'valid' | 'risky' | 'invalid' | 'unknown', required: valid: deliverable; risky: it would bounce less often but has a catch (throwaway, unsubscribed, complained); invalid: an email would not arrive; unknown: the domain could not be checked right now.
    - `code` 'ok' | 'invalid_syntax' | 'domain_not_found' | 'no_mail_server' | 'disposable' | 'likely_typo' | 'hard_bounced' | 'complained' | 'unsubscribed' | 'unknown', required
    - `reason` string, required: In plain words.
    - `suggestion` string, nullable, required: With likely_typo: the address that was probably meant. Never use it without asking the user.
    - `would_send` object, required: Whether send_email would accept this address now, per category.
      - `transactional` boolean, required
      - `other` boolean, required

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

[API](https://skmtc.dev/hypamoon/apis/hypamoon-api.md) · [All operations](https://skmtc.dev/hypamoon/apis/hypamoon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hypamoon/apis/hypamoon-api/revisions/9f0b90004c06?raw)