Developers

Docs that get you to JSON fast.

Everything you need to receive your first email, verify it and put it to work.

Quick start · 3 calls

Needs an API key from the dashboard
01 · Add your domain
curl -X POST https://ghostparse.com/v1/domains \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"yourapp.com","inbound_enabled":true}'

Then publish the records it returns.

02 · Set your webhook
curl -X PATCH https://ghostparse.com/v1/webhook \
  -H "Authorization: Bearer $KEY" \
  -d '{"webhook_url":"https://yourapp.com/hook"}'

Or skip it and run the CLI on your laptop.

03 · Send a sample
curl -X POST https://ghostparse.com/v1/samples \
  -H "Authorization: Bearer $KEY"

A realistic email lands at your webhook, signed.

Anatomy of an event

One shape, every email.

  1. 1Headers you can verify. webhook-id, webhook-timestamp and webhook-signature, in the Standard Webhooks format.
  2. 2The message, decoded. Addresses, text, HTML, reply_text and attachments.
  3. 3What we worked out. authentication, spam, thread_id and auto_submitted.
  4. 4Your fields. extracted: whatever your parser asked for.
Every field →
POST /hooks/email
webhook-id: evt_7a1c…
webhook-signature: v1,K5o…

{
  "type": "email.received",
  "data": {
    "from": { "address": "jane@example.com" },
    "subject": "Re: Order #1042",
    "reply_text": "Nothing has arrived yet…",
    "authentication": { "verdict": "pass" },
    "thread_id": "thr_9f2c41d07ab3e5c8",
    "extracted": { "fields": { "order_number": "1042" } }
  }
}
Your endpoint

Paste it, run it, done.

A complete webhook endpoint in PHP, Node.js, Python or Go, with nothing to install: it verifies our signature (rotating secrets and replay protection included), then hands you each email. Every one runs in our test suite against real signed webhooks.

<?php
// A complete GhostParse webhook endpoint in PHP, with no dependencies.
// Run: GHOSTPARSE_WEBHOOK_SECRET=whsec_... php -S localhost:3000 index.php   (PHP 7.4+)
// Or put it on any PHP host and set the webhook URL to it.

const TOLERANCE_SECONDS = 300;

/** Standard Webhooks: base64 HMAC-SHA256 of "<webhook-id>.<webhook-timestamp>.<raw body>". */
function verify(string $body, string $secret): bool
{
    $id = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
    $timestamp = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';
    $signatures = $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '';
    if ($id === '' || !ctype_digit($timestamp) || $signatures === '') {
        return false;
    }
    if (abs(time() - (int) $timestamp) > TOLERANCE_SECONDS) {
        return false; // a replay, or a wrong clock
    }
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$body", $key, true));
    // Several space-separated signatures while you rotate your secret: accept any that matches.
    foreach (explode(' ', $signatures) as $signature) {
        $parts = explode(',', $signature, 2);
        if (hash_equals($expected, end($parts))) {
            return true;
        }
    }
    return false;
}

if ($_SERVER['REQUEST_METHOD'] !== 'POST' || parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) !== '/webhooks/email') {
    http_response_code(404);
    exit;
}
$body = file_get_contents('php://input'); // the raw body: parsing and re-encoding the JSON would break the signature
if (!verify($body, getenv('GHOSTPARSE_WEBHOOK_SECRET'))) { // whsec_... from Dashboard -> Inbound webhook
    http_response_code(400);
    exit('invalid signature');
}
$event = json_decode($body, true);
if ($event['type'] === 'email.received') {
    $email = $event['data'];
    // Save it here. Use $_SERVER['HTTP_WEBHOOK_ID'] to skip an event you've already stored (it's sent again on retries).
    error_log(sprintf('%s: %s (%d attachments)', $email['from']['address'] ?? '', $email['subject'], count($email['attachments'])));
}
http_response_code(200);
echo 'ok';
Webhook inspector

Watch them arrive.

In the dashboard, create a temporary URL and every request to it shows up live: method, headers, body, and whether our signature checks out with your secret. Send a test event, point a test address at it, or make it answer 500 to watch the retries. Kept in memory for two hours at most, never on disk.

How it works →
On localhost

Real email on your laptop.

The CLI streams every email to your local endpoint, signature and all, and simulate fires signed test webhooks offline before you have a domain.

The tutorial →

API reference

Full reference →

Receiving

GET/v1/inbox
POST/v1/samples
GET/v1/deliveries
GET/v1/listen

Integrations

POST/v1/hooks
GET/v1/destinations
POST/v1/rules
POST/v1/rules/test

Domains

POST/v1/domains
POST/v1/domains/:id/verify
POST/v1/domains/:id/addresses
DEL/v1/domains/:id

Sending

POST/v1/emails
GET/v1/usage