{"id":25157841,"url":"https://github.com/verifalia/verifalia-java-sdk","last_synced_at":"2026-03-17T18:03:00.661Z","repository":{"id":50106429,"uuid":"46057698","full_name":"verifalia/verifalia-java-sdk","owner":"verifalia","description":"Verifalia REST API - Java SDK and helper library","archived":false,"fork":false,"pushed_at":"2021-06-04T02:36:03.000Z","size":259,"stargazers_count":8,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-02T04:49:30.271Z","etag":null,"topics":["email-validation","email-verification","java","verifalia"],"latest_commit_sha":null,"homepage":"https://verifalia.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verifalia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-12T14:20:38.000Z","updated_at":"2024-05-12T17:47:25.000Z","dependencies_parsed_at":"2022-09-26T19:01:04.421Z","dependency_job_id":null,"html_url":"https://github.com/verifalia/verifalia-java-sdk","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/verifalia/verifalia-java-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-java-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-java-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-java-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-java-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verifalia","download_url":"https://codeload.github.com/verifalia/verifalia-java-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verifalia%2Fverifalia-java-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30628405,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T17:32:55.572Z","status":"ssl_error","status_checked_at":"2026-03-17T17:32:38.732Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email-validation","email-verification","java","verifalia"],"created_at":"2025-02-09T01:41:07.267Z","updated_at":"2026-03-17T18:03:00.622Z","avatar_url":"https://github.com/verifalia.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Verifalia API](https://img.shields.io/badge/Verifalia%20API-v2.2-green)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.verifalia/verifalia-java-sdk/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.verifalia/verifalia-java-sdk)\n\nVerifalia RESTful API - Java SDK and helper library\n===================================================\n\n[Verifalia][0] provides a simple HTTPS-based API for validating email addresses in\nreal-time and checking whether they are deliverable or not; this SDK library integrates with Verifalia\nand allows to [verify email addresses][0] under Java 8 and above.\n\nLearn more about Verifalia at [https://verifalia.com][0]\n\n## Adding Verifalia REST API support to your Java project\n\nThe easiest way to add the Verifalia email verification SDK library to your Java project is to use\n[Maven](https://maven.apache.org/) and add the following dependency to your `pom.xml` file:\n\n```xml\n\u003cdependency\u003e\n      \u003cgroupId\u003ecom.github.verifalia\u003c/groupId\u003e\n      \u003cartifactId\u003everifalia-java-sdk\u003c/artifactId\u003e\n      \u003cversion\u003eLATEST\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n#### Manual download and compilation\n\nAs an alternative way to add the Verifalia SDK to your Java project, you can \nclone the SDK source project from GitHub, compile it and install it into your local Maven repository:\n\n```shell\n$ git clone git@github.com:verifalia/verifalia-java-sdk\n$ cd verifalia-java-sdk\n$ mvn install       # Requires maven, download from http://maven.apache.org/download.html\n```\nor, alternatively:\n\n```shell\n$ wget https://github.com/verifalia/verifalia-java-sdk/archive/master.zip\n$ unzip master.zip\n$ cd verifalia-java-sdk-master\n$ mvn install       # Requires maven, download from http://maven.apache.org/download.html\n```\n\nThis will also build the Javadoc in the `target/apidocs` folder: you can open the `index.html` located there to view it locally.\n\n### Authentication\n\nFirst things first: authentication to the Verifalia API is performed by way of either the credentials\n of your root Verifalia account or of one of its users (previously known as sub-accounts): if you don't\n  have a Verifalia account, just [register for a free one][4].\nFor security reasons, it is always advisable to [create and use a dedicated user][3] for accessing\n the API, as doing so will allow to assign only the specific needed permissions to it.\n\nLearn more about authenticating to the Verifalia API at [https://verifalia.com/developers#authentication][2]\n\nOnce you have your Verifalia credentials at hand, use them while creating a new instance of the\n `VerifaliaRestClient` class, which will be the starting point to every other operation against the\n  Verifalia API: the supplied credentials will be automatically provided to the API using the HTTP\n   Basic Auth method.\n\n```java\nimport com.verifalia.api.VerifaliaRestClient;\n\n// Create REST client object with your credentials\n\nVerifaliaRestClient verifalia = new VerifaliaRestClient(\"username\", \"password\");\n```\n\nIn addition to the HTTP Basic Auth method, this SDK also supports other different ways to authenticate\n to the Verifalia API, as explained in the subsequent paragraphs.\n\n#### Authenticating via bearer token\n\nBearer authentication offers higher security over HTTP Basic Auth, as the latter requires sending the\n actual credentials on each API call, while the former only requires it on a first, dedicated\n  authentication request. On the other side, the first authentication request needed by Bearer\n   authentication takes a non-negligible time: if you need to perform only a single request, using\n    HTTP Basic Auth provides the same degree of security and is the faster option too.\n\n```java\nVerifaliaRestClient verifalia =\n    new VerifaliaRestClient(new BearerAuthenticationProvider(\"username\", \"password\"));\n```\n\n#### Authenticating via X.509 client certificate (TLS mutual authentication)\n\nThis authentication method uses a TLS client certificate stored in the Java Keystore (JKS) to authenticate\n against the Verifalia API. This method, also\n called mutual TLS authentication (mTLS) or two-way authentication, offers the highest degree of security,\n  as only a cryptographically-derived key (and not the actual credentials) is sent over the wire on each\n   request.\n\nTo use this authentication method, one needs to generate an identity keystore file from both the verifalia.com\npublic key and the client certificate private key, and finally import and trust the resulting JKS file;\nTo better understand how this works, please see [this tutorial](https://www.snaplogic.com/glossary/two-way-ssl-java-example).\n\nOnce the Java Keystore is configured, you can use the below code to use your TLS client certificate to\nauthenticate against the Verifalia API:\n\n```java\nVerifaliaRestClient verifalia =\n    new VerifaliaRestClient(new ClientCertificateAuthenticationProvider(certAlias, certPassword, new File(identifyJksFilePath), new File(trustStoreJksFilePath)));\n```\nwhere `certAlias` is the alias used when creating the client certificate, `certPassword` is the password\n used when creating it, `identityJksFilePath` and `trustStoreJksFilePath` are the path of, respectively,\n  the identity and trust store JKS files.\n\n## Validating email addresses ##\n\nEvery operation related to verifying / validating email addresses is performed through the\n `emailValidations` property exposed by the `VerifaliaRestClient` instance you created above, whose\n  getter returns an object with many useful methods for verifying email addresses: in the next few\n   paragraphs we are looking at the most used ones, so it is strongly advisable to explore the library\n    and look at the Javadoc for other opportunities.\n    \n### How to validate an email address\n\nTo validate an email address from your Java project you can call the `submit()` method: it accepts\n one or more email addresses and any eventual verification options you wish to pass to Verifalia,\n  including the expected results quality, deduplication preferences and processing priority.\n\nIn the next example, we are showing how to verify a single email address using this library; as the\n entire process is asynchronous, we are passing a `WaitingStrategy` value, asking `submit()` to\n  automatically wait for the job completion:\n\n```java\nValidation validation = verifalia\n    .getEmailValidations()\n    .submit(\"batman@gmail.com\", new WaitingStrategy(true));\n\n// At this point the address has been validated: let's print\n// its email validation result to the console.\n\nValidationEntry entry = validation.getEntries().get(0);\n\nSystem.out.printf(\"%s =\u003e Classification: %s, Status: %s\\n\",\n    entry.getInputData(),\n    entry.getClassification(),\n    entry.getStatus());\n\n// Prints out something like:\n// batman@gmail.com =\u003e Classification: Deliverable, Status: Success\n```\n\n### How to validate a list of email addresses ###\n\nAs an alternative to method above, you can avoid automatically waiting and retrieve the email validation\n results at a later time; this is preferred in the event you are verifying a list of email addresses,\n  which could take minutes or even hours to complete.\n\nHere is how to do that:\n\n```java\nValidation validation = verifalia\n    .getEmailValidations()\n    .submit(new String[] {\n\t\t\"batman@gmail.com\",\n\t\t\"steve.vai@best.music\",\n\t\t\"samantha42@yahoo.de\"\n\t});\n\nSystem.out.println(\"Job Id: \" + validation.getOverview().getId());\nSystem.out.println(\"Status: \" + validation.getOverview().getStatus());\n\n// Prints out something like:\n// Job Id: 290b5146-eeac-4a2b-a9c1-61c7e715f2e9\n// Status: InProgress\n```\n\nOnce you have an email validation job Id, which is always returned by `submit()` as part of the\n validation's `overview` property, you can retrieve the job data using the `get()` method. Similarly\n  to the submission process, you can either wait for the completion of the job or just retrieve the\n   current job snapshot to get its progress, using an instance of the same `WaitingStrategy` class\n    mentioned above. Only completed jobs have their `entries` properties filled with the email validation\n     results, however.\n\nIn the following example, we are requesting the current snapshot of a given email validation job back\n from Verifalia:\n\n```java\nValidation validation = verifalia\n    .getEmailValidations()\n    .get(\"290b5146-eeac-4a2b-a9c1-61c7e715f2e9\");\n\nif (validation.getOverview().getStatus() == ValidationStatus.Completed) {\n\t// validation.getEntries() will have the validation results!\n}\nelse {\n\t// What about having a coffee?\n}\n```\n\nAnd here is how to request the same job, asking the SDK to automatically wait for us until the job\n is completed (that is, _joining_ the job):\n\n```java\nValidation validation = verifalia\n    .getEmailValidations()\n    .get(\"290b5146-eeac-4a2b-a9c1-61c7e715f2e9\", new WaitingStrategy(true));\n```\n\n### Don't forget to clean up, when you are done ###\n\nVerifalia automatically deletes completed jobs after 30 days since their completion: deleting completed\n jobs is a best practice, for privacy and security reasons. To do that, you can invoke the `delete()`\n  method passing the job Id you wish to get rid of:\n\n```java\nverifalia\n    .getEmailValidations()\n    .delete(validation.getOverview().getId());\n```\n\nOnce deleted, a job is gone and there is no way to retrieve its email validation(s).\n\n### How to import email addresses from a file ###\n\nIn addition to submitting structured data (see the paragraphs above), it also possible to import the email addresses to\nverify [from a file](https://verifalia.com/developers#email-validations-importing-file) provided by the user. Once submitted,\nthe email verification job follows the same flow as described above.\n\nVerifalia accepts the following file types:\n- plain text files (.txt), with one email address per line\n- comma-separated values (.csv), tab-separated values (.tsv) and other delimiter-separated values files\n- Microsoft Excel spreadsheets (.xls and .xlsx)\n\nHere is how to extract and verify email addresses, for example, from the third column of the first sheet of an Excel workbook,\nstarting from the second row:\n\n```java\nFileValidationRequest request = new FileValidationRequest(\"my-list.xlsx\",\n    WellKnownMimeTypes.EXCEL_XLSX);\n\n// request.setSheet(0); // 0 is the default value\nrequest.setColumn(2); // zero-based column number\nrequest.setStartingRow(1); // zero-based starting row number\n\nValidation validation = verifalia\n    .getEmailValidations()\n    .submit(request);\n```\n\n### Iterating over your email validation jobs ###\n\nFor management and reporting purposes, you may want to obtain a detailed list of your past email\n validation jobs. This SDK library allows to do that through the `list()` method, which allows\n  to iterate asynchronously over a collection of `ValidationOverview` instances (the same type\n   of the `overview` property of the results returned by `submit()` and `get()`).\n\nHere is how to iterate over your jobs, from the most recent to the oldest one:\n\n```java\nIterable\u003cValidationOverview\u003e jobs = verifalia\n    .getEmailValidations()\n    .list(ValidationOverviewListingOptions\n        .builder()\n        .direction(Direction.Backward)\n        .build());\n\nfor (ValidationOverview job : jobs) {\n\tSystem.out.printf(\"Id: %s, submitted: %s, status: %s, entries: %d\\n\",\n\t\tjobOverview.getId(),\n\t\tjobOverview.getSubmittedOn(),\n\t\tjobOverview.getStatus(),\n\t\tjobOverview.getNoOfEntries());\n}\n\n// Prints out something like:\n// Id: a7784f9a-86d4-436c-b8e4-f72f2bd377ac, submitted: 8/2/2019 10:27:29 AM, status: InProgress, entries: 9886\n// Id: 86d57c00-147a-4736-88cc-c918260c67c6, submitted: 8/2/2019 10:27:29 AM, status: Completed, entries: 1\n// Id: 594bbb0f-6f12-481c-926f-606cfefc1cd5, submitted: 8/2/2019 10:27:28 AM, status: Completed, entries: 1\n// Id: a5c1cd5b-39cc-43bc-9a3a-ee4a0f80ee6d, submitted: 8/2/2019 10:27:26 AM, status: InProgress, entries: 226\n// Id: b6f69e30-60dd-4c21-b2cb-e73ba75fb278, submitted: 8/2/2019 10:27:21 AM, status: Completed, entries: 12077\n// Id: 5e5a97dc-459f-4edf-a607-47371c32aa94, submitted: 8/2/2019 10:27:18 AM, status: Deleted, entries: 1009\n// ...\n```\n\n## Managing credits ##\n\nTo manage the Verifalia credits for your account you can use the `credits` property exposed by the\n `VerifaliaRestClient` instance created above. Like for the previous topic, in the next few paragraphs\n  we are looking at the most used operations, so it is strongly advisable to explore the library and\n   look at the embedded Javadoc for other opportunities.\n\n### Getting the credits balance ###\n\nOne of the most common tasks you may need to perform on your account is retrieving the available number\n of free daily credits and credit packs. To do that, you can use the `getBalance()` method, which\n  returns a `Balance` object, as shown in the next example:\n\n```java\nBalance balance = verifalia\n    .getCredits()\n    .getBalance();\n\nSystem.out.printf(\"Credit packs: %d, free daily credits: %d (will reset in %s)\\n\",\n\tbalance.getCreditPacks(),\n\tbalance.getFreeCredits(),\n\tbalance.getFreeCreditsResetIn());\n\n// Prints out something like:\n// Credit packs: 956.332, free daily credits: 128.66 (will reset in PT9H8M23S)\n```\n\n### Retrieving credits usage statistics ###\n\nAs a way to monitor and forecast the credits consumption for your account, the method `listDailyUsages()`\n allows to retrieve statistics about historical credits usage, returning an iterable collection\n  of `DailyUsage` instances. The method also allows to limit the period of interest by passing a\n   `DailyUsageListingOptions` instance. Elements are returned only for the dates where consumption\n    (either of free credits, credit packs or both) occurred.\n\nHere is how to retrieve the daily credits consumption for the last thirty days:\n\n```java\nDateBetweenPredicate lastThirtyDays = new DateBetweenPredicate();\nlastThirtyDays.setSince(LocalDate.now().minusDays(30));\n\nIterable\u003cDailyUsage\u003e dailyUsages = verifalia\n    .getCredits()\n    .listDailyUsages(DailyUsageListingOptions\n        .builder()\n        .dateFilter(lastThirtyDays)\n        .build());\n\nfor (DailyUsage dailyUsage : dailyUsages) {\n\tSystem.out.printf(\"%s - credit packs: %d, free daily credits: %d\",\n\t\tdailyUsage.Date,\n\t\tdailyUsage.CreditPacks,\n\t\tdailyUsage.FreeCredits);\n}\n\n// Prints out something like:\n// 2020-04-01 - credit packs: 1965.68, free daily credits: 200\n// 2020-03-26 - credit packs: 0, free daily credits: 185.628\n// 2020-03-25 - credit packs: 15.32, free daily credits: 200\n// ...\n```\n\n[0]: https://verifalia.com\n[2]: https://verifalia.com/developers#authentication\n[3]: https://verifalia.com/client-area#/users/new\n[4]: https://verifalia.com/sign-up\n[5]: https://verifalia.com/client-area#/credits/add","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverifalia%2Fverifalia-java-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverifalia%2Fverifalia-java-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverifalia%2Fverifalia-java-sdk/lists"}