Skip to content

Commit fc9ac1d

Browse files
Camila ViscontiCamila Visconti
Camila Visconti
authored and
Camila Visconti
committed
New Email Reputation API doc page
1 parent 4485380 commit fc9ac1d

File tree

8 files changed

+432
-0
lines changed

8 files changed

+432
-0
lines changed

‎.DS_Store

0 Bytes
Binary file not shown.

‎email-reputation/.DS_Store

6 KB
Binary file not shown.

‎email-reputation/email-validation.mdx

+382
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,382 @@
1+
---
2+
title: 'Email Reputation API'
3+
description: 'Improve your delivery rates, clean your email lists, and block fraudulent users with Abstract’s industry-leading Email Reputation API.'
4+
icon: 'envelope'
5+
api: 'GET https://emailreputation.abstractapi.com/v1'
6+
hideApiMarker: true
7+
---
8+
9+
## Getting Started
10+
11+
Abstract's Email Reputation API requires only your unique API key `api_key` and a single email `email`:
12+
13+
```bash
14+
https://emailreputation.abstractapi.com/v1/
15+
? api_key = YOUR_UNIQUE_API_KEY
16+
& email = [email protected]
17+
```
18+
19+
This was a successful request, and all available details about that email were returned:
20+
21+
<ResponseExample>
22+
23+
```json
24+
{
25+
"email_address": "[email protected]",
26+
"email_deliverability": {
27+
"status": "deliverable",
28+
"status_detail": "valid_email",
29+
"is_format_valid": true,
30+
"is_smtp_valid": true,
31+
"is_mx_valid": true,
32+
"mx_records": [
33+
"gmail-smtp-in.l.google.com",
34+
"alt3.gmail-smtp-in.l.google.com",
35+
"alt4.gmail-smtp-in.l.google.com",
36+
"alt1.gmail-smtp-in.l.google.com",
37+
"alt2.gmail-smtp-in.l.google.com"
38+
]
39+
},
40+
"email_quality": {
41+
"score": 0.8,
42+
"is_free_email": false,
43+
"is_username_suspicious": false,
44+
"is_disposable": false,
45+
"is_catchall": true,
46+
"is_subaddress": false,
47+
"is_role": false,
48+
"is_dmarc_enforced": true,
49+
"is_spf_strict": true,
50+
"minimum_age": 1418
51+
},
52+
"email_sender": {
53+
"first_name": "Benjamin",
54+
"last_name": "Richard",
55+
"email_provider_name": "Google",
56+
"organization_name": "Abstract API",
57+
"organization_type": "company"
58+
},
59+
"email_domain": {
60+
"domain": "abstractapi.com",
61+
"domain_age": 1418,
62+
"is_live_site": true,
63+
"registrar": "NAMECHEAP INC",
64+
"registrar_url": "http://www.namecheap.com",
65+
"date_registered": "2020-05-13",
66+
"date_last_renewed": "2024-04-13",
67+
"date_expires": "2025-05-13",
68+
"is_risky_tld": false
69+
},
70+
"email_risk": {
71+
"address_risk_status": "low",
72+
"domain_risk_status": "low"
73+
},
74+
"email_breaches": {
75+
"total_breaches": 2,
76+
"date_first_breached": "2018-07-23T14:30:00Z",
77+
"date_last_breached": "2019-05-24T14:30:00Z",
78+
"breached_domains": [
79+
{ "domain": "apollo.io", "date_breached": "2018-07-23T14:30:00Z" },
80+
{ "domain": "canva.com", "date_breached": "2019-05-24T14:30:00Z" }
81+
]
82+
}
83+
}
84+
85+
```
86+
87+
</ResponseExample>
88+
89+
### Request parameters
90+
91+
<ParamField query="api_key" type="string" required>
92+
Your unique API key. Note that each user has unique API keys _for each of
93+
Abstract's APIs_, so your Email Validation API key will not work for your IP
94+
Geolocation API, for example.
95+
</ParamField>
96+
97+
<ParamField query="email" type="String" required>
98+
The email address to validate.
99+
</ParamField>
100+
101+
### Response parameters
102+
103+
The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html).
104+
105+
<ResponseField name="email_address" type="String">
106+
The email address you submitted for analysis.
107+
</ResponseField>
108+
109+
<ResponseField name="email_deliverability.status" type="String">
110+
Whether the email is considered `deliverable`, `undeliverable`, or `unknown`.
111+
</ResponseField>
112+
113+
<ResponseField name="email_deliverability.status_detail" type="String">
114+
Additional detail on deliverability (e.g., `inbox_full`, `full_mailbox`, `invalid_format`).
115+
</ResponseField>
116+
117+
<ResponseField name="email_deliverability.is_format_valid" type="Boolean">
118+
Is `true` if the email follows the correct format.
119+
</ResponseField>
120+
121+
<ResponseField name="email_deliverability.is_smtp_valid" type="Boolean">
122+
Is `true` if the SMTP check was successful.
123+
</ResponseField>
124+
125+
<ResponseField name="email_deliverability.is_mx_valid" type="Boolean">
126+
Is `true` if the domain has valid MX records.
127+
</ResponseField>
128+
129+
<ResponseField name="email_deliverability.mx_records" type="Array[String]">
130+
List of MX records associated with the domain.
131+
</ResponseField>
132+
133+
<ResponseField name="email_quality.score" type="Float">
134+
Confidence score between 0.01 and 0.99 representing email quality.
135+
</ResponseField>
136+
137+
<ResponseField name="email_quality.is_free_email" type="Boolean">
138+
Is `true` if the email is from a known free provider like Gmail or Yahoo.
139+
</ResponseField>
140+
141+
<ResponseField name="email_quality.is_username_suspicious" type="Boolean">
142+
Is `true` if the username appears auto-generated or suspicious.
143+
</ResponseField>
144+
145+
<ResponseField name="email_quality.is_disposable" type="Boolean">
146+
Is `true` if the email is from a disposable email provider.
147+
</ResponseField>
148+
149+
<ResponseField name="email_quality.is_catchall" type="Boolean">
150+
Is `true` if the domain is configured to accept all emails.
151+
</ResponseField>
152+
153+
<ResponseField name="email_quality.is_subaddress" type="Boolean">
154+
Is `true` if the email uses subaddressing (e.g., `[email protected]`).
155+
</ResponseField>
156+
157+
<ResponseField name="email_quality.is_role" type="Boolean">
158+
Is `true` if the email is a role-based address (e.g., `[email protected]`, `[email protected]`).
159+
</ResponseField>
160+
161+
<ResponseField name="email_quality.is_dmarc_enforced" type="Boolean">
162+
Is `true` if a strict DMARC policy is enforced on the domain.
163+
</ResponseField>
164+
165+
<ResponseField name="email_quality.is_spf_strict" type="Boolean">
166+
Is `true` if the domain enforces a strict SPF policy.
167+
</ResponseField>
168+
169+
<ResponseField name="email_quality.minimum_age" type="Integer or Null">
170+
Is Estimated age of the email address in days, or `null` if unknown.
171+
</ResponseField>
172+
173+
<ResponseField name="email_sender.first_name" type="String or Null">
174+
First name associated with the email address, if available.
175+
</ResponseField>
176+
177+
<ResponseField name="email_sender.last_name" type="String or Null">
178+
Last name associated with the email address, if available.
179+
</ResponseField>
180+
181+
<ResponseField name="email_sender.email_provider_name" type="String or Null">
182+
Name of the email provider (e.g., Google, Microsoft).
183+
</ResponseField>
184+
185+
<ResponseField name="email_sender.organization_name" type="String or Null">
186+
Organization linked to the email or domain, if available.
187+
</ResponseField>
188+
189+
<ResponseField name="email_sender.organization_type" type="String or Null">
190+
Type of organization (e.g., `company`).
191+
</ResponseField>
192+
193+
<ResponseField name="email_domain.domain" type="String">
194+
Domain part of the submitted email address.
195+
</ResponseField>
196+
197+
<ResponseField name="email_domain.domain_age" type="Integer">
198+
Age of the domain in days.
199+
</ResponseField>
200+
201+
<ResponseField name="email_domain.is_live_site" type="Boolean">
202+
Is `true` if the domain has a live website.
203+
</ResponseField>
204+
205+
<ResponseField name="email_domain.registrar" type="String or Null">
206+
Name of the domain registrar.
207+
</ResponseField>
208+
209+
<ResponseField name="email_domain.registrar_url" type="String or Null">
210+
URL of the domain registrar.
211+
</ResponseField>
212+
213+
<ResponseField name="email_domain.date_registered" type="Datetime">
214+
Date when the domain was registered.
215+
</ResponseField>
216+
217+
<ResponseField name="email_domain.date_last_renewed" type="Datetime">
218+
Last renewal date of the domain.
219+
</ResponseField>
220+
221+
<ResponseField name="email_domain.date_expires" type="Datetime">
222+
Expiration date of the domain registration.
223+
</ResponseField>
224+
225+
<ResponseField name="email_domain.is_risky_tld" type="Boolean">
226+
Is `true` if the domain uses a top-level domain associated with risk.
227+
</ResponseField>
228+
229+
<ResponseField name="email_risk.address_risk_status" type="String">
230+
Risk status of the email address: `low`, `medium`, or `high`.
231+
</ResponseField>
232+
233+
<ResponseField name="email_risk.domain_risk_status" type="String">
234+
Risk status of the domain: `low`, `medium`, or `high`.
235+
</ResponseField>
236+
237+
<ResponseField name="email_breaches.total_breaches" type="Integer">
238+
Total number of data breaches involving this email.
239+
</ResponseField>
240+
241+
<ResponseField name="email_breaches.date_first_breached" type="Datetime">
242+
Date of the first known breach.
243+
</ResponseField>
244+
245+
<ResponseField name="email_breaches.date_last_breached" type="Datetime">
246+
Date of the most recent breach.
247+
</ResponseField>
248+
249+
<ResponseField name="email_breaches.breached_domains" type="Array[Object]">
250+
List of breached domains including:
251+
</ResponseField>
252+
253+
<ResponseField name="email_breaches.breached_domains[].domain" type="String">
254+
Domain affected by the breach.
255+
</ResponseField>
256+
257+
<ResponseField name="email_breaches.breached_domains[].date_breached" type="Datetime">
258+
Date when the breach occurred.
259+
</ResponseField>
260+
261+
## Request examples
262+
263+
### Checking a malformed email
264+
265+
In the example below, we show the request and response for an email does not follow the proper format. If the email fails the `is_valid_format` check, then the other checks will not be performed and will be returned as false
266+
267+
```bash
268+
https://emailreputation.abstractapi.com/v1/
269+
? api_key = YOUR_UNIQUE_API_KEY
270+
& email = johnsmith
271+
```
272+
273+
The request was valid and successful, and so it returns the following:
274+
275+
```json
276+
{
277+
"email_address": "johnsmith",
278+
"email_deliverability": {
279+
"status": "undeliverable",
280+
"status_detail": "invalid_format",
281+
"is_format_valid": false,
282+
"is_smtp_valid": false,
283+
"is_mx_valid": false,
284+
"mx_records": []
285+
},
286+
"email_quality": {
287+
"score": null,
288+
"is_free_email": null,
289+
"is_username_suspicious": null,
290+
"is_disposable": null,
291+
"is_catchall": null,
292+
"is_subaddress": null,
293+
"is_role": null,
294+
"is_dmarc_enforced": null,
295+
"is_spf_strict": null,
296+
"minimum_age": null
297+
},
298+
"email_sender": {
299+
"first_name": null,
300+
"last_name": null,
301+
"email_provider_name": null,
302+
"organization_name": null,
303+
"organization_type": null
304+
},
305+
"email_domain": {
306+
"domain": null,
307+
"domain_age": null,
308+
"is_live_site": null,
309+
"registrar": null,
310+
"registrar_url": null,
311+
"date_registered": null,
312+
"date_last_renewed": null,
313+
"date_expires": null,
314+
"is_risky_tld": null
315+
},
316+
"email_risk": {
317+
"address_risk_status": null,
318+
"domain_risk_status": null
319+
},
320+
"email_breaches": {
321+
"total_breaches": null,
322+
"date_first_breached": null,
323+
"date_last_breached": null,
324+
"breached_domains": []
325+
}
326+
}
327+
```
328+
329+
## Possible values for status_detail
330+
331+
This field provides more information about the deliverability result.
332+
333+
#### When `status` is `deliverable`:
334+
335+
- **valid_email**: The email address exists, is valid, and can receive new emails.
336+
- **high_traffic_email**: The email is valid and exists, but the server is receiving too many messages. Your email might bounce.
337+
338+
#### When `status` is `undeliverable`:
339+
340+
- **invalid_mailbox**: The email address doesn't exist or is no longer active. It can't receive new emails.
341+
- **full_mailbox**: The email exists but its mailbox is full, so new emails will bounce.
342+
- **invalid_format**: The email doesn't follow the correct format (e.g., missing `@` or domain).
343+
- **dns_record_not_found**: We couldn't find MX records for the domain, so we couldn’t complete the SMTP check.
344+
- **unavailable_server**: The mail server for the domain is currently unreachable.
345+
346+
#### When `status` is `unknown`:
347+
348+
- **null**
349+
350+
## Bulk upload (CSV)
351+
352+
Don't know how to or don't want to make API calls? Use the bulk CSV uploader to easily use the API. The results will be sent to your email when ready.
353+
354+
Here are some best practices when bulk uploading a CSV file:
355+
356+
* Ensure the selected column contains the email addresses to be analyzed.
357+
* Remove any empty rows from the file.
358+
* Include only one email address per row.
359+
* The maximum file size permitted is 50,000 rows.
360+
361+
362+
## Response and error codes
363+
364+
Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.
365+
366+
| Code | Type | Details |
367+
| ----------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
368+
| 200 | OK | Everything worked as expected. |
369+
| 400 | Bad request | Bad request. |
370+
| 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. |
371+
| 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) |
372+
| 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. |
373+
| 500 | Internal server error | The request could not be completed due to an error on the server side. |
374+
| 503 | Service unavailable | The server was unavailable. |
375+
376+
## Code samples and libraries
377+
378+
Please see the top of this page for code samples for these languages and more. If we're missing a code sample, or if you'd like to contribute a code sample or library in exchange for free credits, email us at: [email protected]
379+
380+
## Other notes
381+
382+
A note on metered billing: Each individual email you submit counts as a credit used. Credits are also counted per request, not per successful response. So if you submit a request for the (invalid) email address "kasj8929hs", that still counts as 1 credit.

‎email-reputation/favicon.png

432 Bytes
Loading

‎email-reputation/logo/.DS_Store

6 KB
Binary file not shown.

‎email-reputation/logo/dark.png

10.5 KB
Loading

‎email-reputation/logo/light.png

13.6 KB
Loading

0 commit comments

Comments
 (0)