API Documentation

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer dl_your_api_key_here

Base URL

https://app.deeplead.com/api/v1

List Pools

Get a list of your inbox pools. You will need pool IDs to create inboxes.

Response

{
  "pools": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Main Pool",
      "inboxCount": 10,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

List Inboxes

Get a list of your inboxes with optional filtering.

Query Parameters

Response

{
  "inboxes": [
    {
      "id": "507f1f77bcf86cd799439012",
      "emailAddress": "sales@company.com",
      "poolId": "507f1f77bcf86cd799439011",
      "status": "active",
      "dailySendingLimit": 50,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 100,
    "skip": 0,
    "hasMore": false
  }
}

Create Inbox(es)

Create one or more email inboxes. Supports single inbox or batch creation.

Request Body

Single Inbox Example (with poolId)

{
  "emailAddress": "sales@company.com",
  "poolId": "507f1f77bcf86cd799439011",
  "imapPassword": "app-password-here",
  "provider": "google",
  "dailySendingLimit": 50
}

Single Inbox Example (auto-create pool)

{
  "emailAddress": "sales@company.com",
  "imapPassword": "app-password-here",
  "provider": "google"
}

Batch Example (up to 100)

[
  {
    "emailAddress": "inbox1@gmail.com",
    "imapPassword": "password1"
  },
  {
    "emailAddress": "inbox2@gmail.com",
    "imapPassword": "password2"
  }
]

Response

{
  "success": true,
  "summary": {
    "total": 2,
    "created": 2,
    "failed": 0
  },
  "autoCreatedPool": {
    "id": "507f1f77bcf86cd799439011",
    "name": "API Pool - 2024-01-15"
  },
  "results": [
    {
      "emailAddress": "inbox1@gmail.com",
      "success": true,
      "inboxId": "507f1f77bcf86cd799439012",
      "autoFilledFields": ["imapHost", "imapPort", "smtpHost", "smtpPort"]
    },
    {
      "emailAddress": "inbox2@gmail.com",
      "success": true,
      "inboxId": "507f1f77bcf86cd799439013"
    }
  ]
}

Provider Auto-Detection

The API automatically detects IMAP/SMTP settings based on the email domain or the provider field.

Supported Providers

Custom SMTP/IMAP

For providers not in the auto-detect list, provide full connection details:

{
  "emailAddress": "user@customdomain.com",
  "poolId": "507f1f77bcf86cd799439011",
  "imapUsername": "user@customdomain.com",
  "imapPassword": "password",
  "imapHost": "mail.customdomain.com",
  "imapPort": 993,
  "smtpUsername": "user@customdomain.com",
  "smtpPassword": "password",
  "smtpHost": "smtp.customdomain.com",
  "smtpPort": 587
}

Error Handling

All error responses follow this format:

{
  "error": "Error message here",
  "details": [...]  // Optional validation errors
}

HTTP Status Codes

Code Examples

cURL

# Create inbox (pool auto-created)
curl -X POST "https://app.deeplead.com/api/v1/inboxes" \
  -H "Authorization: Bearer dl_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "sales@company.com",
    "imapPassword": "your-app-password",
    "provider": "google"
  }'

# Create inbox with specific pool
curl -X POST "https://app.deeplead.com/api/v1/inboxes" \
  -H "Authorization: Bearer dl_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "sales@company.com",
    "poolId": "507f1f77bcf86cd799439011",
    "imapPassword": "your-app-password",
    "provider": "google"
  }'

# List pools
curl -X GET "https://app.deeplead.com/api/v1/pools" \
  -H "Authorization: Bearer dl_your_api_key_here"

Python

import requests

API_KEY = "dl_your_api_key_here"
BASE_URL = "https://app.deeplead.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create inbox (pool auto-created if not specified)
response = requests.post(
    f"{BASE_URL}/inboxes",
    headers=headers,
    json={
        "emailAddress": "sales@company.com",
        "imapPassword": "your-app-password",
        "provider": "google",
        "dailySendingLimit": 50
    }
)

result = response.json()
print(result)

# Auto-created pool ID is in the response
if "autoCreatedPool" in result:
    pool_id = result["autoCreatedPool"]["id"]
    print(f"Pool created: {pool_id}")

JavaScript / Node.js

const API_KEY = "dl_your_api_key_here";
const BASE_URL = "https://app.deeplead.com/api/v1";

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// Create inbox (pool auto-created if not specified)
const response = await fetch(`${BASE_URL}/inboxes`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    emailAddress: "sales@company.com",
    imapPassword: "your-app-password",
    provider: "google",
    dailySendingLimit: 50,
  }),
});

const result = await response.json();
console.log(result);

// Auto-created pool ID is in the response
if (result.autoCreatedPool) {
  console.log("Pool created:", result.autoCreatedPool.id);
}

Rate Limits

• Maximum 100 inboxes per request
• Maximum 1000 inboxes per hour per API key

Support

Need help with the API? Contact your account manager or email support@deeplead.com