Skip to content

Commit 0d649ca

Browse files
jlalmesjlalmes
committed
0 parents  commit 0d649ca

12 files changed

+11901
-0
lines changed

‎.github/workflows/ci.yml

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
on:
2+
push:
3+
branches:
4+
- main
5+
pull_request:
6+
types:
7+
- opened
8+
- synchronize
9+
- reopened
10+
jobs:
11+
ci:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout code
15+
uses: actions/checkout@v3
16+
17+
- name: Set up Node.js
18+
uses: actions/setup-node@v3
19+
with:
20+
node-version: '22.11.0'
21+
22+
- name: Install dependencies
23+
run: npm ci
24+
25+
- name: Run tests
26+
run: npm run test

‎.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
*.log
2+
.DS_Store
3+
node_modules
4+
dist

‎.vscode/settings.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"workbench.colorCustomizations": {
3+
"titleBar.activeBackground": "#600DFF",
4+
"titleBar.activeForeground": "#ffffff"
5+
},
6+
"typescript.tsdk": "node_modules/typescript/lib",
7+
"editor.defaultFormatter": "esbenp.prettier-vscode",
8+
"editor.formatOnSave": true,
9+
"editor.codeActionsOnSave": {
10+
"source.fixAll.eslint": "explicit"
11+
}
12+
}

‎LICENSE

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Getinbox (https://www.getinbox.co/)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md

+184
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
[![getinbox-js](assets/getinbox-readme.png)](https://www.getinbox.co/)
2+
3+
<div align="center">
4+
<h1>getinbox</h1>
5+
<a href="https://www.npmjs.com/package/getinbox"><img src="https://img.shields.io/npm/v/getinbox.svg?style=flat&color=brightgreen" target="_blank" /></a>
6+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-black" /></a>
7+
<a href="https://www.getinbox.co/dashboard/api-key" target="_blank"><img src="https://img.shields.io/badge/api_key-free-600dff" /></a>
8+
<br />
9+
<hr />
10+
</div>
11+
12+
#### `getinbox` is maintained by [Getinbox](https://www.getinbox.co/) - simple, fast and free online [email finder](https://www.getinbox.co/tools/email-finder) tools.
13+
14+
---
15+
16+
## ✅ **Email finder & verifier for Node.js**
17+
18+
- Find anyone's professional email address with 99% accuracy
19+
- Verify email deliverability without sending test emails
20+
- Detect disposable email addresses
21+
- Double-verifies catch-all mailboxes
22+
- Full TypeScript support with detailed type definitions
23+
24+
## Installation
25+
26+
```bash
27+
npm install getinbox
28+
```
29+
30+
## Quick Start
31+
32+
```typescript
33+
import { Getinbox } from 'getinbox';
34+
35+
// Initialize the client
36+
const getinbox = new Getinbox({
37+
apiKey: 'your_api_key', // or set GETINBOX_API_KEY env variable
38+
});
39+
40+
// Find an email address
41+
const { email } = await getinbox.emails.find({
42+
name: 'Elon Musk',
43+
company: 'spacex.com', // Using domain instead of company name provides better accuracy
44+
});
45+
46+
// Verify an email address
47+
const { isValid } = await getinbox.emails.verify({
48+
email: '[email protected]',
49+
});
50+
```
51+
52+
## Requirements
53+
54+
- Node.js 14 or later
55+
- TypeScript 4.7 or later (optional)
56+
57+
## API Reference
58+
59+
### Authentication
60+
61+
Sign up for a free API key at 👉 [getinbox.co/dashboard/api-key](https://www.getinbox.co/dashboard/api-key).
62+
63+
You can provide your API key in two ways:
64+
65+
**1. Pass it when initializing the client:**
66+
67+
```typescript
68+
const getinbox = new Getinbox({ apiKey: 'your_api_key' });
69+
```
70+
71+
**2. Set it as an environment variable:**
72+
73+
```bash
74+
export GETINBOX_API_KEY=your_api_key
75+
const getinbox = new Getinbox(); // Will use GETINBOX_API_KEY env variable
76+
```
77+
78+
### Finding Email Addresses
79+
80+
Find someone's email address using their name and company information:
81+
82+
```typescript
83+
const response = await getinbox.emails.find({
84+
name: 'John Doe', // Full name of the person
85+
company: 'acme.com', // Company domain (preferred) or name
86+
});
87+
88+
console.log(response.email); // => '[email protected]'
89+
```
90+
91+
### Verifying Email Addresses
92+
93+
Verify if an email address exists and is deliverable:
94+
95+
```typescript
96+
const response = await getinbox.emails.verify({
97+
email: '[email protected]',
98+
});
99+
100+
console.log(response.isValid); // => true/false
101+
```
102+
103+
## Features in Detail
104+
105+
### Email Finder
106+
107+
- Discovers professional email addresses with 99% accuracy
108+
- Uses advanced pattern matching and verification
109+
- Cleans and formats input data automatically
110+
- Real-time verification of found emails
111+
112+
### Email Verifier
113+
114+
- Validates email existence without sending test emails
115+
- Checks syntax, domain validity, and mailbox existence
116+
- Detects disposable email addresses
117+
- Identifies catch-all domains
118+
- Helps maintain sender reputation by preventing bounces
119+
120+
## Error Handling
121+
122+
The SDK throws descriptive errors for invalid API keys, failed requests, and API errors:
123+
124+
```typescript
125+
try {
126+
const response = await getinbox.emails.find({
127+
name: 'John Doe',
128+
company: 'acme.com',
129+
});
130+
} catch (error) {
131+
console.error('Error finding email:', error.message);
132+
}
133+
```
134+
135+
## TypeScript Support
136+
137+
The SDK is written in TypeScript and provides comprehensive type definitions:
138+
139+
```typescript
140+
import {
141+
GetinboxOptions,
142+
FindEmailOptions,
143+
VerifyEmailOptions,
144+
} from 'getinbox';
145+
146+
// All options are fully typed
147+
const options: FindEmailOptions = {
148+
name: 'John Doe',
149+
company: 'acme.com',
150+
};
151+
```
152+
153+
## Types
154+
155+
### GetinboxOptions
156+
157+
| Property | Type | Description | Required |
158+
| -------- | -------- | --------------------- | ---------------------------- |
159+
| `apiKey` | `string` | Your Getinbox API key | `false` (if set via env var) |
160+
161+
### FindEmailOptions
162+
163+
| Property | Type | Description | Required |
164+
| --------- | -------- | ----------------------- | -------- |
165+
| `name` | `string` | Full name of the person | `true` |
166+
| `company` | `string` | Company domain or name | `true` |
167+
168+
### VerifyEmailOptions
169+
170+
| Property | Type | Description | Required |
171+
| -------- | -------- | ----------------------- | -------- |
172+
| `email` | `string` | Email address to verify | `true` |
173+
174+
## License
175+
176+
Distributed under the MIT License. See LICENSE for more information.
177+
178+
## Links
179+
180+
If you need support please contact us at 👉 [[email protected]](mailto:[email protected])
181+
182+
- [Getinbox Website](https://www.getinbox.co/)
183+
- [API Key Signup](https://www.getinbox.co/dashboard/api-key)
184+
- [OpenAPI Schema](https://www.getinbox.co/api/openapi.json)

‎assets/getinbox-readme.png

1.01 MB
Loading

0 commit comments

Comments
 (0)