Official Java SDK for the XposedOrNot API
Check if your email has been exposed in data breaches
Note: This SDK uses the free public API from XposedOrNot.com - a free service to check if your email has been compromised in data breaches. Visit the XposedOrNot website to learn more about the service and check your email manually.
- Features
- Installation
- Requirements
- Quick Start
- API Reference
- Error Handling
- Rate Limits
- Configuration
- Contributing
- License
- Links
- Simple API - Fluent builder pattern and endpoint-based method grouping
- Comprehensive Coverage - Email breach checks, breach listings, analytics, and password exposure
- Plus API Support - Optional API key for detailed breach information
- Error Handling - Typed exception classes for every error scenario
- Configurable - Timeout, retries, custom headers, and base URL overrides
- Secure - HTTPS enforced, input validation, k-anonymity for password checks
- Lightweight - Built on Java's built-in
HttpClientwith minimal dependencies
dependencies {
implementation("com.xposedornot:xposedornot:1.0.0")
}<dependency>
<groupId>com.xposedornot</groupId>
<artifactId>xposedornot</artifactId>
<version>1.0.0</version>
</dependency>- Java 11 or higher
import com.xposedornot.XposedOrNot;
import com.xposedornot.models.EmailBreachResponse;
try (XposedOrNot xon = XposedOrNot.builder().build()) {
// Check if an email has been breached
EmailBreachResponse result = xon.email().check("[email protected]");
if (result.isFound()) {
System.out.println("Email found in " + result.getBreaches().size() + " breaches:");
result.getBreaches().forEach(b -> System.out.println(" - " + b));
} else {
System.out.println("Good news! Email not found in any known breaches.");
}
}XposedOrNot xon = XposedOrNot.builder()
.timeout(Duration.ofSeconds(15))
.maxRetries(2)
.build();See Configuration for all builder options.
Check if an email address has been exposed in any data breaches using the free API.
EmailBreachResponse result = xon.email().check("[email protected]");
// result.isFound() -> boolean
// result.getBreaches() -> List<String>Check an email using the Plus API with detailed breach information. Requires an API key.
XposedOrNot xon = XposedOrNot.builder()
.apiKey("your-api-key")
.build();
EmailBreachDetailedResponse result = xon.email().checkDetailed("[email protected]");Get a list of all known data breaches.
List<BreachInfo> breaches = xon.breaches().list();Filter breaches by domain.
List<BreachInfo> adobeBreaches = xon.breaches().listByDomain("adobe.com");BreachInfo properties: breachID, breachedDate, domain, industry, exposedData, exposedRecords, verified, and more.
Get detailed breach analytics for an email address, including breach metrics and summaries.
BreachAnalyticsResponse analytics = xon.email().getAnalytics("[email protected]");
if (analytics.isFound()) {
System.out.println("Exposed breaches: " + analytics.getExposedBreaches());
System.out.println("Breach metrics: " + analytics.getBreachMetrics());
}Check if a password has been exposed in any known data breach. Uses k-anonymity: the password is hashed locally with Keccak-512 and only the first 10 hex characters are sent to the API.
PasswordCheckResponse result = xon.password().check("password123");The library provides typed exception classes for different failure scenarios:
import com.xposedornot.XposedOrNot;
import com.xposedornot.exceptions.*;
try (XposedOrNot xon = XposedOrNot.builder().build()) {
var result = xon.email().check("invalid-email");
} catch (ValidationException e) {
System.err.println("Invalid input: " + e.getMessage());
} catch (RateLimitException e) {
System.err.println("Rate limited: " + e.getMessage());
} catch (NetworkException e) {
System.err.println("Network error: " + e.getMessage());
} catch (AuthenticationException e) {
System.err.println("Authentication failed: " + e.getMessage());
} catch (XposedOrNotException e) {
System.err.println("API error: " + e.getMessage() + " (code: " + e.getStatusCode() + ")");
}| Exception Class | Description |
|---|---|
XposedOrNotException |
Base exception class for all errors |
ValidationException |
Invalid input (e.g., malformed email, empty password) |
RateLimitException |
API rate limit exceeded (HTTP 429) |
NotFoundException |
Resource not found (HTTP 404) |
AuthenticationException |
Authentication failed (invalid or missing API key) |
NetworkException |
Network connectivity issues |
ApiException |
General API or response parsing error |
The XposedOrNot API has the following rate limits:
- 2 requests per second
- 50-100 requests per hour
- 100-1000 requests per day
The client includes automatic retry with exponential backoff for 429 responses.
Use the builder pattern to configure the client:
XposedOrNot xon = XposedOrNot.builder()
.apiKey("your-api-key") // API key for Plus API access
.timeout(Duration.ofSeconds(15)) // HTTP request timeout
.maxRetries(5) // Retry count on 429 responses
.baseUrl("https://...") // Override free API base URL
.plusBaseUrl("https://...") // Override Plus API base URL
.passwordBaseUrl("https://...") // Override password API base URL
.header("X-Custom", "value") // Add custom header to all requests
.build();| Option | Type | Default | Description |
|---|---|---|---|
apiKey |
String |
null |
API key for Plus API access |
timeout |
Duration |
30s |
HTTP request timeout |
maxRetries |
int |
3 |
Max retries on 429 responses |
baseUrl |
String |
https://api.xposedornot.com |
Free API base URL |
plusBaseUrl |
String |
https://plus-api.xposedornot.com |
Plus API base URL |
passwordBaseUrl |
String |
https://passwords.xposedornot.com/api |
Password API base URL |
header |
String, String |
none | Custom headers for all requests |
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
# Clone the repository
git clone https://github.com/XposedOrNot/XposedOrNot-Java.git
cd XposedOrNot-Java
# Build
./gradlew build
# Run tests
./gradlew testMIT - see the LICENSE file for details.
Made with care by XposedOrNot