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 dashboardcurl -X POST https://ghostparse.com/v1/domains \
-H "Authorization: Bearer $KEY" \
-d '{"name":"yourapp.com","inbound_enabled":true}'
Then publish the records it returns.
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.
curl -X POST https://ghostparse.com/v1/samples \ -H "Authorization: Bearer $KEY"
A realistic email lands at your webhook, signed.
One shape, every email.
- 1Headers you can verify. webhook-id, webhook-timestamp and webhook-signature, in the Standard Webhooks format.
- 2The message, decoded. Addresses, text, HTML, reply_text and attachments.
- 3What we worked out. authentication, spam, thread_id and auto_submitted.
- 4Your fields. extracted: whatever your parser asked for.
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" } } } }
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';
// A complete GhostParse webhook endpoint in Node.js, with no dependencies.
// Run: GHOSTPARSE_WEBHOOK_SECRET=whsec_... node server.mjs (Node 18+)
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
const SECRET = process.env.GHOSTPARSE_WEBHOOK_SECRET; // whsec_... from Dashboard -> Inbound webhook
const PORT = Number(process.env.PORT || 3000);
const TOLERANCE_SECONDS = 5 * 60;
/** Standard Webhooks: base64 HMAC-SHA256 of "<webhook-id>.<webhook-timestamp>.<raw body>". */
function verify(body, headers) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"];
if (!id || !timestamp || !signatures) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false; // a replay, or a wrong clock
const key = Buffer.from(SECRET.replace(/^whsec_/, ""), "base64");
const expected = createHmac("sha256", key).update(`${id}.${timestamp}.`).update(body).digest();
// Several space-separated signatures while you rotate your secret: accept any that matches.
return signatures.split(" ").some((s) => {
const sig = Buffer.from(s.replace(/^v1,/, ""), "base64");
return sig.length === expected.length && timingSafeEqual(sig, expected);
});
}
createServer((req, res) => {
if (req.method !== "POST" || req.url !== "/webhooks/email") return res.writeHead(404).end();
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const body = Buffer.concat(chunks); // the raw body: parsing and re-encoding the JSON would break the signature
if (!verify(body, req.headers)) return res.writeHead(400).end("invalid signature");
const event = JSON.parse(body);
if (event.type === "email.received") {
const email = event.data;
// Save it here. Use req.headers["webhook-id"] to skip an event you've already stored (it's sent again on retries).
console.log(`${email.from?.address}: ${email.subject} (${email.attachments.length} attachments)`);
}
res.writeHead(200).end("ok");
});
}).listen(PORT, () => console.log(`Listening on http://localhost:${PORT}/webhooks/email`));
# A complete GhostParse webhook endpoint in Python, with no dependencies.
# Run: GHOSTPARSE_WEBHOOK_SECRET=whsec_... python3 server.py (Python 3.8+)
import base64, hashlib, hmac, json, os, time
from http.server import BaseHTTPRequestHandler, HTTPServer
SECRET = os.environ["GHOSTPARSE_WEBHOOK_SECRET"] # whsec_... from Dashboard -> Inbound webhook
PORT = int(os.environ.get("PORT", "3000"))
TOLERANCE_SECONDS = 5 * 60
def verify(body: bytes, headers) -> bool:
"""Standard Webhooks: base64 HMAC-SHA256 of "<webhook-id>.<webhook-timestamp>.<raw body>"."""
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
signatures = headers.get("webhook-signature")
if not (msg_id and timestamp and signatures):
return False
try:
if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS: # a replay, or a wrong clock
return False
except ValueError:
return False
key = base64.b64decode(SECRET[len("whsec_"):] if SECRET.startswith("whsec_") else SECRET)
expected = base64.b64encode(hmac.new(key, f"{msg_id}.{timestamp}.".encode() + body, hashlib.sha256).digest()).decode()
# Several space-separated signatures while you rotate your secret: accept any that matches.
return any(hmac.compare_digest(s.split(",", 1)[-1], expected) for s in signatures.split(" "))
class Handler(BaseHTTPRequestHandler):
def do_POST(self):
if self.path != "/webhooks/email":
return self.answer(404, "")
body = self.rfile.read(int(self.headers.get("content-length", 0))) # the raw body, before any JSON parsing
if not verify(body, self.headers):
return self.answer(400, "invalid signature")
event = json.loads(body)
if event["type"] == "email.received":
email = event["data"]
# Save it here. Use self.headers["webhook-id"] to skip an event you've already stored (it's sent again on retries).
print(f"{(email.get('from') or {}).get('address')}: {email['subject']} ({len(email['attachments'])} attachments)", flush=True)
self.answer(200, "ok")
def answer(self, status, text):
self.send_response(status)
self.end_headers()
self.wfile.write(text.encode())
print(f"Listening on http://localhost:{PORT}/webhooks/email", flush=True)
HTTPServer(("", PORT), Handler).serve_forever()
// A complete GhostParse webhook endpoint in Go, with no dependencies beyond the standard library.
// Run: GHOSTPARSE_WEBHOOK_SECRET=whsec_... go run main.go
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/json"
"io"
"log"
"math"
"net/http"
"os"
"strconv"
"strings"
"time"
)
const toleranceSeconds = 5 * 60
// verify checks a Standard Webhooks signature: base64 HMAC-SHA256 of "<webhook-id>.<webhook-timestamp>.<raw body>".
func verify(body []byte, h http.Header, secret string) bool {
id, timestamp, signatures := h.Get("webhook-id"), h.Get("webhook-timestamp"), h.Get("webhook-signature")
ts, err := strconv.ParseInt(timestamp, 10, 64)
if id == "" || err != nil || signatures == "" {
return false
}
if math.Abs(float64(time.Now().Unix()-ts)) > toleranceSeconds { // a replay, or a wrong clock
return false
}
key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
if err != nil {
return false
}
mac := hmac.New(sha256.New, key)
mac.Write([]byte(id + "." + timestamp + "."))
mac.Write(body)
expected := mac.Sum(nil)
// Several space-separated signatures while you rotate your secret: accept any that matches.
for _, s := range strings.Split(signatures, " ") {
sig, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(s, "v1,"))
if err == nil && hmac.Equal(sig, expected) {
return true
}
}
return false
}
func main() {
secret := os.Getenv("GHOSTPARSE_WEBHOOK_SECRET") // whsec_... from Dashboard -> Inbound webhook
port := os.Getenv("PORT")
if port == "" {
port = "3000"
}
http.HandleFunc("/webhooks/email", func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.NotFound(w, r)
return
}
body, err := io.ReadAll(r.Body) // the raw body: parsing and re-encoding the JSON would break the signature
if err != nil || !verify(body, r.Header, secret) {
http.Error(w, "invalid signature", http.StatusBadRequest)
return
}
var event struct {
Type string `json:"type"`
Data struct {
From *struct {
Address string `json:"address"`
} `json:"from"`
Subject string `json:"subject"`
Attachments []json.RawMessage `json:"attachments"`
} `json:"data"`
}
if err := json.Unmarshal(body, &event); err != nil {
http.Error(w, "bad JSON", http.StatusBadRequest)
return
}
if event.Type == "email.received" {
from := ""
if event.Data.From != nil {
from = event.Data.From.Address
}
// Save it here. Use r.Header.Get("webhook-id") to skip an event you've already stored (it's sent again on retries).
log.Printf("%s: %s (%d attachments)", from, event.Data.Subject, len(event.Data.Attachments))
}
w.Write([]byte("ok"))
})
log.Printf("Listening on http://localhost:%s/webhooks/email", port)
log.Fatal(http.ListenAndServe(":"+port, nil))
}
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.
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.
Libraries for your stack
npm i @wildye/email-parser
Pythonpip install wildye-email-parser
PHPcomposer require wildye/email-parser
Laravelcomposer require wildye/email-parser-laravel
Rubygem install wildye-email-parser
Gogo get github.com/dwildman86/emailParser/sdk/go
CLInpx @wildye/email-parser-cli listen
OpenAPI 3.1/openapi.json
Tutorials
All tutorials →Save email data to a database, encrypted
Parse invoices into fields and store them with AES-256-GCM field-level encryption. Node.js and Python.
Read →Test webhooks on localhost
Simulated and real email on your laptop, before you have a domain.
Read →Emails as typed Pydantic objects
Your model or JSON Schema decides the shape; every answer is checked before delivery.
Read →Self-hosted webmail
A free PHP and MySQL webmail built on the API and webhooks, with mail encrypted in your own database. Download it, or read it as a working example.
Download →Attachments to your own bucket
S3, R2, B2 or Google Cloud Storage: small webhooks with download links instead of base64.
Docs →