@apifreaks/openapi-specs 0.3.2 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +3486 -128
- package/dist/index.d.cts +3 -3
- package/dist/index.d.ts +3 -3
- package/dist/index.js +3486 -127
- package/dist/specs/domain/domain-reputation.yaml +898 -0
- package/dist/specs/domain/domain-typosquatting.yaml +253 -0
- package/dist/specs/email-validation/bulk-email-validation.yaml +64 -10
- package/dist/specs/email-validation/email-checker.yaml +74 -11
- package/package.json +1 -1
- package/specs/domain/domain-reputation.json +1115 -0
- package/specs/domain/domain-typosquatting.json +344 -0
- package/specs/email-validation/bulk-email-validation.json +78 -9
- package/specs/email-validation/email-checker.json +88 -11
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
{
|
|
2
|
+
"openapi": "3.1.1",
|
|
3
|
+
"info": {
|
|
4
|
+
"title": "Domain Typosquatting API - Find Typo and Look-Alike Domains for Brand Protection and Phishing Discovery",
|
|
5
|
+
"version": "1.0.0",
|
|
6
|
+
"description": "Search for registered domains that read like typo variants of a brand keyword, or that match a wildcard pattern, across the full TLD set. Each match returns what is available of its registration date, expiry date, last-seen date, and drop status, paginated at 100 domains per page. Built for brand and trademark protection, phishing discovery, scheduled monitoring, and domain reclaim.",
|
|
7
|
+
"contact": {
|
|
8
|
+
"name": "APIFreaks Support",
|
|
9
|
+
"url": "https://apifreaks.com/contact",
|
|
10
|
+
"email": "support@apifreaks.com"
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"servers": [
|
|
14
|
+
{
|
|
15
|
+
"url": "https://api.apifreaks.com/v1.0",
|
|
16
|
+
"description": "Domain Typosquatting API Server"
|
|
17
|
+
}
|
|
18
|
+
],
|
|
19
|
+
"paths": {
|
|
20
|
+
"/domain/typosquatting": {
|
|
21
|
+
"get": {
|
|
22
|
+
"tags": ["Domain APIs"],
|
|
23
|
+
"summary": "Find registered typo-variant or wildcard-pattern domains for a brand keyword.",
|
|
24
|
+
"description": "The Domain Typosquatting API searches for registered domains that are typo or look-alike variants of a brand keyword, or that match a wildcard pattern. Results include registration lifecycle data and drop status across 1529+ TLDs, paginated at 100 domains per page.",
|
|
25
|
+
"parameters": [
|
|
26
|
+
{
|
|
27
|
+
"name": "format",
|
|
28
|
+
"in": "query",
|
|
29
|
+
"required": false,
|
|
30
|
+
"schema": {
|
|
31
|
+
"type": "string",
|
|
32
|
+
"enum": ["json", "xml"],
|
|
33
|
+
"default": "json"
|
|
34
|
+
},
|
|
35
|
+
"description": "Format of the response."
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"name": "keyword",
|
|
39
|
+
"in": "query",
|
|
40
|
+
"required": false,
|
|
41
|
+
"schema": {
|
|
42
|
+
"type": "string",
|
|
43
|
+
"minLength": 3,
|
|
44
|
+
"maxLength": 63
|
|
45
|
+
},
|
|
46
|
+
"description": "Brand or label to find typo variants for. 3-63 characters, letters, digits, or hyphens, a single label with no dots. Case-insensitive. Use either keyword or pattern, never both."
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
"name": "pattern",
|
|
50
|
+
"in": "query",
|
|
51
|
+
"required": false,
|
|
52
|
+
"schema": {
|
|
53
|
+
"type": "string",
|
|
54
|
+
"minLength": 3,
|
|
55
|
+
"maxLength": 63
|
|
56
|
+
},
|
|
57
|
+
"description": "Wildcard search string that combines fuzzy matching with * wildcards. 3-63 characters total, * is the only supported wildcard and each one matches zero or more characters, maximum 3 asterisks per request. Use either keyword or pattern, never both."
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
"name": "pageToken",
|
|
61
|
+
"in": "query",
|
|
62
|
+
"required": false,
|
|
63
|
+
"schema": {
|
|
64
|
+
"type": "string"
|
|
65
|
+
},
|
|
66
|
+
"description": "Token from nextPageToken in the previous response. Required to retrieve page 2 and onward. The original keyword or pattern must be passed alongside the token on every page request. Results page at 100 domains per page."
|
|
67
|
+
}
|
|
68
|
+
],
|
|
69
|
+
"responses": {
|
|
70
|
+
"200": {
|
|
71
|
+
"description": "Success",
|
|
72
|
+
"content": {
|
|
73
|
+
"application/json": {
|
|
74
|
+
"schema": {
|
|
75
|
+
"$ref": "#/components/schemas/DomainTyposquattingResponse"
|
|
76
|
+
},
|
|
77
|
+
"examples": {
|
|
78
|
+
"keywordSuccess": {
|
|
79
|
+
"summary": "Keyword search (paypal)",
|
|
80
|
+
"value": {
|
|
81
|
+
"status": true,
|
|
82
|
+
"totalRecords": 1284,
|
|
83
|
+
"currentPage": 1,
|
|
84
|
+
"hasNextPage": true,
|
|
85
|
+
"totalPages": 13,
|
|
86
|
+
"nextPageToken": "<opaque_token>",
|
|
87
|
+
"domains": [
|
|
88
|
+
{
|
|
89
|
+
"domainName": "p-aypal.com",
|
|
90
|
+
"createDate": "2025-04-17",
|
|
91
|
+
"expiryDate": "2026-04-17",
|
|
92
|
+
"lastSeen": "2026-05-29",
|
|
93
|
+
"isDropped": true
|
|
94
|
+
},
|
|
95
|
+
{
|
|
96
|
+
"domainName": "p-aypal.de",
|
|
97
|
+
"lastSeen": "2024-07-11",
|
|
98
|
+
"isDropped": true
|
|
99
|
+
},
|
|
100
|
+
{
|
|
101
|
+
"domainName": "p0aypal.com",
|
|
102
|
+
"createDate": "2017-12-29",
|
|
103
|
+
"expiryDate": "2026-12-29",
|
|
104
|
+
"lastSeen": "2026-08-18",
|
|
105
|
+
"isDropped": false
|
|
106
|
+
},
|
|
107
|
+
{
|
|
108
|
+
"domainName": "p7ypal.com",
|
|
109
|
+
"isDropped": true
|
|
110
|
+
},
|
|
111
|
+
{
|
|
112
|
+
"domainName": "pa-pal.club",
|
|
113
|
+
"createDate": "2019-10-25",
|
|
114
|
+
"expiryDate": "2020-10-25",
|
|
115
|
+
"isDropped": false
|
|
116
|
+
}
|
|
117
|
+
]
|
|
118
|
+
}
|
|
119
|
+
},
|
|
120
|
+
"patternSuccess": {
|
|
121
|
+
"summary": "Wildcard pattern search (*paypal*)",
|
|
122
|
+
"value": {
|
|
123
|
+
"status": true,
|
|
124
|
+
"totalRecords": 5471,
|
|
125
|
+
"currentPage": 1,
|
|
126
|
+
"hasNextPage": true,
|
|
127
|
+
"totalPages": 55,
|
|
128
|
+
"nextPageToken": "<opaque_token>",
|
|
129
|
+
"domains": [
|
|
130
|
+
{
|
|
131
|
+
"domainName": "paypal-support.com",
|
|
132
|
+
"createDate": "2024-11-02",
|
|
133
|
+
"expiryDate": "2026-11-02",
|
|
134
|
+
"lastSeen": "2026-08-30",
|
|
135
|
+
"isDropped": false
|
|
136
|
+
},
|
|
137
|
+
{
|
|
138
|
+
"domainName": "login-paypal.net",
|
|
139
|
+
"lastSeen": "2025-12-14",
|
|
140
|
+
"isDropped": true
|
|
141
|
+
}
|
|
142
|
+
]
|
|
143
|
+
}
|
|
144
|
+
},
|
|
145
|
+
"emptyResult": {
|
|
146
|
+
"summary": "No matches found",
|
|
147
|
+
"value": {
|
|
148
|
+
"status": true,
|
|
149
|
+
"totalRecords": 0,
|
|
150
|
+
"currentPage": 1,
|
|
151
|
+
"hasNextPage": false,
|
|
152
|
+
"totalPages": 0,
|
|
153
|
+
"domains": []
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
},
|
|
159
|
+
"headers": {
|
|
160
|
+
"X-AF-Credits-Cost": {
|
|
161
|
+
"$ref": "#/components/headers/X-AF-Credits-Cost"
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
},
|
|
165
|
+
"400": {
|
|
166
|
+
"description": "Bad Request – Invalid parameters",
|
|
167
|
+
"content": {
|
|
168
|
+
"application/json": {
|
|
169
|
+
"schema": {
|
|
170
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
171
|
+
},
|
|
172
|
+
"examples": {
|
|
173
|
+
"shortPattern": {
|
|
174
|
+
"summary": "Pattern has too few non-wildcard characters",
|
|
175
|
+
"value": {
|
|
176
|
+
"error": "Invalid Pattern Exception",
|
|
177
|
+
"message": "The pattern must contain at least 5 non-wildcard characters and no more than 3 wildcards.",
|
|
178
|
+
"path": "/v1.0/domain/typosquatting",
|
|
179
|
+
"status": 400,
|
|
180
|
+
"timestamp": "2026-09-08T12:00:00.000Z"
|
|
181
|
+
}
|
|
182
|
+
},
|
|
183
|
+
"bothParams": {
|
|
184
|
+
"summary": "Both keyword and pattern supplied",
|
|
185
|
+
"value": {
|
|
186
|
+
"error": "Invalid Param Exception",
|
|
187
|
+
"message": "Use either the \"keyword\" or the \"pattern\" parameter, never both.",
|
|
188
|
+
"path": "/v1.0/domain/typosquatting",
|
|
189
|
+
"status": 400,
|
|
190
|
+
"timestamp": "2026-09-08T12:00:00.000Z"
|
|
191
|
+
}
|
|
192
|
+
},
|
|
193
|
+
"missingParam": {
|
|
194
|
+
"summary": "Neither keyword nor pattern supplied",
|
|
195
|
+
"value": {
|
|
196
|
+
"error": "Invalid Param Exception",
|
|
197
|
+
"message": "Please provide either a \"keyword\" or a \"pattern\" parameter.",
|
|
198
|
+
"path": "/v1.0/domain/typosquatting",
|
|
199
|
+
"status": 400,
|
|
200
|
+
"timestamp": "2026-09-08T12:00:00.000Z"
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
},
|
|
206
|
+
"headers": {
|
|
207
|
+
"X-AF-Credits-Cost": {
|
|
208
|
+
"$ref": "#/components/headers/X-AF-Credits-Cost"
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
},
|
|
213
|
+
"operationId": "getDomainTyposquatting"
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
},
|
|
217
|
+
"components": {
|
|
218
|
+
"securitySchemes": {
|
|
219
|
+
"ApiKeyAuthHeader": {
|
|
220
|
+
"type": "apiKey",
|
|
221
|
+
"in": "header",
|
|
222
|
+
"name": "X-apiKey",
|
|
223
|
+
"description": "Pass your API key via the X-apiKey request header."
|
|
224
|
+
},
|
|
225
|
+
"ApiKeyAuthQuery": {
|
|
226
|
+
"type": "apiKey",
|
|
227
|
+
"in": "query",
|
|
228
|
+
"name": "apiKey",
|
|
229
|
+
"description": "Pass your API key via the apiKey query parameter."
|
|
230
|
+
}
|
|
231
|
+
},
|
|
232
|
+
"schemas": {
|
|
233
|
+
"DomainTyposquattingResponse": {
|
|
234
|
+
"type": "object",
|
|
235
|
+
"required": ["status", "totalRecords", "currentPage", "hasNextPage", "totalPages", "domains"],
|
|
236
|
+
"properties": {
|
|
237
|
+
"status": {
|
|
238
|
+
"type": "boolean",
|
|
239
|
+
"description": "Indicates if the request was successful."
|
|
240
|
+
},
|
|
241
|
+
"totalRecords": {
|
|
242
|
+
"type": "integer",
|
|
243
|
+
"description": "Total number of domains found."
|
|
244
|
+
},
|
|
245
|
+
"currentPage": {
|
|
246
|
+
"type": "integer",
|
|
247
|
+
"description": "Page number of the current response. Starts at 1."
|
|
248
|
+
},
|
|
249
|
+
"hasNextPage": {
|
|
250
|
+
"type": "boolean",
|
|
251
|
+
"description": "true if at least one additional page is available."
|
|
252
|
+
},
|
|
253
|
+
"totalPages": {
|
|
254
|
+
"type": "integer",
|
|
255
|
+
"description": "Total number of pages available."
|
|
256
|
+
},
|
|
257
|
+
"nextPageToken": {
|
|
258
|
+
"type": "string",
|
|
259
|
+
"description": "Opaque token to pass as pageToken on the next request. Present only when hasNextPage is true."
|
|
260
|
+
},
|
|
261
|
+
"domains": {
|
|
262
|
+
"type": "array",
|
|
263
|
+
"items": {
|
|
264
|
+
"$ref": "#/components/schemas/DomainItem"
|
|
265
|
+
},
|
|
266
|
+
"description": "List of typo-variant or pattern-matched domains on the current page."
|
|
267
|
+
}
|
|
268
|
+
},
|
|
269
|
+
"description": "Paginated response containing typo-variant or pattern-matched domains."
|
|
270
|
+
},
|
|
271
|
+
"DomainItem": {
|
|
272
|
+
"type": "object",
|
|
273
|
+
"required": ["domainName", "isDropped"],
|
|
274
|
+
"properties": {
|
|
275
|
+
"domainName": {
|
|
276
|
+
"type": "string",
|
|
277
|
+
"description": "Domain name."
|
|
278
|
+
},
|
|
279
|
+
"createDate": {
|
|
280
|
+
"type": "string",
|
|
281
|
+
"description": "Domain creation date (YYYY-MM-DD). May be absent for older or less-actively-tracked entries."
|
|
282
|
+
},
|
|
283
|
+
"expiryDate": {
|
|
284
|
+
"type": "string",
|
|
285
|
+
"description": "Domain expiration date (YYYY-MM-DD). May be absent for older or less-actively-tracked entries."
|
|
286
|
+
},
|
|
287
|
+
"lastSeen": {
|
|
288
|
+
"type": "string",
|
|
289
|
+
"description": "Last time the domain was observed (YYYY-MM-DD). One of the two fields reliably meaningful across a full result set."
|
|
290
|
+
},
|
|
291
|
+
"isDropped": {
|
|
292
|
+
"type": "boolean",
|
|
293
|
+
"description": "Indicates whether the domain has dropped out of the registry and become available to register again."
|
|
294
|
+
}
|
|
295
|
+
},
|
|
296
|
+
"description": "A single typo-variant or pattern-matched domain with registration lifecycle data."
|
|
297
|
+
},
|
|
298
|
+
"ErrorResponse": {
|
|
299
|
+
"type": "object",
|
|
300
|
+
"description": "Standard error envelope returned by the API on failed requests.",
|
|
301
|
+
"required": ["message"],
|
|
302
|
+
"properties": {
|
|
303
|
+
"error": {
|
|
304
|
+
"type": "string",
|
|
305
|
+
"description": "Short error category or exception type."
|
|
306
|
+
},
|
|
307
|
+
"message": {
|
|
308
|
+
"type": "string",
|
|
309
|
+
"description": "Human-readable error message describing the failure."
|
|
310
|
+
},
|
|
311
|
+
"path": {
|
|
312
|
+
"type": "string",
|
|
313
|
+
"description": "API endpoint path that produced the error."
|
|
314
|
+
},
|
|
315
|
+
"status": {
|
|
316
|
+
"type": "integer",
|
|
317
|
+
"description": "HTTP status code returned with the error."
|
|
318
|
+
},
|
|
319
|
+
"timestamp": {
|
|
320
|
+
"type": "string",
|
|
321
|
+
"format": "date-time",
|
|
322
|
+
"description": "Timestamp when the error occurred (ISO 8601)."
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
},
|
|
327
|
+
"headers": {
|
|
328
|
+
"X-AF-Credits-Cost": {
|
|
329
|
+
"description": "Specifies the number of credits consumed by the current request.",
|
|
330
|
+
"schema": {
|
|
331
|
+
"type": "integer"
|
|
332
|
+
}
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
},
|
|
336
|
+
"security": [
|
|
337
|
+
{
|
|
338
|
+
"ApiKeyAuthHeader": []
|
|
339
|
+
},
|
|
340
|
+
{
|
|
341
|
+
"ApiKeyAuthQuery": []
|
|
342
|
+
}
|
|
343
|
+
]
|
|
344
|
+
}
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"info": {
|
|
4
4
|
"title": "Bulk Email Validation API - Validate and Verify Emails in Bulk",
|
|
5
5
|
"version": "1.0.0",
|
|
6
|
-
"description": "Validate up to 10 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 10 email addresses per request.",
|
|
6
|
+
"description": "Validate up to 10 email addresses in a single POST request. Each email is processed independently. Returns an array of validation results with deliverability assessment per email (valid/accept_all/invalid/unknown/risky/app_server_blocked), plus per-item error objects for failed validations. Maximum 10 email addresses per request.",
|
|
7
7
|
"contact": {
|
|
8
8
|
"name": "APIFreaks Support",
|
|
9
9
|
"url": "https://apifreaks.com/contact",
|
|
@@ -55,7 +55,7 @@
|
|
|
55
55
|
},
|
|
56
56
|
"examples": {
|
|
57
57
|
"bulkEmailsValidated": {
|
|
58
|
-
"summary": "Mix of
|
|
58
|
+
"summary": "Mix of valid, syntactically invalid, accept_all, null-MX invalid, and unknown (no-MX probe) results",
|
|
59
59
|
"value": {
|
|
60
60
|
"emailResponse": [
|
|
61
61
|
{
|
|
@@ -94,6 +94,74 @@
|
|
|
94
94
|
"name": "not-an-email",
|
|
95
95
|
"validDomain": false
|
|
96
96
|
}
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
"success": true,
|
|
100
|
+
"email": "random12345@yahoo.com",
|
|
101
|
+
"validEmail": "accept_all",
|
|
102
|
+
"validSyntax": true,
|
|
103
|
+
"reason": "domain accepts all addresses.",
|
|
104
|
+
"domain": {
|
|
105
|
+
"name": "yahoo.com",
|
|
106
|
+
"disposable": false,
|
|
107
|
+
"spam": false,
|
|
108
|
+
"free": true,
|
|
109
|
+
"validDomain": true,
|
|
110
|
+
"catchAll": true
|
|
111
|
+
},
|
|
112
|
+
"account": {
|
|
113
|
+
"role": false,
|
|
114
|
+
"fullMailBox": false
|
|
115
|
+
},
|
|
116
|
+
"dns": {
|
|
117
|
+
"mxRecord": [
|
|
118
|
+
"mta5.am0.yahoodns.net.",
|
|
119
|
+
"mta6.am0.yahoodns.net.",
|
|
120
|
+
"mta7.am0.yahoodns.net."
|
|
121
|
+
]
|
|
122
|
+
}
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
"success": true,
|
|
126
|
+
"email": "test@example.com",
|
|
127
|
+
"validEmail": "invalid",
|
|
128
|
+
"validSyntax": true,
|
|
129
|
+
"reason": "domain does not accept mail.",
|
|
130
|
+
"domain": {
|
|
131
|
+
"name": "example.com",
|
|
132
|
+
"disposable": true,
|
|
133
|
+
"spam": false,
|
|
134
|
+
"free": false,
|
|
135
|
+
"validDomain": true,
|
|
136
|
+
"catchAll": false
|
|
137
|
+
},
|
|
138
|
+
"account": {
|
|
139
|
+
"role": false
|
|
140
|
+
},
|
|
141
|
+
"dns": {
|
|
142
|
+
"mxRecord": ["."]
|
|
143
|
+
}
|
|
144
|
+
},
|
|
145
|
+
{
|
|
146
|
+
"success": true,
|
|
147
|
+
"email": "test@neverssl.com",
|
|
148
|
+
"validEmail": "unknown",
|
|
149
|
+
"validSyntax": true,
|
|
150
|
+
"reason": "We are unable to determine if email is valid or invalid.",
|
|
151
|
+
"domain": {
|
|
152
|
+
"name": "neverssl.com",
|
|
153
|
+
"disposable": false,
|
|
154
|
+
"spam": false,
|
|
155
|
+
"free": false,
|
|
156
|
+
"validDomain": true,
|
|
157
|
+
"catchAll": false
|
|
158
|
+
},
|
|
159
|
+
"account": {
|
|
160
|
+
"role": false
|
|
161
|
+
},
|
|
162
|
+
"dns": {
|
|
163
|
+
"aRecord": ["34.223.124.45"]
|
|
164
|
+
}
|
|
97
165
|
}
|
|
98
166
|
]
|
|
99
167
|
}
|
|
@@ -298,19 +366,20 @@
|
|
|
298
366
|
},
|
|
299
367
|
"reason": {
|
|
300
368
|
"type": "string",
|
|
301
|
-
"description": "Detailed explanation returned when validEmail is not valid."
|
|
369
|
+
"description": "Detailed explanation returned when validEmail is not valid. Omitted entirely when validEmail is valid."
|
|
302
370
|
},
|
|
303
371
|
"validEmail": {
|
|
304
372
|
"type": "string",
|
|
305
373
|
"enum": [
|
|
306
374
|
"valid",
|
|
375
|
+
"accept_all",
|
|
307
376
|
"invalid",
|
|
308
377
|
"INVALID_EMAIL",
|
|
309
378
|
"unknown",
|
|
310
379
|
"risky",
|
|
311
380
|
"app_server_blocked"
|
|
312
381
|
],
|
|
313
|
-
"description": "Comprehensive deliverability assessment.
|
|
382
|
+
"description": "Comprehensive deliverability assessment. valid: recipient confirmed deliverable, reason omitted. accept_all: the domain is catch-all and accepted the recipient, so this specific mailbox is unconfirmed — see domain.catchAll, reason 'domain accepts all addresses.'. invalid: rejected mailbox, syntax failure, or the domain accepts no mail at all (a null MX). unknown: no conclusive answer, most common for domains with no MX record that only get a probe against their address record. risky: mailbox exists but over quota, or the server deferred with a greylist response. app_server_blocked: our verifier IP was blocked by the receiving server. Casing is inconsistent in the live API: syntactically invalid addresses can return the raw enum name INVALID_EMAIL instead of lowercase invalid — this is a known API bug, handle it defensively as equivalent to invalid."
|
|
314
383
|
},
|
|
315
384
|
"validSyntax": {
|
|
316
385
|
"type": "boolean",
|
|
@@ -362,7 +431,7 @@
|
|
|
362
431
|
},
|
|
363
432
|
"catchAll": {
|
|
364
433
|
"type": "boolean",
|
|
365
|
-
"description": "Detection flag for domains configured to accept mail for any recipient address."
|
|
434
|
+
"description": "Detection flag for domains configured to accept mail for any recipient address. true always corresponds to a top-level validEmail of accept_all."
|
|
366
435
|
}
|
|
367
436
|
},
|
|
368
437
|
"description": "Domain validation details for the email address."
|
|
@@ -384,24 +453,24 @@
|
|
|
384
453
|
},
|
|
385
454
|
"DnsObject": {
|
|
386
455
|
"type": "object",
|
|
387
|
-
"required": [
|
|
456
|
+
"required": [],
|
|
388
457
|
"properties": {
|
|
389
458
|
"mxRecord": {
|
|
390
459
|
"type": "array",
|
|
391
460
|
"items": {
|
|
392
461
|
"type": "string"
|
|
393
462
|
},
|
|
394
|
-
"description": "
|
|
463
|
+
"description": "Every MX hostname at the domain's lowest preference (not just one). [\".\"] means the domain publishes a null MX and accepts no mail at all. Absent entirely when the domain has no MX record of any kind — check aRecord in that case."
|
|
395
464
|
},
|
|
396
465
|
"aRecord": {
|
|
397
466
|
"type": "array",
|
|
398
467
|
"items": {
|
|
399
468
|
"type": "string"
|
|
400
469
|
},
|
|
401
|
-
"description": "Collection of A (Address) records for the domain.
|
|
470
|
+
"description": "Collection of A (Address) records for the domain. Present when the domain has no MX record but does resolve to a web server or other host."
|
|
402
471
|
}
|
|
403
472
|
},
|
|
404
|
-
"description": "DNS records for the email domain."
|
|
473
|
+
"description": "DNS records for the email domain. Absent entirely when the domain publishes neither an MX nor an A record."
|
|
405
474
|
},
|
|
406
475
|
"AddressObject": {
|
|
407
476
|
"type": "object",
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"info": {
|
|
4
4
|
"title": "Email Checker API - Real-Time Validation, Deliverability & Risk Signals",
|
|
5
5
|
"version": "1.0.0",
|
|
6
|
-
"description": "Validate a single email address and receive comprehensive results including syntax validation, domain verification, account detection, DNS records (MX and A records), and optional IP-based geolocation and security enrichment. Returns deliverability assessment with valid/invalid/unknown/risky/app_server_blocked status.",
|
|
6
|
+
"description": "Validate a single email address and receive comprehensive results including syntax validation, domain verification, account detection, DNS records (MX and A records), and optional IP-based geolocation and security enrichment. Returns deliverability assessment with valid/accept_all/invalid/unknown/risky/app_server_blocked status.",
|
|
7
7
|
"contact": {
|
|
8
8
|
"name": "APIFreaks Support",
|
|
9
9
|
"url": "https://apifreaks.com/contact",
|
|
@@ -96,8 +96,8 @@
|
|
|
96
96
|
}
|
|
97
97
|
}
|
|
98
98
|
},
|
|
99
|
-
"
|
|
100
|
-
"summary": "Valid syntax, domain
|
|
99
|
+
"nonexistentDomain": {
|
|
100
|
+
"summary": "Valid syntax, domain does not exist (NXDOMAIN)",
|
|
101
101
|
"value": {
|
|
102
102
|
"success": true,
|
|
103
103
|
"email": "test@nonexistentdomainxyz123abc.com",
|
|
@@ -117,6 +117,83 @@
|
|
|
117
117
|
}
|
|
118
118
|
}
|
|
119
119
|
},
|
|
120
|
+
"acceptAll": {
|
|
121
|
+
"summary": "Catch-all domain accepted the recipient — mailbox unconfirmed",
|
|
122
|
+
"value": {
|
|
123
|
+
"success": true,
|
|
124
|
+
"email": "random12345@yahoo.com",
|
|
125
|
+
"validEmail": "accept_all",
|
|
126
|
+
"validSyntax": true,
|
|
127
|
+
"reason": "domain accepts all addresses.",
|
|
128
|
+
"domain": {
|
|
129
|
+
"name": "yahoo.com",
|
|
130
|
+
"disposable": false,
|
|
131
|
+
"spam": false,
|
|
132
|
+
"free": true,
|
|
133
|
+
"validDomain": true,
|
|
134
|
+
"catchAll": true
|
|
135
|
+
},
|
|
136
|
+
"account": {
|
|
137
|
+
"role": false,
|
|
138
|
+
"fullMailBox": false
|
|
139
|
+
},
|
|
140
|
+
"dns": {
|
|
141
|
+
"mxRecord": [
|
|
142
|
+
"mta5.am0.yahoodns.net.",
|
|
143
|
+
"mta6.am0.yahoodns.net.",
|
|
144
|
+
"mta7.am0.yahoodns.net."
|
|
145
|
+
]
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
},
|
|
149
|
+
"nullMxDomain": {
|
|
150
|
+
"summary": "Domain publishes a null MX (single \".\") — accepts no mail at all",
|
|
151
|
+
"value": {
|
|
152
|
+
"success": true,
|
|
153
|
+
"email": "test@example.com",
|
|
154
|
+
"validEmail": "invalid",
|
|
155
|
+
"validSyntax": true,
|
|
156
|
+
"reason": "domain does not accept mail.",
|
|
157
|
+
"domain": {
|
|
158
|
+
"name": "example.com",
|
|
159
|
+
"disposable": true,
|
|
160
|
+
"spam": false,
|
|
161
|
+
"free": false,
|
|
162
|
+
"validDomain": true,
|
|
163
|
+
"catchAll": false
|
|
164
|
+
},
|
|
165
|
+
"account": {
|
|
166
|
+
"role": false
|
|
167
|
+
},
|
|
168
|
+
"dns": {
|
|
169
|
+
"mxRecord": ["."]
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
},
|
|
173
|
+
"noMxAddressOnly": {
|
|
174
|
+
"summary": "Domain has no MX record but a working A record — gets a real SMTP probe",
|
|
175
|
+
"value": {
|
|
176
|
+
"success": true,
|
|
177
|
+
"email": "test@neverssl.com",
|
|
178
|
+
"validEmail": "unknown",
|
|
179
|
+
"validSyntax": true,
|
|
180
|
+
"reason": "We are unable to determine if email is valid or invalid.",
|
|
181
|
+
"domain": {
|
|
182
|
+
"name": "neverssl.com",
|
|
183
|
+
"disposable": false,
|
|
184
|
+
"spam": false,
|
|
185
|
+
"free": false,
|
|
186
|
+
"validDomain": true,
|
|
187
|
+
"catchAll": false
|
|
188
|
+
},
|
|
189
|
+
"account": {
|
|
190
|
+
"role": false
|
|
191
|
+
},
|
|
192
|
+
"dns": {
|
|
193
|
+
"aRecord": ["34.223.124.45"]
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
},
|
|
120
197
|
"withIp": {
|
|
121
198
|
"summary": "With ip — adds geolocation/security enrichment under address",
|
|
122
199
|
"value": {
|
|
@@ -387,12 +464,12 @@
|
|
|
387
464
|
},
|
|
388
465
|
"reason": {
|
|
389
466
|
"type": "string",
|
|
390
|
-
"description": "Detailed explanation returned when validEmail is not valid."
|
|
467
|
+
"description": "Detailed explanation returned when validEmail is not valid. Omitted entirely when validEmail is valid."
|
|
391
468
|
},
|
|
392
469
|
"validEmail": {
|
|
393
470
|
"type": "string",
|
|
394
|
-
"enum": ["valid", "invalid", "INVALID_EMAIL", "unknown", "risky", "app_server_blocked"],
|
|
395
|
-
"description": "Comprehensive deliverability assessment.
|
|
471
|
+
"enum": ["valid", "accept_all", "invalid", "INVALID_EMAIL", "unknown", "risky", "app_server_blocked"],
|
|
472
|
+
"description": "Comprehensive deliverability assessment. valid: recipient confirmed deliverable, reason omitted. accept_all: the domain is catch-all and accepted the recipient, so this specific mailbox is unconfirmed — see domain.catchAll, reason 'domain accepts all addresses.'. invalid: rejected mailbox, syntax failure, or the domain accepts no mail at all (a null MX). unknown: no conclusive answer, most common for domains with no MX record that only get a probe against their address record. risky: mailbox exists but over quota, or the server deferred with a greylist response. app_server_blocked: our verifier IP was blocked by the receiving server. Casing is inconsistent in the live API: syntactically invalid addresses can return the raw enum name INVALID_EMAIL instead of lowercase invalid — this is a known API bug, handle it defensively as equivalent to invalid."
|
|
396
473
|
},
|
|
397
474
|
"validSyntax": {
|
|
398
475
|
"type": "boolean",
|
|
@@ -444,7 +521,7 @@
|
|
|
444
521
|
},
|
|
445
522
|
"catchAll": {
|
|
446
523
|
"type": "boolean",
|
|
447
|
-
"description": "Detection flag for domains configured to accept mail for any recipient address."
|
|
524
|
+
"description": "Detection flag for domains configured to accept mail for any recipient address. true always corresponds to a top-level validEmail of accept_all."
|
|
448
525
|
}
|
|
449
526
|
},
|
|
450
527
|
"description": "Domain validation details for the email address."
|
|
@@ -466,24 +543,24 @@
|
|
|
466
543
|
},
|
|
467
544
|
"DnsObject": {
|
|
468
545
|
"type": "object",
|
|
469
|
-
"required": [
|
|
546
|
+
"required": [],
|
|
470
547
|
"properties": {
|
|
471
548
|
"mxRecord": {
|
|
472
549
|
"type": "array",
|
|
473
550
|
"items": {
|
|
474
551
|
"type": "string"
|
|
475
552
|
},
|
|
476
|
-
"description": "
|
|
553
|
+
"description": "Every MX hostname at the domain's lowest preference (not just one). [\".\"] means the domain publishes a null MX and accepts no mail at all. Absent entirely when the domain has no MX record of any kind — check aRecord in that case."
|
|
477
554
|
},
|
|
478
555
|
"aRecord": {
|
|
479
556
|
"type": "array",
|
|
480
557
|
"items": {
|
|
481
558
|
"type": "string"
|
|
482
559
|
},
|
|
483
|
-
"description": "Collection of A (Address) records for the domain.
|
|
560
|
+
"description": "Collection of A (Address) records for the domain. Present when the domain has no MX record but does resolve to a web server or other host."
|
|
484
561
|
}
|
|
485
562
|
},
|
|
486
|
-
"description": "DNS records for the email domain."
|
|
563
|
+
"description": "DNS records for the email domain. Absent entirely when the domain publishes neither an MX nor an A record."
|
|
487
564
|
},
|
|
488
565
|
"AddressObject": {
|
|
489
566
|
"type": "object",
|