@apifreaks/openapi-specs 0.1.0

package/specs/email-validation/bulk-email-validation.json

@@ -0,0 +1,534 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Bulk Email Validation API - Validate and Verify Emails in Bulk",
+    "version": "1.0.0",
+    "description": "Validate up to 100 email addresses in a single POST request. Each email is processed independently. Returns an array of validation results with deliverability assessment per email, plus per-item error objects for failed validations. Maximum 100 email addresses per request.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Bulk Email Validation API Server"
+    }
+  ],
+  "paths": {
+    "/email-validation/bulk": {
+      "post": {
+        "tags": ["Email Validation APIs"],
+        "summary": "Validate multiple email addresses",
+        "description": "Validates a bulk of email addresses and returns result for each. Maximum `100` email addresses per request.",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            },
+            "description": "Format of the response"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BulkEmailRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response. Each item corresponds to one requested email, in the same order as the request; invalid emails are reflected via validEmail/validSyntax on that item, not as a separate error object — every item has success=true regardless of validation outcome.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BulkEmailValidationResponse"
+                },
+                "examples": {
+                  "bulkEmailsValidated": {
+                    "summary": "Mix of a valid and a syntactically invalid email",
+                    "value": {
+                      "emailValidationResponses": [
+                        {
+                          "success": true,
+                          "email": "abc.def@gmail.com",
+                          "validEmail": "valid",
+                          "validSyntax": true,
+                          "domain": {
+                            "name": "gmail.com",
+                            "disposable": false,
+                            "spam": false,
+                            "free": true,
+                            "validDomain": true,
+                            "catchAll": false
+                          },
+                          "account": {
+                            "role": false,
+                            "fullMailBox": false
+                          },
+                          "dns": {
+                            "mxRecords": [
+                              "gmail-smtp-in.l.google.com.",
+                              "alt1.gmail-smtp-in.l.google.com.",
+                              "alt2.gmail-smtp-in.l.google.com.",
+                              "alt3.gmail-smtp-in.l.google.com.",
+                              "alt4.gmail-smtp-in.l.google.com."
+                            ]
+                          }
+                        },
+                        {
+                          "success": true,
+                          "email": "not-an-email",
+                          "validEmail": "INVALID_EMAIL",
+                          "validSyntax": false,
+                          "domain": {
+                            "name": "not-an-email",
+                            "validDomain": false
+                          }
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request – Invalid request body",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "invalidBody": {
+                    "summary": "emailData field missing or malformed",
+                    "value": {
+                      "timestamp": "2026-07-27T12:53:14.628Z",
+                      "path": "/v1.0/email-validation/bulk",
+                      "status": 400,
+                      "error": "Invalid request body Exception",
+                      "message": "Please provide data in required format in request body"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "408": {
+            "description": "Request Timeout",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Request Timeout": {
+                    "value": {
+                      "timestamp": "2026-06-06T13:00:00.000Z",
+                      "path": "/v1.0/email-validation/bulk",
+                      "status": 408,
+                      "error": "Request Timeout",
+                      "message": "Timed out while connecting to the remote URL."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate Limit Exceeded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "Rate Limit Exceeded": {
+                    "value": {
+                      "timestamp": "2026-06-06T13:00:00.000Z",
+                      "path": "/v1.0/email-validation/bulk",
+                      "status": 429,
+                      "error": "Too Many Requests",
+                      "message": "API rate limit exceeded."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "operationId": "bulkCheckEmail"
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "BulkEmailValidationResponse": {
+        "type": "object",
+        "description": "Wrapper containing the per-email results array.",
+        "required": ["emailValidationResponses"],
+        "properties": {
+          "emailValidationResponses": {
+            "type": "array",
+            "description": "Array of per-email results, one entry per requested email, in the same order as the request. Invalid emails are reflected via validEmail/validSyntax, not a separate error shape.",
+            "items": {
+              "$ref": "#/components/schemas/SingleEmailValidationResponse"
+            }
+          }
+        }
+      },
+      "SingleEmailValidationResponse": {
+        "type": "object",
+        "required": ["success", "email", "validEmail", "validSyntax", "domain"],
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "Indicates the processing status of the validation request. true: completed successfully."
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "The email address submitted for validation."
+          },
+          "name": {
+            "type": "string",
+            "description": "Optional identifier or label provided in the request for record tracking."
+          },
+          "reason": {
+            "type": "string",
+            "description": "Detailed explanation returned when validEmail is not valid."
+          },
+          "validEmail": {
+            "type": "string",
+            "enum": ["valid", "invalid", "INVALID_EMAIL", "unknown", "risky"],
+            "description": "Comprehensive deliverability assessment. Casing is inconsistent in the live API: syntactically invalid addresses return INVALID_EMAIL, while semantically invalid (undeliverable) addresses return lowercase invalid. unknown/risky are documented possibilities not observed during testing."
+          },
+          "validSyntax": {
+            "type": "boolean",
+            "description": "Validates email address format compliance with RFC 5322 standards."
+          },
+          "domain": {
+            "$ref": "#/components/schemas/DomainObject"
+          },
+          "account": {
+            "$ref": "#/components/schemas/AccountObject"
+          },
+          "dns": {
+            "$ref": "#/components/schemas/DnsObject"
+          },
+          "address": {
+            "$ref": "#/components/schemas/AddressObject"
+          },
+          "ip": {
+            "type": "string",
+            "format": "ip",
+            "description": "IP address provided for geolocation and security enrichment."
+          }
+        },
+        "description": "Email validation response containing deliverability assessment and metadata."
+      },
+      "DomainObject": {
+        "type": "object",
+        "required": ["name", "validDomain"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Extracted domain component from the email address."
+          },
+          "validDomain": {
+            "type": "boolean",
+            "description": "Domain validation status confirming DNS resolution capability."
+          },
+          "disposable": {
+            "type": "boolean",
+            "description": "Classification flag identifying domains from temporary email service providers."
+          },
+          "spam": {
+            "type": "boolean",
+            "description": "Reputation indicator flagging domains on spam databases."
+          },
+          "free": {
+            "type": "boolean",
+            "description": "Classification indicating free or consumer-grade email service providers."
+          },
+          "catchAll": {
+            "type": "boolean",
+            "description": "Detection flag for domains configured to accept mail for any recipient address."
+          }
+        },
+        "description": "Domain validation details for the email address."
+      },
+      "AccountObject": {
+        "type": "object",
+        "required": ["role"],
+        "properties": {
+          "role": {
+            "type": "boolean",
+            "description": "Detection flag identifying role-based email addresses (e.g., admin@, support@)."
+          },
+          "fullMailBox": {
+            "type": "boolean",
+            "description": "Storage capacity status indicator for the recipient mailbox."
+          }
+        },
+        "description": "Account-level validation details."
+      },
+      "DnsObject": {
+        "type": "object",
+        "required": ["mxRecords"],
+        "properties": {
+          "mxRecords": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Collection of MX (Mail Exchange) hostname records from DNS queries."
+          },
+          "aRecords": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Collection of A (Address) records for the domain. Not observed in testing — may be rarely or never populated."
+          }
+        },
+        "description": "DNS records for the email domain."
+      },
+      "AddressObject": {
+        "type": "object",
+        "properties": {
+          "validIpAddress": {
+            "type": "boolean",
+            "description": "IP recognized/reachable by the geolocation provider."
+          },
+          "location": {
+            "$ref": "#/components/schemas/EmailLocation"
+          },
+          "security": {
+            "$ref": "#/components/schemas/EmailSecurity"
+          }
+        },
+        "description": "Geolocation and security enrichment data for the IP address.",
+        "required": []
+      },
+      "EmailLocation": {
+        "type": "object",
+        "description": "Geolocation data derived from the IP address.",
+        "properties": {
+          "city": {
+            "type": "string",
+            "description": "Municipal or city name."
+          },
+          "district": {
+            "type": "string",
+            "description": "District or neighborhood."
+          },
+          "zipcode": {
+            "type": "string",
+            "description": "Postal or ZIP code."
+          },
+          "state_prov": {
+            "type": "string",
+            "description": "State or province."
+          },
+          "country_name": {
+            "type": "string",
+            "description": "Common country name."
+          },
+          "country_name_official": {
+            "type": "string",
+            "description": "Official country name."
+          },
+          "country_code2": {
+            "type": "string",
+            "description": "Two-character ISO country code."
+          },
+          "country_code3": {
+            "type": "string",
+            "description": "Three-character ISO country code."
+          },
+          "continent_name": {
+            "type": "string",
+            "description": "Continental region name."
+          },
+          "continent_code": {
+            "type": "string",
+            "description": "Continental region identifier."
+          },
+          "accuracy_radius": {
+            "type": "string",
+            "description": "Geolocation precision radius."
+          },
+          "confidence": {
+            "type": "string",
+            "description": "Confidence score for geolocation accuracy."
+          },
+          "is_eu": {
+            "type": "boolean",
+            "description": "European Union membership status."
+          }
+        },
+        "required": []
+      },
+      "EmailSecurity": {
+        "type": "object",
+        "description": "Threat and anonymity profile for the IP address.",
+        "required": [
+          "threat_score",
+          "is_tor",
+          "is_proxy",
+          "proxy_type",
+          "proxy_provider",
+          "is_anonymous",
+          "is_known_attacker",
+          "is_spam",
+          "is_bot",
+          "is_cloud_provider",
+          "cloud_provider"
+        ],
+        "properties": {
+          "threat_score": {
+            "type": "integer",
+            "description": "Quantitative risk assessment score. Higher values indicate elevated security risk."
+          },
+          "is_tor": {
+            "type": "boolean",
+            "description": "Detection flag for IP addresses routed through the Tor anonymity network."
+          },
+          "is_proxy": {
+            "type": "boolean",
+            "description": "Detection flag identifying IP addresses operating as proxy servers."
+          },
+          "proxy_type": {
+            "type": "string",
+            "description": "Classification of detected proxy infrastructure type (e.g. VPN, HTTP, SOCKS)."
+          },
+          "proxy_provider": {
+            "type": "string",
+            "description": "Identified service provider operating the proxy infrastructure."
+          },
+          "is_anonymous": {
+            "type": "boolean",
+            "description": "Anonymization detection flag for IP addresses using identity obfuscation techniques."
+          },
+          "is_known_attacker": {
+            "type": "boolean",
+            "description": "Threat intelligence flag for IP addresses documented as confirmed malicious sources."
+          },
+          "is_spam": {
+            "type": "boolean",
+            "description": "Reputation flag for IP addresses associated with spam transmission."
+          },
+          "is_bot": {
+            "type": "boolean",
+            "description": "Automated traffic detection flag for IP addresses from bot networks."
+          },
+          "is_cloud_provider": {
+            "type": "boolean",
+            "description": "Infrastructure classification flag for IP addresses from cloud computing providers."
+          },
+          "cloud_provider": {
+            "type": "string",
+            "description": "Identified cloud infrastructure or hosting service provider name."
+          }
+        }
+      },
+      "BulkEmailRequest": {
+        "type": "object",
+        "description": "Request body for bulk email validation.",
+        "required": ["emailData"],
+        "properties": {
+          "emailData": {
+            "type": "array",
+            "description": "Array of email objects to validate. Maximum 100 per request.",
+            "maxItems": 100,
+            "items": {
+              "$ref": "#/components/schemas/BulkEmailRequestItem"
+            }
+          }
+        }
+      },
+      "BulkEmailRequestItem": {
+        "type": "object",
+        "description": "A single email entry in a bulk validation request.",
+        "required": ["email"],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Email address to validate."
+          },
+          "name": {
+            "type": "string",
+            "description": "Optional name or label."
+          },
+          "ip": {
+            "type": "string",
+            "format": "ip",
+            "description": "Optional IP address for enrichment."
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}