{
	"openapi": "3.0.0",
	"info": {
		"title": "Reacher",
		"version": "0.5.0",
		"description": "### What is Reacher?\n\nReacher is a powerful, free and open-source email verification API service. It is provided both as a SaaS and as a self-host solution.",
		"license": {
			"name": "AGPL-3.0 OR Commercial",
			"url": "https://github.com/reacherhq/check-if-email-exists/blob/master/LICENSE.md"
		},
		"contact": {
			"name": "Reacher",
			"url": "https://reacher.email",
			"email": "amaury@reacher.email"
		},
		"termsOfService": "https://github.com/reacherhq/policies/blob/master/terms/index.fr.md"
	},
	"servers": [
		{
			"url": "https://api.reacher.email/v0",
			"description": "Reacher Production"
		}
	],
	"paths": {
		"/check_email": {
			"post": {
				"summary": "/check_email",
				"responses": {
					"200": {
						"description": "OK",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/CheckEmailOutput"
								},
								"examples": {
									"Example with test@gmail.com": {
										"value": {
											"input": "test@gmail.com",
											"is_reachable": "invalid",
											"misc": {
												"is_disposable": false,
												"is_role_account": true
											},
											"mx": {
												"accepts_mail": true,
												"records": [
													"alt4.gmail-smtp-in.l.google.com.",
													"alt2.gmail-smtp-in.l.google.com.",
													"alt3.gmail-smtp-in.l.google.com.",
													"gmail-smtp-in.l.google.com.",
													"alt1.gmail-smtp-in.l.google.com."
												]
											},
											"smtp": {
												"can_connect_smtp": true,
												"has_full_inbox": false,
												"is_catch_all": false,
												"is_deliverable": false,
												"is_disabled": false
											},
											"syntax": {
												"domain": "gmail.com",
												"is_valid_syntax": true,
												"username": "test"
											}
										}
									}
								}
							}
						}
					}
				},
				"operationId": "post-check-email",
				"description": "Perform a full verification of an email address.",
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/CheckEmailInput"
							}
						}
					},
					"description": "Input containing all parameters necessary for an email verification."
				},
				"parameters": [
					{
						"schema": {
							"type": "string"
						},
						"in": "header",
						"name": "Authorization",
						"description": "Your personal Reacher API key",
						"required": true
					}
				]
			},
			"parameters": []
		}
	},
	"components": {
		"schemas": {
			"CheckEmailOutput": {
				"title": "CheckEmailOutput",
				"type": "object",
				"x-examples": {
					"Example with test@gmail.com": {
						"input": "test@gmail.com",
						"is_reachable": "invalid",
						"misc": {
							"is_disposable": false,
							"is_role_account": true
						},
						"mx": {
							"accepts_mail": true,
							"records": [
								"alt4.gmail-smtp-in.l.google.com.",
								"alt2.gmail-smtp-in.l.google.com.",
								"alt3.gmail-smtp-in.l.google.com.",
								"gmail-smtp-in.l.google.com.",
								"alt1.gmail-smtp-in.l.google.com."
							]
						},
						"smtp": {
							"can_connect_smtp": true,
							"has_full_inbox": false,
							"is_catch_all": false,
							"is_deliverable": false,
							"is_disabled": false
						},
						"syntax": {
							"domain": "gmail.com",
							"is_valid_syntax": true,
							"username": "test"
						}
					}
				},
				"description": "The verification result of an email.",
				"properties": {
					"input": {
						"type": "string",
						"format": "email",
						"description": "The input email address."
					},
					"is_reachable": {
						"$ref": "#/components/schemas/Reachable"
					},
					"misc": {
						"oneOf": [
							{
								"$ref": "#/components/schemas/MiscDetails"
							},
							{
								"$ref": "#/components/schemas/Error"
							}
						],
						"description": "Miscellaneous information about the email account."
					},
					"mx": {
						"oneOf": [
							{
								"$ref": "#/components/schemas/MxDetails"
							},
							{
								"$ref": "#/components/schemas/Error"
							}
						],
						"description": "Information gathered from querying the MX records of the mail server."
					},
					"smtp": {
						"oneOf": [
							{
								"$ref": "#/components/schemas/SmtpDetails"
							},
							{
								"$ref": "#/components/schemas/Error"
							}
						],
						"description": "Verifications performed by connecting to the mail server via SMTP."
					},
					"syntax": {
						"$ref": "#/components/schemas/SyntaxDetails"
					}
				},
				"required": [
					"input",
					"misc",
					"mx",
					"smtp",
					"syntax",
					"is_reachable"
				]
			},
			"Error": {
				"title": "Error",
				"type": "object",
				"description": "Object describing an error happening during the misc, MX, or SMTP verifications.",
				"properties": {
					"type": {
						"type": "string",
						"description": "An error type."
					},
					"message": {
						"type": "string",
						"description": "A human-readable description of the error."
					}
				},
				"required": ["type", "message"]
			},
			"MiscDetails": {
				"title": "MiscDetails",
				"type": "object",
				"description": "Miscellaneous information about the email account.",
				"properties": {
					"is_disposable": {
						"type": "boolean",
						"description": "Is the address provided by a known disposable email address provider?"
					},
					"is_role_account": {
						"type": "boolean",
						"description": "Is this email a role-based account?"
					},
					"gravatar_url": {
						"type": "string",
						"description": "URL to the email's Gravatar profile picture. It is only populated if check_gravatar is set to true in the request, and if the email has an associated Gravatar."
					}
				},
				"required": ["is_disposable", "is_role_account"]
			},
			"MxDetails": {
				"title": "MxDetails",
				"type": "object",
				"properties": {
					"accepts_mail": {
						"type": "boolean",
						"description": "Does the server accept mails?"
					},
					"records": {
						"type": "array",
						"description": "The list of FQDN (Fully Qualified Domain Names) of the mail server.",
						"items": {
							"type": "string"
						}
					}
				},
				"required": ["accepts_mail", "records"],
				"description": "Object holding the MX details of the mail server."
			},
			"SmtpDetails": {
				"title": "SmtpDetails",
				"type": "object",
				"description": "Verifications performed by connecting to the mail server via SMTP.",
				"properties": {
					"can_connect_smtp": {
						"type": "boolean",
						"description": "Can the mail exchanger of the email address domain be contacted successfully?"
					},
					"has_full_inbox": {
						"type": "boolean",
						"description": "Is the inbox of this mailbox full?"
					},
					"is_catch_all": {
						"type": "boolean",
						"description": "Is this email address a catch-all address?"
					},
					"is_deliverable": {
						"type": "boolean",
						"description": "Is an email sent to this address deliverable?"
					},
					"is_disabled": {
						"type": "boolean",
						"description": "Has this email address been disabled by the email provider?"
					}
				},
				"required": [
					"can_connect_smtp",
					"has_full_inbox",
					"is_catch_all",
					"is_deliverable",
					"is_disabled"
				]
			},
			"SyntaxDetails": {
				"title": "SyntaxDetails",
				"type": "object",
				"description": "Syntax validation of an email address.",
				"properties": {
					"domain": {
						"type": "string",
						"description": "The domain name of the email, i.e. the part after the \"@\" symbol."
					},
					"is_valid_syntax": {
						"type": "boolean",
						"description": "Is the address syntactically valid?"
					},
					"username": {
						"type": "string",
						"description": "The username of the email, i.e. the part before the \"@\" symbol."
					}
				},
				"required": ["domain", "is_valid_syntax", "username"]
			},
			"Reachable": {
				"type": "string",
				"title": "Reachable",
				"enum": ["invalid", "unknown", "safe", "risky"],
				"description": "An enum to describe how confident we are that the recipient address is real: `safe`, `risky`, `invalid` and `unknown`. Check our FAQ to know the meanings of the 4 possibilities: https://help.reacher.email/email-attributes-inside-json."
			},
			"YahooVerifyMethod": {
				"type": "string",
				"title": "YahooVerifyMethod",
				"enum": ["Api", "Headless", "Smtp"],
				"description": "An enum to describe how we verify Yahoo emails."
			},
			"HotmailVerifyMethod": {
				"type": "string",
				"title": "HotmailVerifyMethod",
				"enum": ["Api", "Headless", "Smtp"],
				"description": "An enum to describe how we verify Hotmail emails."
			},
			"GmailVerifyMethod": {
				"type": "string",
				"title": "GmailVerifyMethod",
				"enum": ["Api", "Smtp"],
				"description": "An enum to describe how we verify Gmail emails.",
				"x-internal": false
			},
			"CheckEmailInput": {
				"title": "CheckEmailInput",
				"type": "object",
				"description": "Input containing all parameters necessary for an email verification, as well as some config on how to perform the verification.",
				"properties": {
					"from_email": {
						"type": "string",
						"description": "In the SMTP connection, the FROM email address."
					},
					"to_email": {
						"type": "string",
						"description": "The email address to check."
					},
					"hello_name": {
						"type": "string",
						"description": "In the SMTP connection, the EHLO hostname."
					},
					"proxy": {
						"$ref": "#/components/schemas/CheckEmailInputProxy"
					},
					"smtp_port": {
						"type": "number",
						"description": "SMTP port to use for email validation. Generally, ports 25, 465, 587 and 2525 are used."
					},
					"yahoo_verify_method": {
						"$ref": "#/components/schemas/YahooVerifyMethod"
					},
					"gmail_verify_method": {
						"$ref": "#/components/schemas/GmailVerifyMethod"
					},
					"hotmail_verify_method": {
						"$ref": "#/components/schemas/HotmailVerifyMethod"
					},
					"check_gravatar": {
						"type": "boolean",
						"description": "Whether to check if a gravatar image is existing for the given email."
					},
					"retries": {
						"type": "number",
						"default": 2,
						"description": "Number of retries of SMTP connections to do."
					},
					"smtp_security": {
						"type": "string",
						"example": "Opportunistic",
						"enum": [
							"None",
							"Opportunistic",
							"Required",
							"Wrapper"
						],
						"description": "How to apply TLS to a SMTP client connection."
					},
					"smtp_timeout": {
						"$ref": "#/components/schemas/Duration"
					}
				},
				"required": ["to_email"]
			},
			"CheckEmailInputProxy": {
				"title": "CheckEmailInputProxy",
				"type": "object",
				"x-examples": {
					"example-1": {
						"value": {
							"host": "my-proxy.io",
							"port": 1080
						}
					}
				},
				"properties": {
					"host": {
						"type": "string",
						"description": "The proxy host."
					},
					"port": {
						"type": "integer",
						"description": "The proxy port."
					},
					"username": {
						"type": "string",
						"description": "Username to pass to proxy authentication."
					},
					"password": {
						"type": "string",
						"description": "Password to pass to proxy authentication."
					}
				},
				"required": ["host", "port"]
			},
			"Duration": {
				"title": "Duration",
				"x-stoplight": {
					"id": "0s9q75wxim1iw"
				},
				"type": "object",
				"description": "An object representing a duration (seconds + nanoseconds).",
				"properties": {
					"secs": {
						"type": "number",
						"description": "Seconds"
					},
					"nanos": {
						"type": "string",
						"description": "Nanoseconds"
					}
				},
				"required": ["secs", "nanos"]
			}
		},
		"securitySchemes": {
			"Authorization": {
				"name": "Authorization",
				"type": "apiKey",
				"in": "header",
				"description": "A Reacher API key is required for all requests. Sign up on https://reacher.email to get your personal API key."
			}
		}
	}
}