March 24, 202610 min readInboxParse Team

Getting Started with the InboxParse API: cURL, Node.js, Python & PHP

Code examples for every popular language and HTTP client — cURL, fetch, axios, Python requests, and PHP Guzzle. Authenticate, list emails, search, and fetch threads in minutes.

apitutorialnodepythonphp

InboxParse turns email inboxes into a clean REST API — structured, AI-ready data you can query from any language. No IMAP, no MIME parsing, no OAuth token juggling. Just HTTP requests and JSON responses.

This guide walks you through your first API calls using cURL, Node.js (native fetch and axios), Python, and PHP. By the end you'll know how to authenticate, list emails, search your inbox, and fetch full conversation threads.

Prerequisites

Create a free InboxParse account (no credit card required).
Connect at least one mailbox — Gmail or IMAP — from Console → Mailboxes.
Generate an API key from Console → API Keys. Keys start with ip_.

All examples use the base URL https://inboxparse.com/api/v1.

Authentication

Every request needs your API key in the Authorization header:

Authorization: Bearer ip_your_api_key

You can also use the X-API-Key header if you prefer. API keys come in two roles:

Admin — full read/write access (send emails, create mailboxes, manage webhooks).
Member — read-only access (list emails, search, view threads).

All examples below work with either role unless noted otherwise.

cURL

The quickest way to test the API. No dependencies, works everywhere.

List recent emails

curl -s "https://inboxparse.com/api/v1/emails?limit=10&format=markdown" \
  -H "Authorization: Bearer ip_your_api_key"

Get a single email

curl -s "https://inboxparse.com/api/v1/emails/msg_01jxxxxxxxxx?format=full" \
  -H "Authorization: Bearer ip_your_api_key"

Search emails

curl -s -X POST "https://inboxparse.com/api/v1/search" \
  -H "Authorization: Bearer ip_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "invoice overdue", "mode": "hybrid", "limit": 20}'

List threads

curl -s "https://inboxparse.com/api/v1/threads?limit=10" \
  -H "Authorization: Bearer ip_your_api_key"

Node.js (fetch)

Native fetch is built into Node.js 18+ — no packages needed. Perfect for scripts and serverless functions.

List emails

const API_KEY = "ip_your_api_key";
const BASE_URL = "https://inboxparse.com/api/v1";

const headers = { Authorization: `Bearer ${API_KEY}` };

// List recent emails
const res = await fetch(`${BASE_URL}/emails?limit=10&format=markdown`, { headers });
const { data, pagination } = await res.json();

console.log(`Got ${data.length} emails`);
for (const email of data) {
  console.log(`[${email.direction}] ${email.subject} — from ${email.from}`);
}

Search emails

// Search emails (hybrid = full-text + semantic)
const res = await fetch(`${BASE_URL}/search`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ query: "invoice overdue", mode: "hybrid", limit: 20 }),
});
const { data } = await res.json();

for (const email of data) {
  console.log(`${email.subject} — ${email.ai?.summary}`);
}

Get a thread

// Get a full thread with all messages
const res = await fetch(`${BASE_URL}/threads/thr_01jxxxxxxxxx?format=markdown`, { headers });
const { data: thread } = await res.json();

console.log(`Thread: ${thread.subject} (${thread.message_count} messages)`);
for (const msg of thread.messages) {
  console.log(`  ${msg.from}: ${msg.content.markdown.slice(0, 100)}...`);
}

Node.js (axios)

axios is the most popular HTTP client for Node.js. It handles JSON serialization, base URLs, and default headers automatically.

npm install axios

import axios from "axios";

const client = axios.create({
  baseURL: "https://inboxparse.com/api/v1",
  headers: { Authorization: "Bearer ip_your_api_key" },
});

// List emails
const { data: { data: emails, pagination } } = await client.get("/emails", {
  params: { limit: 10, format: "markdown" },
});

