Skip to content
InboxGreen

Getting Started

API Base URL

https://api.getinboxgreen.com

Authentication Method

All API requests require a Bearer token in the Authorization header. Generate your API tokens from your dashboard settings.

Rate Limits

API requests are limited to 100 per minute per API key. When you exceed the rate limit, you'll receive a 429 status code with retry information in headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 96
Retry-After: 42

Error Format

All errors return a consistent JSON structure:

{ "error": { "code": "invalid_request", "message": "Domain is required" } }

Authentication

InboxGreen uses Bearer token authentication. Include your API token in the Authorization header of every request. You can manage your API tokens in the dashboard under Settings → API Keys.

Token Management

  • •Tokens can be scoped to specific permissions (read-only, write, admin)
  • •Rotate tokens regularly for security best practices
  • •Revoke compromised tokens immediately from the dashboard
  • •Never commit tokens to version control or expose in client-side code

Authentication Examples

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.getinboxgreen.com/scan

API Endpoints

Polling Guidance

When polling the /fix/status endpoint:

  • •Start with a 1-second interval between requests
  • •Use exponential backoff, maxing out at 10 seconds
  • •Stop polling when state is complete or failed

WebSocket Option: For real-time updates without polling, connect to wss://api.getinboxgreen.com/fix/status?job_id=job_123. The server will push progress events as JSON lines.

Complete Code Examples

Full Workflow: Scan and Monitor

This example shows how to scan a domain, get the job status, and handle the results:

# 1. Start async scan
curl -X POST https://api.getinboxgreen.com/scan \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","async":true}'

# Response: {"job_id": "job_123", "status": "queued"}

# 2. Poll for status
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://api.getinboxgreen.com/fix/status?job_id=job_123"

# Response: {"job_id": "job_123", "state": "complete", "progress": 100}

Official SDKs & Libraries

Official SDKs

Node.js

npm i @inboxgreen/sdk

TypeScript support included. Requires Node.js 14+.

Python

pip install inboxgreen
Coming Soon

Go

go get github.com/inboxgreen/sdk
Coming Soon

Ruby

gem install inboxgreen
Coming Soon

Community Libraries

Community-maintained libraries are available for additional languages. These are not officially supported by InboxGreen but may be useful for your integration.

Disclaimer: Community libraries are maintained by third parties. Use at your own discretion and verify compatibility with current API version.

Postman Collection

Import our Postman collection to quickly test API endpoints and explore request/response formats.

API Status & Support

API Status & Uptime

Monitor real-time API status, historical uptime, and scheduled maintenance windows.

View Status Page

Support Resources

Documentation Home

Browse all guides and tutorials

Contact Support

Get help from our team

API Limits

Rate limits and best practices

Versioning & Breaking Changes

The InboxGreen API is versioned. All endpoints are prefixed with /v1/ to ensure backward compatibility.

  • •Non-breaking changes may be introduced without version bumps
  • •Breaking changes will trigger a new version (e.g., /v2/)
  • •Deprecated endpoints receive 90 days notice before removal
  • •Subscribe to our changelog for update notifications