{
    "swagger": "2.0",
    "info":
    {
        "description": "The mailfloss single-email verification API is ideal for integrating email address verification during your signup or onboarding process with just a single request from your back-end application.",
        "version": "1.0.0",
        "title": "mailfloss API",
        "termsOfService": "http://mailfloss.com/terms/",
        "contact":
        {
            "email": "hello@mailfloss.com"
        }
    },
    "host": "api.mailfloss.com",
    "basePath": "/",
    "tags": [
    {
        "name": "verify",
        "description": "mailfloss email verification API"
    },
    {
        "name": "batch verify",
        "description": "mailfloss email batch verification API"
    }],
    "schemes": [
        "https"
    ],
    "paths":
    {
        "/verify":
        {
            "get":
            {
                "tags": [
                    "verify"
                ],
                "summary": "Verify email address",
                "description": "",
                "operationId": "verifyEmailAddress",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                {
                    "name": "api_key",
                    "in": "query",
                    "description": "Your API key ",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "email",
                    "in": "query",
                    "description": "The email address that needs to be verified ",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "timeout",
                    "in": "query",
                    "description": "Timeout value in ms. Max 60000. Defaults to 30000 ",
                    "required": false,
                    "type": "integer"
                }],
                "responses":
                {
                    "200":
                    {
                        "description": "successful operation",
                        "schema":
                        {
                            "$ref": "#/definitions/Verify"
                        }
                    },
                    "400":
                    {
                        "description": "No email address supplied"
                    },
                    "401":
                    {
                        "description": "Invalid API key"
                    },
                    "402":
                    {
                        "description": "Insufficient credits"
                    },
                    "403":
                    {
                        "description": "No API key provided"
                    },
                    "429":
                    {
                        "description": "Rate limit exceeded"
                    },
                    "500":
                    {
                        "description": "Timeout"
                    }
                },
                "security": [
                {
                    "api_key": []
                }]
            }
        },
        "/batch-verify":
        {
            "post":
            {
                "tags": [
                    "batch verify"
                ],
                "summary": "Batch verifies emails from given input array. Maximum 1000000 emails per call. Maximum 10 running batch verification sessions at a time. Add a webhook url to receive results once completed (optional and recommended).",
                "description": "",
                "operationId": "batchVerifyEmailsWithArrayInput",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                {
                    "name": "api_key",
                    "in": "query",
                    "description": "Your API key ",
                    "required": true,
                    "type": "string"
                },
                {
                    "in": "body",
                    "name": "body",
                    "description": "Batch verify array of email addresses. Maximum 1000000 email addresses.",
                    "required": true,
                    "schema":
                    {
                        "type": "object",
                        "properties":
                        {
                            "webhookUrl":
                            {
                                "type": "string",
                                "description": "optional - enter webhook url to post to when job completed"
                            },
                            "emails":
                            {
                                "type": "array",
                                "items":
                                {
                                    "type": "string"
                                }
                            }
                        },
                        "required": [
                            "emails"
                        ]
                    }
                }],
                "responses":
                {
                    "200":
                    {
                        "description": "successful operation",
                        "schema":
                        {
                            "$ref": "#/definitions/BatchVerify"
                        }
                    },
                    "400":
                    {
                        "description": "No email address supplied"
                    },
                    "401":
                    {
                        "description": "Invalid API key"
                    },
                    "402":
                    {
                        "description": "Insufficient credits"
                    },
                    "403":
                    {
                        "description": "No API key provided"
                    },
                    "413":
                    {
                        "description": "Payload too large. Too many emails addresses"
                    },
                    "415":
                    {
                        "description": "Invalid Content Type. Must be application/json"
                    },
                    "429":
                    {
                        "description": "Rate limit exceeded"
                    },
                    "503":
                    {
                        "description": "Failed to create job"
                    }
                },
                "security": [
                {
                    "api_key": []
                }]
            }
        },
        "/batch-verify/{id}/cancel":
        {
            "post":
            {
                "tags": [
                    "batch verify"
                ],
                "summary": "Cancel batch verification job",
                "description": "",
                "operationId": "batchVerifyEmailAddressesCancel",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                {
                    "name": "api_key",
                    "in": "query",
                    "description": "Your API key ",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "id",
                    "in": "path",
                    "description": "The id that needs to be canceled. ",
                    "required": true,
                    "type": "string"
                }],
                "responses":
                {
                    "200":
                    {
                        "description": "successful operation",
                        "schema":
                        {
                            "$ref": "#/definitions/JobCancel"
                        }
                    },
                    "400":
                    {
                        "description": "No id supplied"
                    },
                    "401":
                    {
                        "description": "Invalid API key"
                    },
                    "403":
                    {
                        "description": "No API key provided"
                    },
                    "404":
                    {
                        "description": "Job not found"
                    },
                    "429":
                    {
                        "description": "Rate limit exceeded"
                    }
                },
                "security": [
                {
                    "api_key": []
                }]
            }
        },
        "/batch-verify/{id}/status":
        {
            "get":
            {
                "tags": [
                    "batch verify"
                ],
                "summary": "Get batch verification status",
                "description": "",
                "operationId": "batchVerifyEmailAddressesStatus",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                {
                    "name": "api_key",
                    "in": "query",
                    "description": "Your API key ",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "id",
                    "in": "path",
                    "description": "The id that needs to be fetched. ",
                    "required": true,
                    "type": "string"
                }],
                "responses":
                {
                    "200":
                    {
                        "description": "successful operation",
                        "schema":
                        {
                            "$ref": "#/definitions/Job"
                        }
                    },
                    "400":
                    {
                        "description": "No id supplied"
                    },
                    "401":
                    {
                        "description": "Invalid API key"
                    },
                    "403":
                    {
                        "description": "No API key provided"
                    },
                    "404":
                    {
                        "description": "Job not found"
                    },
                    "429":
                    {
                        "description": "Rate limit exceeded"
                    }
                },
                "security": [
                {
                    "api_key": []
                }]
            }
        },
        "/batch-verify/{id}":
        {
            "get":
            {
                "tags": [
                    "batch verify"
                ],
                "summary": "Get batch verification results",
                "description": "",
                "operationId": "batchVerifyEmailAddressesResults",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "description": "The id that needs to be fetched. ",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "api_key",
                    "in": "query",
                    "description": "Your API key ",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "page",
                    "in": "query",
                    "description": "Page to be fetched ",
                    "required": true,
                    "type": "integer"
                },
                {
                    "name": "per_page",
                    "in": "query",
                    "description": "The number of items returned in a single response. Max 1000. Defaults to 100 ",
                    "required": true,
                    "type": "integer"
                }],
                "responses":
                {
                    "200":
                    {
                        "description": "successful operation",
                        "schema":
                        {
                            "$ref": "#/definitions/ResultsArray"
                        }
                    },
                    "400":
                    {
                        "description": "No id supplied"
                    },
                    "401":
                    {
                        "description": "Invalid API key"
                    },
                    "403":
                    {
                        "description": "No API key provided"
                    },
                    "404":
                    {
                        "description": "Job not found"
                    },
                    "429":
                    {
                        "description": "Rate limit exceeded"
                    }
                },
                "security": [
                {
                    "api_key": []
                }]
            }
        }
    },
    "securityDefinitions":
    {
        "api_key":
        {
            "type": "apiKey",
            "name": "api_key",
            "in": "query"
        }
    },
    "definitions":
    {
        "Verify":
        {
            "type": "object",
            "properties":
            {
                "email":
                {
                    "type": "string",
                    "description": "The checked email address"
                },
                "suggestion":
                {
                    "type": "string",
                    "description": "An email address suggestion, if one exists"
                },
                "status":
                {
                    "type": "string",
                    "description": "The status of the email address"
                },
                "reason":
                {
                    "type": "string",
                    "description": "The category of the email address"
                },
                "role":
                {
                    "type": "boolean",
                    "description": "True if email address is role-based"
                },
                "disposable":
                {
                    "type": "boolean",
                    "description": "True if email address is from a disposable domain service"
                },
                "free":
                {
                    "type": "boolean",
                    "description": "True if email address is from a free email service provider"
                },
                "passed":
                {
                    "type": "boolean",
                    "description": "If the email address passed all verification tests"
                },
                "domain":
                {
                    "type": "string",
                    "description": "The domain of the email address"
                },
                "meta":
                {
                    "type": "string",
                    "description": "Additional meta information"
                }
            },
            "xml":
            {
                "name": "Check"
            }
        },
        "BatchVerify":
        {
            "type": "object",
            "properties":
            {
                "id":
                {
                    "type": "string",
                    "description": "The returned job Id"
                }
            },
            "xml":
            {
                "name": "Batch Verify"
            }
        },
        "Job":
        {
            "type": "object",
            "properties":
            {
                "id":
                {
                    "type": "string",
                    "description": "The job Id"
                },
                "processed":
                {
                    "type": "boolean",
                    "description": "If the job has finished processing"
                },
                "status":
                {
                    "type": "string",
                    "description": "The status of the job"
                },
                "numImported":
                {
                    "type": "integer",
                    "description": "Number of email addresses imported"
                },
                "emailsProcessed":
                {
                    "type": "integer",
                    "description": "Number of email addresses processed"
                },
                "numPassed":
                {
                    "type": "integer",
                    "description": "Number of valid email addresses"
                },
                "numFailed":
                {
                    "type": "integer",
                    "description": "Number of email addresses that failed to pass all tests"
                },
                "numUndeliverable":
                {
                    "type": "integer",
                    "description": "Number of undeliverable email addresses"
                },
                "numUnknown":
                {
                    "type": "integer",
                    "description": "Number of unknown email addresses"
                },
                "numRisky":
                {
                    "type": "integer",
                    "description": "Number of risky email addresses"
                }
            },
            "xml":
            {
                "name": "Job"
            }
        },
        "JobCancel":
        {
            "type": "object",
            "properties":
            {
                "status":
                {
                    "type": "string",
                    "description": "Success if job canceled successful"
                }
            },
            "xml":
            {
                "name": "JobCancel"
            }
        },
        "ResultsArray":
        {
            "type": "array",
            "items":
            {
                "type": "object",
                "properties":
                {
                    "processed":
                    {
                        "type": "boolean",
                        "description": "If the email address was processed"
                    },
                    "passed":
                    {
                        "type": "boolean",
                        "description": "If the email address passed all verification tests"
                    },
                    "status":
                    {
                        "type": "string",
                        "description": "The status of the email address"
                    },
                    "reason":
                    {
                        "type": "string",
                        "description": "The category of the email address"
                    },
                    "email":
                    {
                        "type": "string",
                        "description": "The checked email addresses"
                    },
                    "domain":
                    {
                        "type": "string",
                        "description": "The domain of the email address"
                    },
                    "completed_at":
                    {
                        "type": "string",
                        "description": "The date the check was completed"
                    },
                    "suggestion":
                    {
                        "type": "string",
                        "description": "An email address suggestion, if one exists"
                    }
                }
            },
            "xml":
            {
                "name": "ResultsArray"
            }
        }
    },
    "externalDocs":
    {
        "description": "Find out more about mailfloss",
        "url": "https://mailfloss.com"
    }
}