// Search
const { data: { data: results } } = await client.post("/search", {
  query: "invoice overdue",
  mode: "hybrid",
});

// Get thread
const { data: { data: thread } } = await client.get("/threads/thr_01jxxxxxxxxx", {
  params: { format: "markdown" },
});

Python (requests)

requests is the standard HTTP library for Python. Install it with pip:

pip install requests

import requests

API_KEY = "ip_your_api_key"
BASE_URL = "https://inboxparse.com/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# List emails
resp = requests.get(f"{BASE_URL}/emails", headers=headers, params={
    "limit": 10,
    "format": "markdown",
})
emails = resp.json()["data"]
for email in emails:
    print(f"[{email['direction']}] {email['subject']} — from {email['from']}")

# Search
resp = requests.post(f"{BASE_URL}/search", headers=headers, json={
    "query": "invoice overdue",
    "mode": "hybrid",
    "limit": 20,
})
results = resp.json()["data"]

# Get thread
resp = requests.get(
    f"{BASE_URL}/threads/thr_01jxxxxxxxxx",
    headers=headers,
    params={"format": "markdown"},
)
thread = resp.json()["data"]
print(f"Thread: {thread['subject']} ({thread['message_count']} messages)")

PHP (Guzzle)

GuzzleHttp is the go-to HTTP client for PHP. Install it via Composer:

composer require guzzlehttp/guzzle

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://inboxparse.com/api/v1/',
    'headers'  => ['Authorization' => 'Bearer ip_your_api_key'],
]);

// List emails
$resp = $client->get('emails', ['query' => ['limit' => 10, 'format' => 'markdown']]);
$body = json_decode($resp->getBody(), true);
foreach ($body['data'] as $email) {
    echo "[{$email['direction']}] {$email['subject']}\n";
}

// Search
$resp = $client->post('search', ['json' => [
    'query' => 'invoice overdue',
    'mode'  => 'hybrid',
    'limit' => 20,
]]);
$results = json_decode($resp->getBody(), true)['data'];

// Get thread
$resp = $client->get('threads/thr_01jxxxxxxxxx', [
    'query' => ['format' => 'markdown'],
]);
$thread = json_decode($resp->getBody(), true)['data'];
echo "Thread: {$thread['subject']} ({$thread['message_count']} messages)\n";

Response Format

All responses follow the same structure:

// Single item
{ "data": { "id": "msg_01j...", "subject": "Hello", ... } }

// Paginated list
{
  "data": [ ... ],
  "pagination": { "next_cursor": "eyJpZCI6...", "has_more": true }
}

// Error
{
  "error": { "message": "API key is invalid", "code": "unauthorized" }
}

Content formats

Use the format query parameter to control how email bodies are returned:

Value	Returns	Best for
`markdown`	Clean Markdown body	LLMs and AI agents (default)
`full`	Markdown + text + HTML	Apps that need all formats
`raw`	Raw HTML only	Email rendering

Add ?compact=true to any request to get shortened JSON keys — saves tokens when piping responses to an LLM.

Pagination

List endpoints use cursor-based pagination. Pass the next_cursor value from a response as the cursor parameter in your next request. When has_more is false, you've reached the end.

Error Handling

The API uses standard HTTP status codes with a consistent error body:

Status	Code	Meaning
400	`validation_error`	Invalid parameters
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	Member key on an admin-only endpoint
404	`not_found`	Resource doesn't exist or wrong workspace
429	`rate_limit_exceeded`	Monthly tier limit reached

Next Steps

Full API reference — every endpoint, parameter, and response field.
MCP server guide — connect your AI agent to InboxParse without writing any code.
Webhooks — get push notifications when new emails arrive or are processed.
API Playground — test requests interactively from your browser.
Pricing — free tier includes 500 emails/month and 20,000 API calls.

Ready to give your AI agent a mailbox?

Free plan available. No credit card required.

Start building free Read the docs