This document is intended for anyone who wishes to build a reader for our email verification database in a currently unsupported language or to understand better how our data is structured. If you would like us to support your language, contact us.
Database Format
IPQS Database Format Specifications
File Structure
File header:
| Name | Size | Description | ||||||
| Magic bytes | 4 bytes | 4 bytes ASCII IPQS. | ||||||
| Version | 1 byte | Version number of the database file. | ||||||
| Type | 1 byte |
The type of database file. The value determines which type of data.
|
||||||
| CreationTime | 8 bytes | The date and time in Unix timestamp (epoch) format of when the database file was created. | ||||||
| Header count | 1 byte | The number of headers present in the database file. | ||||||
| Headers | x bytes | Each header is 2 bytes in size, showing the header's ID and the size of each entry. |
Possible headers:
| Name | ID | Size | Fields |
| Base | 0 | 3 bytes | Valid, Disposable, Suspect, CatchAll, SmtpScore, Deliverability |
| Fraudscore | 1 | 1 byte | Fraudscore |
| Leaked | 2 | 1 byte | Leaked |
| RecentAbuse | 3 | 1 byte | RecentAbuse |
| UserVelocity | 4 | 1 byte | UserVelocity |
| DomainVelocity | 5 | 1 byte | DomainVelocity |
| DomainCommon | 6 | 1 byte | DomainCommon |
| DomainDisposable | 7 | 1 byte | DomainDisposable |
Node structure:
| Name | Size | Description |
| Leaf | 1 byte | Indicates if the node is a leaf. |
| N | 8 byte | The number of data points the node has. |
| Data | x bytes | A variable number of bytes in the Data section. The first 32 bytes are the hash. The remaining bytes are the data for the headers. |
| Children | x bytes | The position in the database file for the child nodes. Each child node is 8 bytes in size, one per data point. |
How the Database Readers Search the Database
The database reader begins by hashing the search query using the SHA-256 hashing function, producing a 32-byte hashed value.
Next, the reader examines the root node of the tree structure and compares the hashed value against entries within the node.
If the hashed value is smaller than the current entry being compared and no exact match is found, the reader moves to the left (or corresponding child) node. If the hashed value is larger, it moves to the right (or another appropriate child node based on the indexing structure).
This process repeats until the reader either finds a leaf node or an exact hash match. If an exact match is found, the reader has found the result. If it finds a leaf node, that indicates the queried value is not present in the database.