{"openapi":"3.0.0","paths":{"/api/verifyEmail":{"get":{"operationId":"verifySingleEmail","summary":"Verify email deliverability","description":"\n## Verify email deliverability\n\n#### Rate limit: 10 requests in 1 second\n\n#### Credits required: 1\n\nThis endpoint evaluates deliverability status of a single email address. The response body is a plain text representing the deliverability status. Additionally, the value can be `error_credit` which denotes inadequate credit balance for request execution.\n","parameters":[{"name":"email","required":true,"in":"query","description":"The email address that will be verified","schema":{"format":"email","example":"john.smith@gmail.com","type":"string"}}],"responses":{"200":{"description":"Deliverability status of the email address","content":{"text/html":{"schema":{"type":"string","example":"ok","enum":["ok","unknown","dead_server","invalid_mx","email_disabled","antispam_system","ok_for_all","smtp_protocol","invalid_syntax","disposable","spamtrap","error_credit"],"description":"The deliverability status of the email address"}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/verifyEmailDetailed":{"get":{"operationId":"verifySingleEmailDetailed","summary":"Verify email deliverability","description":"\n## Verify email deliverability\n\n#### Rate limit: 10 requests in 1 second\n\n#### Credits required: 1\n\nThis endpoint determines the deliverability status of an individual email address, providing information on evaluated metadata as part of the evaluation process.\n","parameters":[{"name":"email","required":true,"in":"query","description":"The email address that will be verified","schema":{"format":"email","example":"john.smith@gmail.com","type":"string"}}],"responses":{"200":{"description":"Details of the email deliverability and metadata","content":{"application/json":{"schema":{"type":"object","required":["email","result","internalResult","mxServer","mxServerIp","esp","account","tag","isRole","isFree","isNoReply","firstName","lastName","gender"],"properties":{"email":{"type":"string","format":"email","example":"john.smith+123@gmail.com","description":"Verified email"},"result":{"type":"string","example":"email_disabled","enum":["ok","unknown","dead_server","invalid_mx","email_disabled","antispam_system","ok_for_all","smtp_protocol","invalid_syntax","disposable","spamtrap"],"description":"The deliverability status of the email address"},"internalResult":{"type":"string","example":"mailbox_not_found","description":"The internal status of the email address processing","nullable":true},"mxServer":{"type":"string","format":"hostname","example":"gmail-smtp-in.l.google.com","description":"MX server associated with the email domain.","nullable":true},"mxServerIp":{"type":"string","format":"ipv4","example":"142.250.27.27","description":"IP address corresponding to the MX server.","nullable":true},"esp":{"type":"string","example":"Google","enum":["Google","iCloud","AOL","Yahoo","Zoho Mail","Proton Mail","Microsoft 365","Seznam","Namecheap","Yandex","Mail.ru"],"description":"ESP of the email address","nullable":true},"account":{"type":"string","example":"john.smith","description":"Local part of the email address"},"tag":{"type":"string","example":"123","description":"Tag part of the email address","nullable":true},"isRole":{"type":"boolean","example":"false","description":"Signifies if the email pertains to a specific business-related role within a company rather than an individual. Such emails typically feature names such as 'info' or 'support'"},"isFree":{"type":"boolean","example":"true","description":"Indicates the potential for creating a free email account using the same domain (e.g. has _@gmail.com_ domain)."},"isNoReply":{"type":"boolean","example":"false","description":"Denotes whether the email's inbox is actively monitored for incoming messages. Typically, these emails feature names such as 'noreply' or 'no-reply'."},"firstName":{"type":"string","example":"John","description":"Estimation of the first name of the person associated with the email address.","nullable":true},"lastName":{"type":"string","example":"Smith","description":"Estimation of the last name of the person associated with the email address.","nullable":true},"gender":{"type":"string","enum":["male","female"],"example":"male","description":"Estimation of the gender of the person associated with the email address.","nullable":true}}}}}},"400":{"content":{"application/json":{"examples":{"ApiTooManyRequestsException":{"description":"Too many requests coming from your API key.","value":{"statusCode":400,"message":"Too many requests coming from your API key.","error":"TooManyRequests"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Too many requests coming from your API key."},"error":{"type":"string","example":"TooManyRequests"}},"required":["statusCode","message"]}}},"description":""},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"403":{"content":{"application/json":{"examples":{"NotEnoughCreditException":{"description":"Not enough credit, <amount> required.","value":{"statusCode":403,"message":"Not enough credit, <amount> required.","error":"Forbidden"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":403},"message":{"type":"string","example":"Not enough credit, <amount> required."},"error":{"type":"string","example":"Forbidden"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/emailJobs":{"post":{"operationId":"createEmailJob","summary":"Create asynchronous job that verifies email deliverability","description":"\n## Create asynchronous job that verifies email deliverability\n\n#### Rate limit: 100 requests in 1 second\n\n#### Credits required: Based on the quality\n- **Standard:** 1 credit\n- **High:** 2 credits\n\nThis API endpoint initiates an asynchronous task to assess the deliverability status of an individual email address. Additionally, the result includes details on the processed metadata during the evaluation. Users need to query the job later to check its progress or access the final outcome. Please be aware that jobs of **standard** quality may require up to 1 minute for completion, whereas **high** quality jobs may take up to 30 minutes due to potential greylisting delays.\n","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmailJobDto"}}}},"responses":{"201":{"description":"ID","content":{"application/json":{"schema":{"type":"object","required":["id","email","quality"],"properties":{"id":{"type":"string","example":"67fa2fb9eff3c4a985b4ee52","description":"ID of the created job"},"email":{"type":"string","format":"email","example":"john.smith@gmail.com","description":"Email to be verified by the job"},"quality":{"type":"string","format":"email","example":"high","enum":["standard","high"],"description":"Quality of the email verification. If not present, the default value is **standard**"}}}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"403":{"content":{"application/json":{"examples":{"NotEnoughCreditException":{"description":"Not enough credit, <amount> required.","value":{"statusCode":403,"message":"Not enough credit, <amount> required.","error":"Forbidden"}},"TooManyEmailJobsException":{"description":"Too many running email jobs","value":{"statusCode":403,"message":"Too many running email jobs","error":"Forbidden"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":403},"message":{"type":"string","example":"Not enough credit, <amount> required."},"error":{"type":"string","example":"Forbidden"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/emailJobs/{id}":{"get":{"operationId":"getEmailJob","summary":"Verify email deliverability","description":"\n## Verify email deliverability\n\n#### Rate limit: 100 requests in 1 second\n\nThis endpoint retrieves status of an asynchronous email job including result and information on evaluated metadata if it's already finished.\n","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Deliverability status of the email address","content":{"application/json":{"schema":{"type":"object","required":["id","email","quality","status","hasGreylist","result","finishedAt","createdAt"],"properties":{"id":{"type":"string","example":"67fa2fb9eff3c4a985b4ee52","description":"ID of the created job"},"email":{"type":"string","format":"email","example":"john.smith@gmail.com","description":"Email that is being verified by the job"},"quality":{"type":"string","format":"email","example":"high","enum":["standard","high"],"description":"Quality of the email verification."},"status":{"type":"string","enum":["processing","finished"],"example":"processing","description":"Status of the asynchronous email job"},"hasGreylist":{"type":"boolean","example":false,"description":"Says whether the verification processing is currently facing an anti-spam measure called **greylisting**, which may postpone verification process by up to 30 minutes."},"finishedAt":{"type":"string","format":"date-time","example":"2024-11-15T11:57:15.909Z","description":"Date when the job has finished, in ISO 8601 format."},"createdAt":{"type":"string","format":"date-time","example":"2024-11-15T12:13:49.182Z","description":"Date when the job was created, in ISO 8601 format."},"result":{"nullable":true,"type":"object","required":["email","result","internalResult","mxServer","mxServerIp","esp","account","tag","isRole","isFree","isNoReply","firstName","lastName","gender"],"properties":{"email":{"type":"string","format":"email","example":"john.smith+123@gmail.com","description":"Verified email"},"result":{"type":"string","example":"email_disabled","enum":["ok","unknown","dead_server","invalid_mx","email_disabled","antispam_system","ok_for_all","smtp_protocol","invalid_syntax","disposable","spamtrap"],"description":"The deliverability status of the email address"},"internalResult":{"type":"string","example":"mailbox_not_found","description":"The internal status of the email address processing","nullable":true},"mxServer":{"type":"string","format":"hostname","example":"gmail-smtp-in.l.google.com","description":"MX server associated with the email domain.","nullable":true},"mxServerIp":{"type":"string","format":"ipv4","example":"142.250.27.27","description":"IP address corresponding to the MX server.","nullable":true},"esp":{"type":"string","example":"Google","enum":["Google","iCloud","AOL","Yahoo","Zoho Mail","Proton Mail","Microsoft 365","Seznam","Namecheap","Yandex","Mail.ru"],"description":"ESP of the email address","nullable":true},"account":{"type":"string","example":"john.smith","description":"Local part of the email address"},"tag":{"type":"string","example":"123","description":"Tag part of the email address","nullable":true},"isRole":{"type":"boolean","example":"false","description":"Signifies if the email pertains to a specific business-related role within a company rather than an individual. Such emails typically feature names such as 'info' or 'support'"},"isFree":{"type":"boolean","example":"true","description":"Indicates the potential for creating a free email account using the same domain (e.g. has _@gmail.com_ domain)."},"isNoReply":{"type":"boolean","example":"false","description":"Denotes whether the email's inbox is actively monitored for incoming messages. Typically, these emails feature names such as 'noreply' or 'no-reply'."},"firstName":{"type":"string","example":"John","description":"Estimation of the first name of the person associated with the email address.","nullable":true},"lastName":{"type":"string","example":"Smith","description":"Estimation of the last name of the person associated with the email address.","nullable":true},"gender":{"type":"string","enum":["male","female"],"example":"male","description":"Estimation of the gender of the person associated with the email address.","nullable":true}}}}}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"404":{"content":{"application/json":{"examples":{"EmailJobNotFoundException":{"description":"Email job not found","value":{"statusCode":404,"message":"Email job not found","error":"NotFound"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":404},"message":{"type":"string","example":"Email job not found"},"error":{"type":"string","example":"NotFound"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/verifyApiFile":{"post":{"operationId":"verifyApiFile","summary":"Upload email list","description":"\n## Upload email list\n\n#### Rate limit: 5 requests in 1 second\n\n#### Credits required: Based on the number of valid and unique emails found in the file and the quality\n- **Standard:** 1 credit per email\n- **High:** 2 credits per email\n\nBefore you begin the upload, make sure your email list file meets these formatting requirements:\n  - The file format is *.csv*, *.txt*, or *.xlsx*\n  - One email address per row\n  - File does not exceed 100 MB\n  - Email addresses are placed in the same column\n  - The spreadsheet should not have more than 1,000,000 rows\n\nFor example, this is a valid email list:\n| First Name | Last Name | Email | Company | Phone | Added |\n| ---------- | ---------- | ---------- | ---------- | ---------- | ---------- |\n| Sienna | Schuster | Sienna_Schuster91@gmail.com | Haley and Bechtelar | (719) 472-6351 x8875 | Apr 3rd 2025 |\n| Kale | Parker | Kale.Parker9@yahoo.com | Kub LLC | 790.549.8766 x9145 | Feb 6th 2024 |\n| Florine | Sipes | Florine.Sipes@hotmail.com | Marquardt LLC | (881) 624-2788 x120 | Mar 6th 2025 |\n| Rebeca | Grady | Rebeca.Grady@hotmail.com | Buckridge - Kshlerin | (245) 226-4323 | May 1st 2025 |\n| Jeanie | McGlynn-Dicki | Jeanie_McGlynn-Dicki@yahoo.com | O'Connell Group | 1-773-534-2564 | Dec 12th 2024 |\n| Adela | Franey | Adela_Franey17@gmail.com | Connelly Inc | 1-638-484-8311 x2970 | Dec 14th 2023 |\n| Carmela | Sipes | Carmela_Sipes@hotmail.com | Lubowitz and Schowalter | 507-649-5761 x31543 | Mar 30th 2024 |\n| Ladarius | Metz | Ladarius.Metz@yahoo.com | Glover - Ziemann | (871) 854-6314 x525 | Oct 29th 2025 |\n| Allen | Hirthe | Allen.Hirthe49@hotmail.com | Schuppe - Lemke | 1-462-480-1998 x9315 | May 22nd 2024 |\n\nAnd its corresponding raw *.csv* file ready for upload:\n```\nFirst Name,Last Name,Email,Company,Phone,Added\nSienna,Schuster,Sienna_Schuster91@gmail.com,Haley and Bechtelar,(719) 472-6351 x8875,Apr 3rd 2025\nKale,Parker,Kale.Parker9@yahoo.com,Kub LLC,790.549.8766 x9145,Feb 6th 2024\nFlorine,Sipes,Florine.Sipes@hotmail.com,Marquardt LLC,(881) 624-2788 x120,Mar 6th 2025\nRebeca,Grady,Rebeca.Grady@hotmail.com,Buckridge - Kshlerin,(245) 226-4323,May 1st 2025\nJeanie,McGlynn-Dicki,Jeanie_McGlynn-Dicki@yahoo.com,O'Connell Group,1-773-534-2564,Dec 12th 2024\nAdela,Franey,Adela_Franey17@gmail.com,Connelly Inc,1-638-484-8311 x2970,Dec 14th 2023\nCarmela,Sipes,Carmela_Sipes@hotmail.com,Lubowitz and Schowalter,507-649-5761 x31543,Mar 30th 2024\nLadarius,Metz,Ladarius.Metz@yahoo.com,Glover - Ziemann,(871) 854-6314 x525,Oct 29th 2025\nAllen,Hirthe,Allen.Hirthe49@hotmail.com,Schuppe - Lemke,1-462-480-1998 x9315,May 22nd 2024\n```\n\nAfter successfully uploading the email list, the HTTP response will return an ID which you can use to query for the bulk verification progress using the endpoint `/api/maillists/{id}/progress`.\n","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file_contents"],"properties":{"file_contents":{"type":"string","format":"binary"},"quality":{"type":"string","nullable":false,"enum":["standard","high"],"default":"standard","example":"high","description":"Quality of the email list verification. If not present, the default value is **standard**"}}}}}},"responses":{"201":{"description":"ID of the successufully uploaded email list","content":{"text/html":{"schema":{"type":"string","example":"2616806","description":"ID of the successufully uploaded email list"}}}},"400":{"content":{"application/json":{"examples":{"BadMaillistFileException":{"description":"Property `file_contents` in the form data does not contain the uploaded file","value":{"statusCode":400,"message":"Property `file_contents` in the form data does not contain the uploaded file","error":"BadRequest"}},"TooManyLinesException":{"description":"File has too many lines (max 1,000,000)","value":{"statusCode":400,"message":"File has too many lines (max 1,000,000)","error":"BadRequest"}},"BadMaillistFormatException":{"description":"Only .csv, .txt or .xlsx files are accepted","value":{"statusCode":400,"message":"Only .csv, .txt or .xlsx files are accepted","error":"BadRequest"}},"FileTooLargeException":{"description":"File is too large (max 100MB)","value":{"statusCode":400,"message":"File is too large (max 100MB)","error":"BadRequest"}},"EmptyMaillistException":{"description":"Uploaded maillist file does not contain any valid emails","value":{"statusCode":400,"message":"Uploaded maillist file does not contain any valid emails","error":"BadRequest"}},"MaillistAlreadyUploadedException":{"description":"You have already uploaded a maillist file with this name","value":{"statusCode":400,"message":"You have already uploaded a maillist file with this name","error":"BadRequest"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Property `file_contents` in the form data does not contain the uploaded file"},"error":{"type":"string","example":"BadRequest"}},"required":["statusCode","message"]}}},"description":""},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"403":{"content":{"application/json":{"examples":{"NotEnoughCreditException":{"description":"Not enough credit, <amount> required.","value":{"statusCode":403,"message":"Not enough credit, <amount> required.","error":"Forbidden"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":403},"message":{"type":"string","example":"Not enough credit, <amount> required."},"error":{"type":"string","example":"Forbidden"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/findContact":{"post":{"operationId":"findContact","summary":"Search for email address of a contact","description":"\n## Search for email address of a contact\n\n#### Rate limit: 5 requests in 1 second\n\n#### Credits required:\n- **5:** If the first name, the last name, or both are provided.\n- **10:** If only the domain is provided.\n\nThis endpoint is specifically configured to facilitate the discovery of a contact's **business email address**. By supplying the contact's optional first name, optional last name, and mandatory company email domain, a series of potential email addresses will be generated. These addresses will then undergo verification for deliverability, following which our **level of confidence** in each email will be assessed to identify the most appropriate match for the contact's primary email address.\n\nThe variety and quantity of emails generated will be dependent on the presence of optional parameters:\n- **Both First Name and Last Name:** A search will be conducted for several potential combinations of the name format (e.g., *john.smith@company.com*, *smithjohn@company.com*).\n- **Only One of the Names:** A search will be carried out for one potential email address (e.g., *john@company.com*).\n- **Only Domain:** A search will be conducted for around twenty business-related emails associated with the company (e.g., *info@company.com*, *support@domain.com*).\n\nGiven that the number of emails generated for verification may vary, distinct credit amounts are charged accordingly.\n\nLastly, the confidence levels assigned to each generated email will fall into one of the following categories:\n- **high:** The email is deliverable and precisely aligns with the contact's name or the role within the company. It is expected to reach the intended recipient securely.\n- **medium:** The email is deliverable, although the contact's name may only be partially matched. The email might lead to a different person with a similar name within the company.\n- **low:** The email is deliverable, but the domain is associated with a free email service provider (e.g., _gmail.com_). This email may not reach the expected individual.\n- **unknown:** The email's deliverability is uncertain, or our verification was partially obstructed by anti-spam protection mechanisms.\n","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindContactDto"}}}},"responses":{"201":{"description":"Possible contact's emails and their details","content":{"application/json":{"schema":{"type":"array","example":[{"email":"adela.franey@connelycorp.com","confidence":"high"},{"email":"franey.adela@connelycorp.com","confidence":"unknown"},{"email":"a.franey@connelycorp.com","confidence":"high"},{"email":"franey.a@connelycorp.com","confidence":"unknown"},{"email":"adelafraney@connelycorp.com","confidence":"unknown"},{"email":"franeyadela@connelycorp.com","confidence":"unknown"},{"email":"adela@connelycorp.com","confidence":"medium"},{"email":"franey@connelycorp.com","confidence":"unknown"}],"items":{"type":"object","required":["email","confidence","result","internalResult","mxServer","mxServerIp"],"properties":{"email":{"type":"string","format":"email","example":"adela.franey@connelycorp.com"},"confidence":{"type":"string","enum":["unknown","low","medium","high"],"example":"high"},"result":{"type":"string","example":"ok","enum":["ok","unknown","dead_server","invalid_mx","email_disabled","antispam_system","ok_for_all","smtp_protocol","invalid_syntax","disposable","spamtrap"],"description":"The deliverability status of the email address"},"internalResult":{"type":"string","example":"mailbox_problem","description":"The internal status of the email address processing","nullable":true},"mxServer":{"type":"string","format":"hostname","example":"gmail-smtp-in.l.google.com","description":"MX server associated with the email domain.","nullable":true},"mxServerIp":{"type":"string","format":"ipv4","example":"142.250.27.27","description":"IP address corresponding to the MX server.","nullable":true}}}}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"403":{"content":{"application/json":{"examples":{"NotEnoughCreditException":{"description":"Not enough credit, <amount> required.","value":{"statusCode":403,"message":"Not enough credit, <amount> required.","error":"Forbidden"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":403},"message":{"type":"string","example":"Not enough credit, <amount> required."},"error":{"type":"string","example":"Forbidden"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/checkDisposable":{"post":{"operationId":"checkDisposable","summary":"Verify if a domain is disposable","description":"\n## Verify if a domain is disposable\n\n#### Rate limit: 50 requests in 1 second\n\n#### Credits required: 1\n\nThis API endpoint serves to determine if an email domain is associated with the generation of temporary email addresses. The purpose of this verification is to provide a faster alternative to the `verifyEmail` deliverability check, specifically for safeguarding registration endpoints. In addition to the disposability check, this operation includes the verification of the domain's DNS records for correct configuration. The response generated by this endpoint is formatted as a JSON object, with the `result` field indicating the disposability status of the domain. The `result` value can be one of the following:\n\n| Result | Description |\n| -------- | ------- |\n| `disposable` | The email domain is recognized for issuing temporary email addresses, which may result in bounced emails, non-receipt, or delivery to unintended recipients. |\n| `ok` | The email domain hosts legitimate email addresses and is capable of receiving incoming emails without issue. |\n| `dead_server` | Denotes that the email domain is nonexistent or lacks the appropriate MX server configuration, resulting in bounced emails back to the sender. |\n| `invalid_mx` | Indicates misconfigured MX servers for the email domain, leading to bounced emails returned to the sender. |\n| `unknown` | The presence of an unknown error prevents verification of the disposability status of the email domain, with no deduction of credits for the verification request. |\n","parameters":[{"name":"domain","required":true,"in":"query","description":"The email domain to check","schema":{"maxLength":255,"example":"temporarydomain.net","type":"string"}}],"responses":{"201":{"description":"The email domain details along with its disposability status.","content":{"application/json":{"schema":{"type":"object","required":["domain","result","internalResult","mxServer","mxServerIp"],"properties":{"domain":{"type":"string","format":"hostname","example":"temporarydomain.net","description":"The email domain"},"result":{"type":"string","example":"disposable","description":"The domain's disposability status.","enum":["ok","disposable","dead_server","invalid_mx","unknown"]},"internalResult":{"nullable":true,"type":"string","example":"dynamic_disposable_domain","description":"The internal status of the disposable domain processing"},"mxServer":{"nullable":true,"type":"string","format":"hostname","example":"mx.temporarydomain.net","description":"MX server associated with the email domain."},"mxServerIp":{"nullable":true,"type":"string","format":"ipv4","example":"30.194.93.51","description":"IP address corresponding to the MX server."}}}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"403":{"content":{"application/json":{"examples":{"NotEnoughCreditException":{"description":"Not enough credit, <amount> required.","value":{"statusCode":403,"message":"Not enough credit, <amount> required.","error":"Forbidden"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":403},"message":{"type":"string","example":"Not enough credit, <amount> required."},"error":{"type":"string","example":"Forbidden"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/checkBlacklists":{"post":{"operationId":"checkBlacklists","summary":"Check IP or domain against blacklists","description":"\n## Check IP or domain against blacklists\n\n#### Rate limit: 10 requests in 1 second\n\n#### Credits required: 10\n\nThis API endpoint checks an IP address (IPv4 or IPv6) or domain against multiple DNS-based blacklists (DNSBLs) to determine if it has been listed for spam, malicious activity, or other reputation issues. The endpoint automatically detects the type of value provided (IPv4, IPv6, or domain) and queries the appropriate blacklist providers.\n\nThis check is useful for monitoring IP reputation, preventing spam, and ensuring email deliverability.\n","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckBlacklistsDto"}}}},"responses":{"201":{"description":"The blacklist check results","content":{"application/json":{"schema":{"type":"object","required":["type","value","blacklists"],"properties":{"type":{"type":"string","enum":["IPv4","IPv6","Domain"],"example":"IPv4","description":"The detected type of the checked value"},"value":{"type":"string","example":"172.75.233.15","description":"The IP address or domain that was checked"},"blacklists":{"type":"array","description":"Blacklist providers that have listed this IP/domain","items":{"type":"object","required":["name","url","domain"],"properties":{"name":{"type":"string","example":"Spamhaus ZEN","description":"Name of the blacklist provider"},"url":{"type":"string","example":"https://www.spamhaus.org/zen/","description":"URL to the blacklist provider information"},"domain":{"type":"string","example":"zen.dq.spamhaus.net","description":"Domain of the blacklist used in the DNS query"},"description":{"nullable":true,"type":"string","example":"Listed by SBL, see https://check.spamhaus.org/sbl/query/SBL123456","description":"Additional information about the listing which usually includes delisting instructions"}}}}}}}}},"400":{"content":{"application/json":{"examples":{"BadBlacklistCheckValueException":{"description":"Value is not a valid IP address or Domain name.","value":{"statusCode":400,"message":"Value is not a valid IP address or Domain name.","error":"BadRequest"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Value is not a valid IP address or Domain name."},"error":{"type":"string","example":"BadRequest"}},"required":["statusCode","message"]}}},"description":""},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"403":{"content":{"application/json":{"examples":{"NotEnoughCreditException":{"description":"Not enough credit, <amount> required.","value":{"statusCode":403,"message":"Not enough credit, <amount> required.","error":"Forbidden"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":403},"message":{"type":"string","example":"Not enough credit, <amount> required."},"error":{"type":"string","example":"Forbidden"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/maillists/{id}/progress":{"get":{"operationId":"maillistProgress","summary":"Retrieve progress information of email list","description":"\n## Retrieve progress information of email list\n\n#### Rate limit: 100 requests in 1 second\n\nRetrieve real-time progress updates for an uploaded email list. This endpoint offers insights into the verification process, with the `status` enum conveying the following values:\n\n| Status | Description |\n| ------ | ----------- |\n| `uploaded` | The email list has been successfully uploaded and is awaiting processing. |\n| `processing` | Verification of the email list is currently underway. Utilize the 'progress' property to monitor its completion. |\n| `finished` | Verification of the email list is complete. Access the download URL to obtain the results. |\n| `inQueue` | The maximum limit for concurrent email list verifications has been reached, set to 5 by default. The list will commence processing automatically as existing verifications are finalized. |\n| `starting` | The verification process for the email list is commencing. Emails are being queued for verification. |\n| `error` | Verification of the email list encountered an unknown error. **All credits have been returned** for this email list. |\n\nAdditionally, details regarding credit handling for the email list are provided, comprising two distinct values:\n - **charged:** The number of credits deducted based on the quantity of valid email addresses identified in the file. **Duplicate email addresses are not charged.**\n - **returned:** The number of credits returned when the email list is finished, for emails with non-chargeable verification results (e.g. _antispam_system_).\n","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","required":["status","progress","credits","name","createdAt","updatedAt"],"properties":{"status":{"type":"string","enum":["uploaded","processing","finished","inQueue","starting","error"],"example":"processing","description":"Status of the email list"},"progress":{"type":"integer","minimum":0,"maximum":100,"example":42,"description":"Percentage of completion of the email list"},"credits":{"type":"object","required":["charged","returned"],"properties":{"charged":{"nullable":true,"type":"integer","minimum":0,"example":123,"description":"Credit amount deducted to commence the email list, displayed as null if no credits have been deducted yet."},"returned":{"nullable":true,"type":"integer","minimum":0,"example":16,"description":"Credit amount refunded upon completion of the email list for unsuccessful verifications, indicated as null if no credits were returned thus far."}}},"name":{"type":"string","example":"my_email_list.csv","description":"Name of the uploaded email list"},"createdAt":{"type":"string","format":"date-time","example":"2024-11-15T11:57:15.909Z","description":"Date when the email list was uploaded, in ISO 8601 format."},"updatedAt":{"type":"string","format":"date-time","example":"2024-11-15T12:19:38.532Z","description":"Date when the email list's progerss was last updated, in ISO 8601 format."}}}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"404":{"content":{"application/json":{"examples":{"MaillistNotFoundException":{"description":"Email list not found","value":{"statusCode":404,"message":"Email list not found","error":"NotFound"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":404},"message":{"type":"string","example":"Email list not found"},"error":{"type":"string","example":"NotFound"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/maillists/{id}":{"get":{"operationId":"downloadMaillist","summary":"Download finished email list","description":"\n## Download finished email list\n\n#### Rate limit: 5 requests in 1 second\n\nOnce the verification of the email list is completed, you have the option to download the result file, which includes the verification outcomes in a distinct column. By default, a single column is added on the far left, identified by the custom header 'ELV Result'. This column showcases the verification status of each row's email address. If a row contains either no email addresses or more than two, making it challenging to select valid input for verification, the result field displays a blank value (-). Here is an example of the downloaded result without utilizing any query parameters:\n\n| ELV Result | First Name | Last Name | Email | Company | Phone | Added |\n| ---------- | ---------- | ---------- | ---------- | ---------- | ---------- | ---------- |\n| ok | Sienna | Schuster | Sienna_Schuster91@gmail.com | Haley and Bechtelar | (719) 472-6351 x8875 | Apr 3rd 2025 |\n| disposable | Kale | Parker | Kale.Parker9@yahoo.com | Kub LLC | 790.549.8766 x9145 | Feb 6th 2024 |\n| email_disabled | Florine | Sipes | Florine.Sipes@hotmail.com | Marquardt LLC | (881) 624-2788 x120 | Mar 6th 2025 |\n| unknown | Rebeca | Grady | Rebeca.Grady@hotmail.com | Buckridge - Kshlerin | (245) 226-4323 | May 1st 2025 |\n| ok_for_all | Jeanie | McGlynn-Dicki | Jeanie_McGlynn-Dicki@yahoo.com | O'Connell Group | 1-773-534-2564 | Dec 12th 2024 |\n| smtp_protocol | Adela | Franey | Adela_Franey17@gmail.com | Connelly Inc | 1-638-484-8311 x2970 | Dec 14th 2023 |\n| dead_server | Carmela | Sipes | Carmela_Sipes@hotmail.com | Lubowitz and Schowalter | 507-649-5761 x31543 | Mar 30th 2024 |\n| smtp_protocol | Ladarius | Metz | Ladarius.Metz@yahoo.com | Glover - Ziemann | (871) 854-6314 x525 | Oct 29th 2025 |\n| ok | Allen | Hirthe | Allen.Hirthe49@hotmail.com | Schuppe - Lemke | 1-462-480-1998 x9315 | May 22nd 2024 |\n\nNevertheless, this endpoint provides a range of query parameters to customize the columns and rows of the email list file extensively.\n","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the finished email list","schema":{"example":"2200875","type":"string"}},{"name":"addFirstName","required":false,"in":"query","description":"Adds a column 'ELV First Name' with an estimation of the first name of the person associated with the email address.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addLastName","required":false,"in":"query","description":"Adds a column named 'ELV Last Name' with an estimation of the last name of the person associated with the email address.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addGender","required":false,"in":"query","description":"Adds a column named 'ELV Gender' with an estimation of the gender of the person associated with the email address.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addIsNoReply","required":false,"in":"query","description":"Adds a column named 'ELV Is No Reply' with values denoting whether the email's inbox is actively monitored for incoming messages. Typically, these emails feature names such as 'noreply' or 'no-reply'.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addIsFree","required":false,"in":"query","description":"Adds a column named 'ELV Is Free' containing values that indicate the potential for creating a free email account using the same domain.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addIsRole","required":false,"in":"query","description":"Adds a column named 'ELV Is Role' to signify if the email pertains to a specific business-related role within a company rather than an individual. Such emails typically feature names such as 'info' or 'support'.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addResult","required":false,"in":"query","description":"Adds a column named 'ELV Result' displaying the result of the verification process of the row's email.","schema":{"format":"boolean","default":"true","example":"true","type":"string"}},{"name":"addEmail","required":false,"in":"query","description":"Adds a column named 'ELV Email' displaying the exact email that was used as an input during the verification process.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addOriginal","required":false,"in":"query","description":"Includes all columns from the uploaded file that do not contain email information (e.g., Phone, Address).","schema":{"format":"boolean","default":"true","example":"true","type":"string"}},{"name":"addNoEmailRows","required":false,"in":"query","description":"Adds rows that do not contain precisely one email and cannot undergo verification due to insufficient input. These rows are assigned a blank deliverability status (-)","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addDuplicates","required":false,"in":"query","description":"Eliminates duplicate emails from the email list, retaining only the first occurrence of each email.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addMxServer","required":false,"in":"query","description":"Adds a column named 'ELV MX Server' displaying the MX server associated with the domain of the email.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addEsp","required":false,"in":"query","description":"Adds a column named 'ELV ESP' displaying the Email Service Provider associated with the domain of the email.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"addInternalResult","required":false,"in":"query","description":"Adds a column named 'ELV Internal Result' displaying the internal verification result given by the system.","schema":{"format":"boolean","default":"false","example":"false","type":"string"}},{"name":"format","required":false,"in":"query","description":"Select the format of the downloaded email list file.","schema":{"example":"csv","enum":["csv","xlsx"],"type":"string"}},{"name":"results","required":false,"in":"query","description":"Adds rows containing the verification result within this parameter. The parameter's value comprises a list of deliverability statuses separated by commas.","schema":{"default":"*all*","example":"ok,email_disabled,antispam_system","type":"string"}}],"responses":{"200":{"content":{"text/csv":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"octet/stream":{"schema":{"type":"string","format":"binary"}}},"description":"Response body contains the email list email list file - either text (.csv), or binary (.xlsx)"},"400":{"content":{"application/json":{"examples":{"MaillistNotFinishedException":{"description":"Maillist has not finished yet","value":{"statusCode":400,"message":"Maillist has not finished yet","error":"BadRequest"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Maillist has not finished yet"},"error":{"type":"string","example":"BadRequest"}},"required":["statusCode","message"]}}},"description":""},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"404":{"content":{"application/json":{"examples":{"MaillistNotFoundException":{"description":"Email list not found","value":{"statusCode":404,"message":"Email list not found","error":"NotFound"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":404},"message":{"type":"string","example":"Email list not found"},"error":{"type":"string","example":"NotFound"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]},"delete":{"operationId":"deleteMaillist","summary":"Delete finished email list","description":"\n## Delete finished email list\n\n#### Rate limit: 100 requests in 1 second\n\nOnce the verification of the email list is completed, you have the option to delete it.\n","parameters":[{"name":"id","required":true,"in":"path","description":"ID of the finished email list","schema":{"example":"2200875","type":"string"}}],"responses":{"204":{"description":"The email list has been successfully deleted"},"400":{"content":{"application/json":{"examples":{"MaillistNotFinishedException":{"description":"Maillist has not finished yet","value":{"statusCode":400,"message":"Maillist has not finished yet","error":"BadRequest"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":400},"message":{"type":"string","example":"Maillist has not finished yet"},"error":{"type":"string","example":"BadRequest"}},"required":["statusCode","message"]}}},"description":""},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"404":{"content":{"application/json":{"examples":{"MaillistNotFoundException":{"description":"Email list not found","value":{"statusCode":404,"message":"Email list not found","error":"NotFound"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":404},"message":{"type":"string","example":"Email list not found"},"error":{"type":"string","example":"NotFound"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/credits":{"get":{"operationId":"credits","summary":"Retrieve details regarding your available credits","description":"\n## Retrieve details regarding your available credits\n\n#### Rate limit: 10 requests in 1 second\n\nDescription of the available on-demand and daily credit allocations. On-demand credits retain their validity indefinitely, allowing flexibility in their utilization at any time. Daily credits are replenished on a daily basis and are accessible solely during the active subscription period. No credits are charged for this request.\n","parameters":[],"responses":{"200":{"description":"Details of the available credits","content":{"application/json":{"schema":{"type":"object","required":["onDemand","subscription"],"properties":{"onDemand":{"type":"object","required":["available"],"properties":{"available":{"type":"integer","minimum":0,"example":42,"description":"Remaining balance of on-demand credits."}}},"subscription":{"nullable":true,"type":"object","required":["available","expiresAt"],"properties":{"available":{"type":"integer","minimum":0,"example":15000,"description":"Remaining credits available for use within the current subscription period."},"expiresAt":{"type":"string","format":"date-time","example":"2024-06-19T00:00:00.000Z","description":"Expiration date of the current subscription period in ISO 8601 format."}}}}}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Verification Endpoints"]}},"/api/inboxPlacementTests":{"post":{"operationId":"createPlacementTest","summary":"Create inbox placement test","description":"\n## Create inbox placement test\n\n#### Rate limit: 20 requests in 1 second\n\n#### Credits required: 100\n\nThis endpoint creates a new inbox placement test to evaluate where your emails land across different email service providers (Gmail, Yahoo, Outlook, etc.).\n\n### How it works:\n\n1. **Call this endpoint** to create a test. Optionally provide:\n   - A name for the test (for easier identification)\n   - A webhook URL to receive results automatically when the test completes\n2. **You will receive**:\n   - A unique tracking code (e.g., `ELV-A1B2C3D4E5`)\n   - A list of seed email addresses to send your test email to\n   - A test ID for polling results\n3. **Send a test email** from your production email system (the one you want to test) to **all** the provided seed email addresses\n4. **Include the tracking code** in your email subject or body so the system can identify your test\n5. **Get results** either by:\n   - Polling the `GET /api/inboxPlacementTests/{code}` endpoint every 30-60 seconds\n   - Waiting for automatic webhook notification (if webhook URL was provided)\n\n### Important notes:\n\n- The test typically completes within **5-10 minutes** after you send the emails\n- 100 credits are charged upfront\n- If no placement is detected (all emails missing/waiting), **100 credits will be refunded automatically**\n- If at least one email is detected (inbox/spam/promotions), the test is considered billable and credits are kept\n- Webhook notifications are sent as POST requests with the complete test results when status becomes \"complete\"\n\n### Example workflow:\n\n1. POST /api/inboxPlacementTests with optional name and webhookUrl parameters\n2. Receive tracking code and list of seed email addresses\n3. Send email from YOUR production system to all seed emails with tracking code in subject/body\n4. Get results via polling or webhook notification\n","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePlacementTestViaOpenApiDto"}}}},"responses":{"201":{"description":"Placement test created successfully","content":{"application/json":{"schema":{"type":"object","required":["id","code","name","emails","status","createdAt"],"properties":{"id":{"type":"string","example":"507f1f77bcf86cd799439011","description":"Unique identifier for the placement test (MongoDB ObjectId)"},"code":{"type":"string","example":"ELV-A1B2C3D4E5","pattern":"^ELV-[A-Z0-9]{10}$","description":"Tracking code to include in test emails"},"name":{"type":"string","example":"Q1 2025 Campaign Test","description":"Name of the placement test"},"emails":{"type":"array","items":{"type":"string","format":"email"},"example":["test1@gmail.com","test2@yahoo.com","test3@outlook.com"],"description":"List of seed email addresses to send your test email to"},"status":{"type":"string","enum":["running","complete"],"example":"running","description":"Current status of the placement test"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-27T16:55:00.000Z","description":"Timestamp when the test was created, in ISO 8601 format"}}}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"403":{"content":{"application/json":{"examples":{"NotEnoughCreditException":{"description":"Not enough credit, <amount> required.","value":{"statusCode":403,"message":"Not enough credit, <amount> required.","error":"Forbidden"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":403},"message":{"type":"string","example":"Not enough credit, <amount> required."},"error":{"type":"string","example":"Forbidden"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Inbox Placement Test Endpoints"]}},"/api/inboxPlacementTests/{code}":{"get":{"operationId":"getPlacementTest","summary":"Get placement test results","description":"\n## Get placement test results\n\n#### Rate limit: 20 requests in 1 second\n\nThis endpoint retrieves the current status and results of a placement test.\n\n### Response includes:\n\n- **Status**: `running` or `complete`\n- **Recipients**: List of all seed emails with their current placement status:\n  - `inbox` - Email landed in primary inbox\n  - `category` - Email landed in promotions/social/updates folder\n  - `spam` - Email landed in spam folder\n  - `waiting` - Email not yet detected (test still running)\n  - `missing` - Email not found (may have bounced or blocked)\n- **Sender**: The email address that sent the test (detected automatically)\n- **ESP breakdown**: Results grouped by email service provider (Google, Yahoo, Outlook, etc.)\n\n### Polling recommendations:\n\n- Poll every **30-60 seconds** while status is `running`\n- Stop polling when status becomes `complete`\n- Tests typically complete within 5-10 minutes\n","parameters":[{"name":"code","required":true,"in":"path","description":"Tracking code of the placement test","schema":{"example":"ELV-A1B2C3D4E5","type":"string"}}],"responses":{"200":{"description":"Placement test details and results","content":{"application/json":{"schema":{"type":"object","nullable":true,"required":["name","code","status","recipients","summary","createdAt"],"properties":{"userId":{"type":"number","nullable":true,"example":123,"description":"ID of the user who created the test"},"name":{"type":"string","example":"Q1 2025 Campaign Test","description":"Name of the placement test"},"code":{"type":"string","example":"ELV-A1B2C3D4E5","description":"Tracking code for the test"},"status":{"type":"string","enum":["running","complete"],"example":"complete","description":"Current status of the test"},"sender":{"type":"string","format":"email","nullable":true,"example":"campaigns@yourcompany.com","description":"Email address that sent the test (auto-detected)"},"recipients":{"type":"array","items":{"type":"object","required":["email","esp","type","placement"],"properties":{"email":{"type":"string","format":"email","example":"test1@gmail.com","description":"Seed email address"},"esp":{"type":"string","enum":["google","yahoo","outlook","zoho","other"],"example":"google","description":"Email service provider"},"type":{"type":"string","enum":["personal","professional"],"example":"personal","description":"Type of email account"},"placement":{"type":"string","enum":["inbox","category","spam","waiting","missing"],"example":"inbox","description":"Where the email landed"},"foundAt":{"type":"string","format":"date-time","nullable":true,"example":"2025-01-27T17:02:15.000Z","description":"When the email was detected, in ISO 8601 format"}}},"description":"List of seed emails with placement results"},"summary":{"type":"object","required":["inbox","promotions","spam","waiting","missing"],"properties":{"inbox":{"type":"number","example":79,"description":"Percentage of emails that landed in primary inbox"},"promotions":{"type":"number","example":0,"description":"Percentage of emails that landed in promotions/social/updates folder"},"spam":{"type":"number","example":14,"description":"Percentage of emails that landed in spam folder"},"waiting":{"type":"number","example":7,"description":"Percentage of emails not yet detected (test still running)"},"missing":{"type":"number","example":0,"description":"Percentage of emails not found (may have bounced or been blocked)"}},"description":"Summary of placement results as percentages"},"createdAt":{"type":"string","format":"date-time","example":"2025-01-27T16:55:00.000Z","description":"When the test was created, in ISO 8601 format"},"updatedAt":{"type":"string","format":"date-time","nullable":true,"example":"2025-01-27T17:05:00.000Z","description":"When the test was last updated, in ISO 8601 format"}}}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""},"404":{"content":{"application/json":{"examples":{"PlacementTestNotFoundException":{"description":"Placement test with code undefined does not exist !","value":{"statusCode":404,"message":"Placement test with code undefined does not exist !","error":"NotFound"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":404},"message":{"type":"string","example":"Placement test with code undefined does not exist !"},"error":{"type":"string","example":"NotFound"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["Inbox Placement Test Endpoints"]}},"/api/getApiFileInfo":{"get":{"operationId":"getApiFileInfo","summary":"Retrieve progress information of email list","description":"\n## Retrieve progress information of email list\n\n#### Rate limit: 100 requests in 1 second\n\nThis endpoint furnishes progress updates for an uploaded email list encoded in plain text. Depending on the processing state of the email list, the response body may display:\n\n1. <code>errored</code>: An unknown error occurred during the verification of the email list. **No credits were deducted** for this email list.\n\n1. <code>waiting</code>: You have reached the maximum limit of concurrently verifying email lists. The email list will initiate automatically once some of the ongoing verifications are completed.\n\n1. <code>&#124;&lt;id&gt;&#124;&lt;filename&gt;&#124;no&#124;&lt;total_emails&gt;&#124;&lt;processed_emails&gt;&#124;progress&#124;&lt;created_timestamp&gt;&#124;&#124;</code>: The email list verification is in progress.\n\n1. <code>&#124;&lt;id&gt;&#124;&lt;filename&gt;&#124;no&#124;&lt;total_emails&gt;&#124;&lt;total_emails&gt;&#124;finished&#124;&lt;created_timestamp&gt;&#124;&lt;ok_url&gt;&#124;&lt;all_url&gt;&#124;</code>: The email list verification is finished.\n\nThe response bodies in steps 3 and 4 adhere to a custom format where the variables are defined as follows:\n- <code>&lt;id&gt;</code>: ID of the uploaded email list\n\n- <code>&lt;filename&gt;</code>: Name of the uploaded email list\n\n- <code>&lt;total_emails&gt;</code>: The total count of emails identified within the uploaded email list\n\n- <code>&lt;processed_emails&gt;</code>: Total count of emails that have already been verified\n\n- <code>&lt;created_timestamp&gt;</code>: Unix timestamp indicating the time of upload\n\n- <code>&lt;ok_url&gt;</code>: Download URL containing deduplicated emails with `ok` status\n\n- <code>&lt;all_url&gt;</code>: Download URL containing all emails and their corresponding statuses\n","parameters":[{"name":"id","required":true,"in":"query","description":"ID of the successfully uploaded email list","schema":{"example":"2200875","type":"string"}}],"responses":{"200":{"description":"Progress of the successfully uploaded email list","content":{"text/html":{"schema":{"type":"string","example":"2200875|filename.csv|no|100|42|progress|1727212618|https://apps.emaillistverify.com/api/maillists/1904211?addEmail=false&addFirstName=false&addGender=false&addIsFree=false&addIsNoReply=false&addIsRole=false&addLastName=false&addOriginal=true&addResult=true&addDuplicates=false&addNoEmailRows=false&addEsp=false&addMxServer=false&format=csv&results=ok&secret=Ef7TiBga7CxJ973wr1Xl2|https://apps.emaillistverify.com/api/maillists/1904211?addEmail=false&addFirstName=false&addGender=false&addIsFree=false&addIsNoReply=false&addIsRole=false&addLastName=false&addOriginal=true&addResult=true&addDuplicates=true&addNoEmailRows=true&addEsp=false&addMxServer=false&format=csv&results=ok,unknown,dead_server,invalid_mx,email_disabled,antispam_system,ok_for_all,smtp_protocol,invalid_syntax,disposable,spamtrap&secret=Ef7TiBga7CxJ973wr1Xl2","description":"Progress of the successfully uploaded email list"}}}},"401":{"content":{"application/json":{"examples":{"InvalidApiKeyException":{"description":"Invalid api key","value":{"statusCode":401,"message":"Invalid api key","error":"Unauthorized"}}},"schema":{"type":"object","properties":{"statusCode":{"type":"number","example":401},"message":{"type":"string","example":"Invalid api key"},"error":{"type":"string","example":"Unauthorized"}},"required":["statusCode","message"]}}},"description":""}},"security":[{"api_key":[]}],"tags":["[Obsolete] Compatibility Endpoints"]}}},"info":{"title":"EmailListVerify API Documentation","description":"\nWelcome to the EmailListVerify (ELV) Customer API documentation. This guide is designed for developers, system integrators, and API enthusiasts seeking to explore and utilize the features of the EmailListVerify API. Our API facilitates individual email address verification and supports batch verification through file uploads. Accessible as a publicly available REST API server, you can seamlessly integrate ELV into your workflows using HTTP requests with the programming or scripting language of your choice.\n\n## Overview\nEmailListVerify aids in the verification of email address deliverability status. By using the tool, you can ensure the successful delivery of your campaign emails to intended recipients, or safeguard your registration process from fraudulent users. Our verification process directly employs the SMPT protocol to ensure the most up-to-date results. Verify emails individually or in bulk through the following tools:\n- **Single email verification:** Quickly determine the deliverability status of a single email address, providing a simple introduction to ELV API.\n- **Bulk email verification:** Upload a spreadsheet file with an email column for asynchronous verification, also referred to as an email list. Pre-screen deliverable emails before initiating your campaign. The formatting requirements are:\n  - The file format is *.csv*, *.txt*, or *.xlsx*\n  - One email address per row\n  - File does not exceed 100 MB\n  - Email addresses are placed in the same column\n  - The spreadsheet should not have more than 1,000,000 rows\n- **Find contact:** Find a deliverable email based on a contact's first name, last name, and company domain. Alternatively, search for role-based emails of the company, such as _info@company.com_, or _sales@company.com_.\n- **Bulk find contact:** Upload a spreadsheet file with columns denoting first name, last name, and company domain of contacts. This tool is only available in a web app at the moment, [find more details here](https://apps.emaillistverify.com/email-finder).\n  - The spreadsheet should not have more than 40,000 rows\n- **Disposable email check:** Quickly determine if an email address is a temporary one. Suitable for registration processes.\n\n## Verification Steps\n- **DNS Check:** Check the availability of the email domain by confirming the presence of a properly configured MX server, essential for receiving emails.\n- **Spamtrap Detection:** Detect potential spam traps, which can harm sender's inbox health and reputation.\n- **Disposable Check:** Ensure the email address is not generated for temporary use.\n- **Deliverability status:** Utilize the SMTP protocol to verify the deliverability of email addresses.\n- **Accept all Handling:** Detect risky email domains that accept messages sent to any username, potentially causing delivery issues.\n- **Error handling:** Address anti-spam technology protection on SMTP servers and handle unexpected errors without exhausting any credits.\n\n## Deliverability status\nThe verification result of an email address can fall into one of the following categories:\n| Result | Description |\n| --------------------- | ----------- |\n| `ok` | Indicates that the email address is **valid and deliverable**. |\n| `email_disabled` | Indicates that the email address is **disabled or non-existent**, resulting in bounced emails back to the sender. |\n| `dead_server` | Indicates that the email domain does not exist or **lacks proper MX server configuration**, leading to bounced emails back to the sender. |\n| `invalid_mx` | Indicates that the email domain has **misconfigured MX servers**, causing incoming emails to bounce back to the sender. |\n| `disposable` | Indicates that the email domain is associated with **temporary email** addresses that are short-lived, potentially resulting in bounced emails or reaching unintended recipients. |\n| `spamtrap` | Represents an email address designed as a decoy to attract and identify spam emails, potentially **harming the sender's reputation**. Incoming emails are delivered but flagged for monitoring. |\n| `ok_for_all` | Indicates that the email domain **accepts all emails**, regardless of the recipient's actual existence. Incoming emails may or may not bounce back to the sender. |\n| `smtp_protocol` | Signifies that the SMTP communication unexpectedly terminated before verifying deliverability status. **No credits are deducted** for this verification request. |\n| `antispam_system` | Indicates that the destination server's anti-spam measures prevented deliverability status verification. **No credits are deducted** for this verification request. |\n| `unknown` | Denotes an unknown error that prevented verification of email address deliverability. **No credits are deducted** for the verification request. |\n| `invalid_syntax` | Indicates that the input value lacks a valid email address syntax. **No credits are deducted** for this verification request. |\n\n## Verification quality\nThis feature is currently exclusive to bulk email verifications and is designed to reduce the occurrence of *antispam_system*, *smtp_protocol*, and *unknown* statuses. It reflects the level of verification accuracy for each email within the list. The available options are as follows:\n- **Standard:** Represents our traditional verification quality, known for its quick and reliable results. Priced at **1 credit per email**, the standard process includes multiple retry attempts from different IP addresses if encountering the specified statuses or unexpected errors.\n- **High:** Introduces our advanced verification method, priced at **2 credits per email**. This option offers twice the retries from varied IP addresses, which may lead to a slower verification process in extreme cases. However, it significantly reduces the likelihood of encountering the mentioned states. Additionally, the high-quality verification includes a new feature implementing greylisting, a proven anti-spam measure. **Greylisting** involves temporarily rejecting emails from certain senders, later allowing them through after a delay. In such instances, our system retries verification multiple times with varying delays, with a maximum delay of 30 minutes. While this may postpone the verification process for the entire email list by up to 30 minutes, it substantially increases the chances of converting *antispam_system* responses to *ok* or *email_disabled* statuses.\n\n## Inbox Placement Testing\nBeyond verifying email deliverability, understanding where your emails actually land is crucial for campaign success. Our inbox placement test evaluates your email's reputation across major providers:\n- **Create a test:** Request a unique tracking code and list of seed email addresses across Gmail, Yahoo, Outlook, and other providers.\n- **Send from your system:** Send your actual campaign email from your production email system to all provided seed addresses, including the tracking code.\n- **Get placement results:** Discover whether your emails reach the inbox, spam folder, or promotional tabs. Results are typically ready within 5-10 minutes and can be retrieved via polling or automatic webhook notification.\n\nThis tool helps you identify deliverability issues before launching campaigns, allowing you to adjust sender reputation, content, or configuration as needed.\n\n## Authentication\nGenerate your API key in the [API section](https://apps.emaillistverify.com/api) before initiating API requests. All endpoints support two interchangeable authentication methods:\n- Use the `x-api-key` HTTP header (e.g., `cOGs9KY3LNzxe3EBIJ6M5`)\n- Include the `secret` query string parameter in the URL (e.g., `secret=cOGs9KY3LNzxe3EBIJ6M5`)\n\n## Credit Types and Usage\nThe standard pricing for email verification is typically 1 credit per verified email address, although this may vary depending on the specific tool being used. At EmailListVerify, we offer two types of credits that can be purchased through our [pricing page](https://emaillistverify.com/pricing). These credits differ in terms of how they are maintained and charged:\n- **On-Demand Credit:** This option involves a one-time purchase of credits that never expire. You have the flexibility to use these credits at your convenience, but they do not automatically replenish. On-Demand credits are ideal for one-time verification needs or preparing for a specific email campaign.\n- **Daily Credit:** Alternatively, you can choose a subscription plan that provides a recurring allocation of credits. Your credit usage is refreshed at the start of each new billing period. Monthly credits are well-suited for continuous verification requirements, such as validating user emails in real-time during registration processes.\n\n## Rate Limits\nTo ensure fair usage and maintain the stability of our API for all users, we enforce separate rate limits on each endpoint. The rate limit for each endpoint is documented in its respective endpoint section. If you exceed this limit, your requests may be temporarily blocked until the rate limit resets. We recommend implementing proper error handling and retry logic in your application to manage this limit effectively.\n\n## Additional Resources\n- [JSON Documentation](https://api.emaillistverify.com/api-doc-json): Access a machine-readable JSON version of the EmailListVerify Customer API documentation, suitable for system integration or developers requiring a machine-readable format.\n","version":"","contact":{}},"tags":[],"servers":[{"url":"https://api.emaillistverify.com","description":"Production Server"}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"x-api-key","scheme":"api_key"}},"schemas":{"CreateEmailJobDto":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The email address that will be verified asynchronously","example":"john.smith@gmail.com"},"quality":{"type":"string","enum":["standard","high"],"default":"standard","example":"high","description":"Quality of the email verification. If not present, the default value is **standard**"}},"required":["email"]},"FindContactDto":{"type":"object","properties":{"firstName":{"type":"string","description":"First name of the contact","example":"Adela"},"lastName":{"type":"string","description":"Last name of the contact","example":"Franey"},"domain":{"type":"string","format":"hostname","description":"Email domain of the contact's company","example":"connelycorp.com"}},"required":["domain"]},"CheckBlacklistsDto":{"type":"object","properties":{"value":{"type":"string","description":"The IP address (IPv4/IPv6) or domain to check against blacklists","example":"172.75.233.15","maxLength":255}},"required":["value"]},"CreatePlacementTestViaOpenApiDto":{"type":"object","properties":{"name":{"type":"string","description":"Optional name for the placement test. If not provided, a default name will be generated.","example":"Q1 2025 Campaign Test","minLength":5},"webhookUrl":{"type":"string","description":"Optional webhook URL for asynchronous result delivery. Must be a valid HTTP or HTTPS URL. When provided, a POST request with test results will be sent to this URL upon test completion.","example":"https://yourapp.com/webhooks/placement-test"}}}}}}