Node.js SDK Documentation
Official JavaScript/TypeScript SDK for InboxRisk API. Works with Node.js and modern browsers.
Installation
Install the InboxRisk SDK using npm, yarn, or pnpm:
npm
npm install inboxriskyarn
yarn add inboxriskpnpm
pnpm add inboxriskQuick Setup
Initialize the SDK with your API key:
import { InboxRisk } from 'inboxrisk';
// Initialize client
const client = new InboxRisk({
apiKey: 'your_api_key_here'
});
// Or use environment variable
const client = new InboxRisk();
// This will use process.env.INBOXRISK_API_KEY💡 Tip: Store your API key in environment variables. Never commit it to version control.
Usage Examples
Email Risk Check
Perform comprehensive email risk assessment:
async function checkEmail() {
const result = await client.email.riskCheck({
email: 'user@example.com'
});
console.log('Risk Score:', result.risk_score);
console.log('Risk Level:', result.risk_level);
console.log('Is Disposable:', result.is_disposable);
console.log('Fraud Reports:', result.fraud_reports);
}Disposable Email Detection
Quick check for temporary email addresses:
async function checkDisposable() {
const result = await client.email.disposableCheck({
email: 'user@tempmail.com'
});
if (result.is_disposable) {
console.log('This is a temporary email');
console.log('Provider:', result.provider);
}
}Email Reputation
Get sender reputation and deliverability status:
async function checkReputation() {
const result = await client.email.reputation({
email: 'sender@company.com'
});
console.log('Reputation Score:', result.reputation_score);
console.log('Deliverability:', result.deliverability);
console.log('SPF Status:', result.spf_status);
console.log('DKIM Status:', result.dkim_status);
}Content Analysis
Analyze email content for phishing and fraud indicators:
async function analyzeContent() {
const result = await client.email.contentAnalysis({
email: 'user@example.com',
subject: 'Verify Your Account',
body: 'Click here to verify your account'
});
console.log('Phishing Score:', result.phishing_score);
console.log('Phishing Level:', result.phishing_level);
console.log('Fraud Indicators:', result.fraud_indicators);
}Bulk Email Checking
Check multiple emails in a single request:
async function bulkCheck() {
const result = await client.email.bulkCheck({
emails: [
'user1@example.com',
'user2@example.com',
'user3@tempmail.com'
]
});
console.log('Total:', result.total);
console.log('Processed:', result.processed);
result.results.forEach(email => {
console.log(`${email.email}: Risk ${email.risk_level}`);
});
}Error Handling
Always wrap API calls in try-catch blocks to handle errors:
try {
const result = await client.email.riskCheck({
email: 'user@example.com'
});
console.log('Risk score:', result.risk_score);
} catch (error) {
if (error.code === 'UNAUTHORIZED') {
console.error('Invalid API key');
} else if (error.code === 'RATE_LIMITED') {
console.error('Rate limit exceeded');
} else if (error.code === 'INVALID_EMAIL') {
console.error('Invalid email format');
} else {
console.error('API Error:', error.message);
}
}⚠️ Important: Implement exponential backoff for rate limit (429) errors and retry requests appropriately.
TypeScript Support
The SDK includes full TypeScript support with types:
import { InboxRisk } from 'inboxrisk';
import type { EmailRiskResponse, DisposableCheckResponse } from 'inboxrisk';
const client = new InboxRisk();
async function typedExample() {
const result: EmailRiskResponse = await client.email.riskCheck({
email: 'user@example.com'
});
// Full autocomplete and type checking
console.log(result.risk_score);
}Advanced Options
Custom Configuration
const client = new InboxRisk({
apiKey: 'your_api_key',
timeout: 10000, // 10 second timeout
retries: 3, // Retry failed requests
baseUrl: 'https://api.inboxrisk.com'
});Webhook Configuration
Setup webhooks for async event notifications:
await client.webhooks.create({
url: 'https://your-app.com/webhook',
events: ['risk_check.completed'],
active: true
});