API documentation
Send transactional email with one API call, and receive inbound email as signed JSON. Free, transactional only, and we never store your email.
Overview
| Base URL | https://ghostparse.com |
|---|---|
| Format | JSON request and response bodies, UTF-8. Send Content-Type: application/json. |
| Auth | Authorization: Bearer <API key> |
| Sending | POST /v1/emails |
| Receiving | We POST each inbound email to your webhook URL as signed JSON. |
Quick start
- Create a free account and verify your email address.
- In Domains, add your domain and publish the SPF, DKIM and DMARC records shown (plus MX if you want to receive mail). Click Verify.
- Under that domain's Email addresses, add the addresses you'll use, e.g.
orderswith Send on andsupportwith Receive on. Only listed addresses can send or receive. - In API keys, create a key. It's shown once: store it as a secret.
- Send your first email:
curl https://ghostparse.com/v1/emails \
-H "Authorization: Bearer $EMAIL_PARSER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "orders@yourapp.com",
"to": "customer@example.com",
"subject": "Your receipt",
"text": "Thanks for your order."
}'
// composer require wildye/email-parser
use Wildye\EmailParser\Client;
use Wildye\EmailParser\Email;
$client = new Client(getenv('EMAIL_PARSER_API_KEY'), ['base_url' => 'https://ghostparse.com']);
$sent = $client->send(
Email::create()
->from('orders@yourapp.com')
->to('customer@example.com')
->subject('Your receipt')
->text('Thanks for your order.')
);
echo $sent->id;
const res = await fetch("https://ghostparse.com/v1/emails", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.EMAIL_PARSER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: "orders@yourapp.com",
to: "customer@example.com",
subject: "Your receipt",
text: "Thanks for your order.",
}),
});
const sent = await res.json();
if (!res.ok) throw new Error(sent.message);
console.log(sent.id);
import os, requests
res = requests.post(
"https://ghostparse.com/v1/emails",
headers={"Authorization": f"Bearer {os.environ['EMAIL_PARSER_API_KEY']}"},
json={
"from": "orders@yourapp.com",
"to": "customer@example.com",
"subject": "Your receipt",
"text": "Thanks for your order.",
},
timeout=30,
)
res.raise_for_status()
print(res.json()["id"])
Authentication
Every API request needs an API key in the Authorization header:
Authorization: Bearer ek_live_…
Create and revoke keys in the dashboard under API keys (developer role or above). Keys are shown
once and stored only as a hash, so we can't show them again. Use one key per environment or service, keep them
server-side, and revoke any key that may have leaked. A missing, wrong or revoked key returns
401.
Each key has permissions, chosen when it's created: send (send email),
domains (Domains API and webhook settings), integrations
(Make, n8n, the WordPress plugin, destinations and routing rules) and, for resellers,
accounts (sub-accounts). Calling an endpoint without its permission returns
403 insufficient_scope.
Send an email
POST /v1/emails
Sends one transactional email, DKIM-signed with your domain's key. The call returns once the message has been handed to our outbound mail server.
POST /v1/emails
Authorization: Bearer ek_live_…
Content-Type: application/json
Idempotency-Key: order-1042-receipt
{
"from": { "address": "orders@yourapp.com", "name": "Your App" },
"to": [{ "address": "sam@example.com", "name": "Sam Customer" }],
"reply_to": "support@yourapp.com",
"subject": "Your receipt for order #1042",
"html": "<p>Thanks for your order.</p>",
"text": "Thanks for your order.",
"headers": { "X-Order-Id": "1042" },
"attachments": [
{ "filename": "receipt-1042.pdf", "content": "JVBERi0xLjQK…", "content_type": "application/pdf" }
]
}
Response 200
{
"id": "out_2f154a2f-34b4-475f-b349-202cf97a2adc",
"message_id": "<out_2f154a2f-34b4-475f-b349-202cf97a2adc@yourapp.com>",
"from": { "address": "orders@yourapp.com", "name": "Your App" },
"thread_id": "thr_2c9e0d1f5a7b3e4c6d8f0a1b",
"accepted": ["sam@example.com"],
"rejected": [],
"sent_at": "2026-10-02T09:15:16.835Z"
}
| Field | Description |
|---|---|
id | Our ID for this send. Store it; we don't keep a copy of the email. |
message_id | The Message-ID header. Replies to this email reference it in In-Reply-To, so you can match them to the original. |
from | The From the email was sent with: its address and the name used (yours, or the address's saved From name; null when none). |
accepted / rejected | Recipients the outbound server accepted or refused. |
thread_id | The conversation this email starts (or continues): replies arrive with the same data.thread_id. |
sent_at | ISO 8601 timestamp. |
Request fields
An address is either a string ("sam@example.com") or an object
({"address": "sam@example.com", "name": "Sam"}). Recipient fields accept one address or an array.
| Field | Type | Notes |
|---|---|---|
from required | address | Must be on a verified domain and listed under that domain's Email addresses with Send on. Sub-addresses (orders+eu@) count as their base address. |
from_name | string | The From name: Jane Smith in Jane Smith <jane@yourapp.com>. Up to 200 characters, no line breaks. Overrides a name in from; without either, the address's saved From name is used. |
to, cc, bcc | address or address[] | At least one recipient across the three; at most 50 in total. |
reply_to | address or address[] | |
subject required | string | 1–998 characters. |
text | string | At least one of text or html. Sending both is recommended. |
html | string | |
headers | object of strings | Custom headers, e.g. {"X-Order-Id": "1042"}. Not allowed: From, To, Cc, Bcc, Reply-To, Subject, Message-ID, Date, Content-Type, Content-Transfer-Encoding, MIME-Version, the bulk-mail headers Precedence, List-Id, List-Unsubscribe, List-Unsubscribe-Post, any
Content-* or Resent-* header, and headers only mail servers add or that would claim another sender:
Sender, Return-Path, Received, Received-SPF, DKIM-Signature,
Authentication-Results, ARC-*, Delivered-To, X-Original-To, Feedback-ID.
Names are letters, digits and - (no spaces or colons); values up to 2,000 characters. |
attachments | attachment[] | See Attachments. |
in_reply_to | string | The Message-ID you're replying to. See threading. |
references | string[] | The thread's earlier Message-IDs. |
Attachments & inline images
| Field | Type | Notes |
|---|---|---|
filename required | string | Shown to the recipient. |
content required | string | File bytes, base64-encoded. |
content_type | string | e.g. application/pdf. Guessed from the filename if omitted. |
content_id | string | Makes it an inline image: reference it in your HTML as <img src="cid:logo@yourapp">. |
An email can be up to 25 MB in total, measured before base64 encoding (the JSON request itself may be about a third larger). Many mailbox providers reject messages over 20–25 MB, so keep attachments small or send a download link instead.
Replies & threading
To make an email part of an existing conversation, set in_reply_to to the Message-ID you're
replying to and references to the thread's IDs. When a customer replies to an email you sent, the inbound
webhook's data.in_reply_to contains your original message_id, and its data.thread_id
equals the thread_id returned when you sent, so you can match it to the conversation in your database
(see conversations).
Tip: give each conversation its own reply address using a sub-address, e.g. Reply-To: support+ticket-42@yourapp.com.
Mail to it is delivered as support@yourapp.com, and the full address is in data.envelope.rcpt_to.
Signatures & disclaimers
Each sending address can have a From name, a position and a signature, and each domain a disclaimer. Set them on the domain's page in the dashboard (Signatures & disclaimer), or with the API. They're added to every email sent from that address:
PATCH /v1/domains/{id}/addresses/{addressId}
{ "display_name": "Jane Smith", "position": "Customer Support Lead",
"signature": "Acme Ltd\n07700 900123 · https://acme.example" }
PATCH /v1/domains/{id}
{ "disclaimer": "This email is confidential and meant only for the addressee. Acme Ltd, registered in England and Wales no. 01234567." }
Then a send's text ends like this (the HTML version is laid out the same, with links):
See you Saturday. -- Jane Smith Customer Support Lead Acme Ltd 07700 900123 · https://acme.example This email is confidential and meant only for the addressee. Acme Ltd, registered in England and Wales no. 01234567.
- From name: used when the request's
fromhas no name. A name in the request wins. - Signature: added after the standard
--line, which mail apps recognise. It's only added when there's a position or signature text; a From name alone just names the sender. Send"signature": falseto leave it out of one email. - Disclaimer: always added last, to every email from the domain.
- Plain text only, up to 100 characters for the name and position, 2,000 for the signature and 4,000 for the
disclaimer. In the HTML version it's escaped (never treated as HTML), and web and email addresses become links. Send
nullor""to clear a field. - With only
htmlin a request, the generated text part includes them too.
Idempotency
Network timeouts happen. To retry a send without risking a duplicate email, send an Idempotency-Key
header. Use a value tied to the business event, such as order-1042-receipt:
Idempotency-Key: order-1042-receipt
- Repeating a request with the same key within 24 hours returns the original result instead of sending again. (Keys are remembered in memory, so a platform restart forgets them.)
- If a send failed, the key is released, so retrying with it sends normally.
- Keys are scoped to your account. The PHP library adds a key to every send automatically.
Deliverability: bounces & suppressions
Gmail, Yahoo, Outlook, iCloud and Proton decide whether your mail reaches the inbox partly on authentication and partly on how often it bounces or is reported as spam. GhostParse handles both for you:
- Authenticated: every email is DKIM-signed with your domain's key (aligned with your From address, so it passes DMARC), sent over TLS, from servers with matching reverse DNS, over IPv4 and IPv6.
- Bounces come to us: each email's return path is
bounces+<id>@mx.ghostparse.com, so bounces are matched to the exact email instead of landing in your From mailbox. - Suppressed automatically: an address that hard-bounces (it doesn't exist) or whose owner
marks your mail as spam is added to your suppression list. Later emails skip it and list it in
suppressed. If every recipient is suppressed, the send fails with422 recipients_suppressed. - Told by webhook: your webhook receives
email.bouncedandemail.complainedevents, so you can flag the address in your own app. - A text part is added when you send HTML only, and a
Feedback-IDheader lets the platform track spam rates per account in Gmail Postmaster Tools.
{
"type": "email.bounced",
"data": {
"id": "out_5f0c8a2e-…",
"recipient": "gone@example.com",
"permanent": true,
"suppressed": true,
"status": "5.1.1",
"diagnostic": "550 5.1.1 The email account that you tried to reach does not exist"
}
}
Temporary failures (4.x.x) and permanent ones that say nothing about the address (a full mailbox,
a spam block) are reported with suppressed: false. email.complained carries
id, recipient, feedback_type and suppressed.
| Endpoint | Does |
|---|---|
GET /v1/suppressions | The addresses you no longer send to, newest first |
POST /v1/suppressions | Add one yourself: { "address": "…" } |
DELETE /v1/suppressions/{address} | Send to it again. Only do this if you're sure the address works now. |
BigCommerce order emails
Connect a BigCommerce store and GhostParse sends its order emails from your own verified domain, with templates you can edit: order confirmation, shipping confirmation (with carrier, tracking number and link), order cancelled and refund confirmation (off until you turn it on). There's no app to install: you give us an API token from your store, and we register its webhooks.
Connect a store
- In BigCommerce go to Settings → Store-level API accounts → Create API account. Name it, and set Orders: modify (to read orders and add replies to their staff notes) and Information & settings: read-only (for the store's name). Leave the rest as None, and save.
- BigCommerce shows the access token and the API path once (and downloads them as a file).
- On the dashboard's BigCommerce page, paste both and choose the address to send from. We check the token, register the store's webhooks, and show the store's emails.
- In BigCommerce, Marketing → Transactional emails: turn off its own order confirmation, shipped, cancelled and refunded emails, so customers get only ours.
| BigCommerce webhook | |
|---|---|
store/order/created | Order confirmation (once the order is past Incomplete; a checkout that finishes later sends it then) |
store/order/statusUpdated | Order cancelled, when the status changes to Cancelled |
store/shipment/created | Shipping confirmation, for what's in that shipment |
store/order/refund/created | Refund confirmation |
- Checked: our webhooks carry a secret header we set when registering them, and say which store they're from; anything else is refused. BigCommerce's webhooks only name the order, so every email is written from the order as BigCommerce's API returns it, never from the webhook.
- Once: each confirmation, cancellation, shipment and refund sends one email, however often BigCommerce
delivers the webhook. If our mail server can't take it we answer
503, and BigCommerce retries. - Nothing kept: only the order number, the event and the result, for 30 days. The token is stored encrypted.
- A token that stops working (deleted in BigCommerce) shows on the store's page: paste a new one in its settings.
The store inbox, saved messages and the Autopilot work for BigCommerce stores too. Replies are added to the order's staff notes (BigCommerce has no order tags), and you can email the customer of any order from the store's page by its order number. Templates can use {{order.name}}, {{customer.first_name}}, {{tracking.number}}, {{items_table}} and the other order values (listed in the template editor). BigCommerce has no carrier updates, so there are no out-for-delivery or delivered emails.
API
With a key that has the integrations permission, under /v1/bigcommerce/stores: list, connect,
get, change, disconnect, a new webhook URL, events, and each template (change, preview, send a test). See the API reference.
Connect with store (the API path or the store's address), api_token and from_address;
change the token with PATCH and api_token.
Set up inbound email
- Add and verify your domain (the DKIM record proves you own it), and publish the MX record shown
in the dashboard. Use a subdomain such as
inbound.yourapp.comif your main domain's mail is handled elsewhere. - Under Email addresses, add each address that should receive mail with Receive on. Mail to
any other address is refused with
550 No such recipient. - Turn on Inbound for the domain.
- In Inbound webhook, set your
https://webhook URL and copy the signing secret.
Each accepted message is parsed and POSTed to your URL as an email.received event. Bulk and mailing-list
mail is refused by default; you can change that on the Inbound webhook page.
Webhook payload
POST https://yourapp.com/webhooks/email
Content-Type: application/json
User-Agent: email-parser-api/0.1
webhook-id: evt_6c1d…
webhook-timestamp: 1790932497
webhook-signature: v1,unqzZ64edPDGcZVcnf3zGnmbc6EQ6DznDhh3jhZXPIE=
{
"id": "evt_6c1d…",
"type": "email.received",
"timestamp": "2026-10-02T09:00:00.000Z",
"created_at": "2026-10-02T09:00:00.000Z",
"tenant_id": "acct_…",
"data": {
"id": "inb_…",
"message_id": "<reply-1@example.com>",
"envelope": {
"mail_from": "jane@example.com",
"rcpt_to": ["support+ticket-42@yourapp.com"],
"client_ip": "198.51.100.7",
"helo": "mail.example.com"
},
"from": { "address": "jane@example.com", "name": "Jane Doe" },
"to": [{ "address": "support+ticket-42@yourapp.com", "name": "" }],
"cc": [],
"reply_to": [],
"subject": "Re: Order #1042",
"date": "2026-10-01T10:00:00.000Z",
"in_reply_to": "<out_2f15…@yourapp.com>",
"references": ["<out_2f15…@yourapp.com>"],
"thread_id": "thr_836de45f552c568b8e3b9810",
"thread": { "id": "thr_836de45f552c568b8e3b9810", "root_message_id": "<out_2f15…@yourapp.com>", "position": 1, "is_reply": true, "method": "references", "tag": null },
"text": "Where is my order?\n\nOn Tue, 29 Sep 2026, Your App <support@yourapp.com> wrote:\n> Your order has shipped",
"reply_text": "Where is my order?",
"html": "<p>Where is my order?</p>…",
"headers": { "subject": "Re: Order #1042", "x-mailer": "…" },
"attachments": [
{
"filename": "photo.jpg",
"content_type": "image/jpeg",
"size": 48213,
"content_id": null,
"disposition": "attachment",
"content": "/9j/4AAQSkZJRg…",
"sha256": "9f2c…"
}
],
"authentication": {
"verdict": "pass",
"spf": { "result": "pass", "domain": "example.com", "client_ip": "198.51.100.7" },
"dkim": [{ "result": "pass", "domain": "example.com", "selector": "s1", "aligned": true }],
"dmarc": { "result": "pass", "policy": "reject", "domain": "example.com" },
"arc": { "result": "none" },
"header": "Authentication-Results: mx.ghostparse.com; …"
},
"auto_submitted": null,
"bounce": null,
"calendar": [],
"recipients": [
{ "address": "support+ticket-42@yourapp.com", "base_address": "support@yourapp.com", "tag": "ticket-42", "tag_verified": null }
],
"spam": { "score": 1.2, "action": "no action", "symbols": ["DKIM_VALID", "…"] },
"virus": { "infected": false, "names": [] },
"extracted": {
"parser_id": "prs_…", "parser": "Orders", "method": "rules", "error": null,
"fields": { "order_number": 1042, "total": 42.5, "tracking": "TRK-88213" }
},
"size": 66104,
"received_at": "2026-10-02T09:00:00.000Z"
}
}
| Field | Notes |
|---|---|
type | email.received, or webhook.test for test events, or email.bounced / email.complained for mail you sent. Ignore types you don't recognise. |
tenant_id | Your account ID. |
data.thread_id, thread | The conversation: the same for the first message and every reply. See below. |
data.message_id | The sender's Message-ID. To de-duplicate deliveries, use the webhook-id header instead: see handling duplicates. |
data.envelope.rcpt_to | The address(es) at your domain this delivery is for, as the sender wrote them (including any +tag). Can differ from the To header, e.g. for BCC. |
data.from, to, cc, reply_to | From the message headers. from may be null. |
data.text, html | Either may be null. |
data.reply_text | Just the new part of a reply: quoted history (On … wrote:, > lines, Outlook header blocks, in several languages) and the signature removed. Best effort; text always has everything. |
data.recipients | Each envelope recipient split up: base_address (the listed address it matched), tag (after the +) and tag_verified for signed reply addresses. |
data.auto_submitted, bounce | auto_reply, bounce, auto_generated or null. See below. |
data.calendar | Meeting invites found in the email. See below. |
data.spam, virus | Scan results when this platform runs spam/virus scanning, else null. See below. |
data.extracted | The fields your parser pulled out, or null when the address has none. |
data.size | Size of the original message in bytes. |
data.headers | All headers, names lower-cased; repeated headers are joined with a newline. |
data.attachments[].content | Base64 (or null, depending on your attachment setting). Inline images have a content_id. sha256 is the file's hash. Filenames come from the sender: sanitise them before saving. |
data.authentication | Our SPF, DKIM and DMARC checks. See below. |
Addresses & routing
Each domain has a list of addresses that receive mail. Anything else is refused at the door with
550 No such recipient, so spam to random addresses never reaches you.
| Entry | Receives |
|---|---|
support | support@, plus sub-addresses like support+ticket-42@ (the tag is in recipients[].tag) |
ticket-* | Any address matching the pattern: ticket-1042@, ticket-abc@… Handy when your app makes an address per order or user. |
* | Catch-all: every address on the domain. Expect more spam. |
Exact entries win over patterns, and longer patterns over shorter ones. Patterns can only receive.
Where mail goes: an address can have its own webhook URL (e.g. invoices@ to your
accounting service), otherwise the domain's, otherwise your account's. Mail to several addresses with different
webhooks is delivered to each separately, each seeing only its own recipients. All webhooks are signed with your
account's secret.
A domain can also have its own size limit (up to 25 MB): bigger messages are refused.
Conversations (thread_id)
Every email arrives with a thread_id that is the same for the first message of a conversation and
every reply to it, so you don't have to rebuild threads from email headers yourself. Store it with your ticket,
order or chat, and look it up when the next email arrives.
"thread_id": "thr_836de45f552c568b8e3b9810",
"thread": {
"id": "thr_836de45f552c568b8e3b9810",
"root_message_id": "<out_2f15…@yourapp.com>", // the conversation's first email
"position": 1, // 0 = first message
"is_reply": true,
"method": "references",
"tag": "t42" // from a verified signed reply address, else null
}
- How it's worked out: from
References(its first entry is the conversation's first email, and mail clients keep it), elseIn-Reply-To, else Outlook'sThread-Index, else the email's ownMessage-ID(it starts a new conversation). Nothing is stored on our side. - Emails you send: the thread_id is
thr_+ the first 24 hex characters of the SHA-256 of the Message-ID without its angle brackets (domain part in lower case). Every SDK has a helper (threadIdFor,thread_id_for,Thread::idFor), so you can save it when you send and match the first reply.POST /v1/emailsreturns it asthread_id. - Signed reply addresses: when the email came to a signed reply address,
thread.tagis your tag (for example your ticket ID). That works even when the sender's mail client drops the headers, so use both if you can. - A reply from a client that strips
ReferencesandIn-Reply-Tostarts a new thread_id; it still carries your signed tag if you used a reply address.
Auto-replies & bounces
If your app answers inbound email automatically, it must not answer robots, or two auto-responders email each
other forever. Every email says what it is in data.auto_submitted:
| Value | Means | Detected by |
|---|---|---|
auto_reply | Out-of-office or other automatic reply | Auto-Submitted: auto-replied, X-Autoreply, Precedence: auto_reply, or subjects like "Automatic reply:" / "Out of Office" |
bounce | A delivery failure report about an email sent from your address | A delivery-status report, or an empty envelope sender from MAILER-DAEMON / postmaster |
auto_generated | Other machine-sent mail | Auto-Submitted: auto-generated |
null | Sent by a person, as far as we can tell |
"auto_submitted": "bounce",
"bounce": {
"recipient": "gone@example.com",
"action": "failed",
"status": "5.1.1",
"diagnostic": "550 5.1.1 User unknown",
"original_message_id": "<order-42@yourapp.com>"
}
Use bounce.original_message_id to find the email that failed and status (5.x.x permanent,
4.x.x temporary) to decide whether to stop emailing that address. Or switch on Drop out-of-office replies,
bounces and other automatic mail on the Inbound webhook page: we accept them (so the sender doesn't retry)
but don't deliver them, and the delivery log shows them as dropped.
Calendar invites
Meeting invites, updates, cancellations and RSVPs (iCalendar .ics parts) are read for you:
"calendar": [{
"method": "REQUEST",
"uid": "abc-123@example.com",
"sequence": 2,
"status": "CONFIRMED",
"summary": "Kick-off",
"description": "Agenda…",
"location": "Room 4",
"start": "2026-10-05T09:00:00",
"end": "2026-10-05T10:00:00",
"timezone": "Europe/London",
"all_day": false,
"recurrence": null,
"organizer": { "email": "jane@example.com", "name": "Jane Doe" },
"attendees": [{ "email": "support@yourapp.com", "name": "Support", "status": "NEEDS-ACTION", "role": "REQ-PARTICIPANT" }]
}]
method is REQUEST for a new or updated invite (higher sequence = newer),
CANCEL for a cancellation and REPLY for someone's RSVP. Times ending in Z are UTC;
others are local to timezone; all-day events have just a date. The .ics file is still in
attachments.
Attachments & the raw message
Choose how attachments reach you on the Inbound webhook page:
| Setting | What you receive |
|---|---|
| Inside the JSON (default) | application/json; each attachment's content is base64. |
| As separate files | multipart/form-data: a part named event holding the JSON (attachment content is null and part names its file part), plus one file part per attachment: attachment_0, attachment_1… About 25% smaller, and frameworks hand you the files directly. |
| Leave them out | JSON with names, types, sizes and hashes only (content is null). |
| Upload to your bucket | JSON with each attachment in your own S3-compatible bucket: content is null and storage has its key and a download link. Small webhooks whatever the attachments' size. See Attachment storage. |
Signatures for multipart: the signature covers the event part's
text instead of the whole body. Check each file against its
sha256 in the event, and the files are covered too. This also works in PHP, where
php://input is empty for multipart requests:
// Webhook::fromGlobals() reads $_POST['event'] and $_FILES for multipart requests.
$event = Webhook::fromGlobals($secret);
foreach ($event->email()->attachments as $a) {
$bytes = $a->content(); // the uploaded file, checked against its signed sha256
}
Include the original message: adds the complete .eml: base64 in data.raw,
or as a file part named raw (with data.raw_part: "raw") in multipart mode. Useful for
archiving or your own parsing. Mind the size: up to 25 MB plus encoding. With attachment storage,
it's uploaded to your bucket as message.eml instead, with its link in data.raw_storage.
Attachment storage (your own bucket)
Base64 makes a 10 MB PDF a 13.5 MB webhook. Instead, we can upload each attachment to your bucket as the email arrives and send you its details and a download link. Your webhook stays a few kilobytes, your app downloads only what it needs, and the files live in storage you control (we keep no copy).
Works with anything that speaks the S3 API:
| Service | Endpoint | Region |
|---|---|---|
| Amazon S3 | (not needed) | Your bucket's, e.g. eu-west-2 |
| Cloudflare R2 | https://<account id>.r2.cloudflarestorage.com | auto |
| Backblaze B2 | https://s3.<region>.backblazeb2.com | e.g. us-west-004 |
| Google Cloud Storage | https://storage.googleapis.com (with an HMAC key) | auto |
| DigitalOcean Spaces | https://<region>.digitaloceanspaces.com | e.g. nyc3 |
| Wasabi, MinIO, others | The service's S3 endpoint | As the service says |
- Create a bucket, and an access key that can write to it and read from it. On AWS, this policy is enough:
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["s3:PutObject", "s3:GetObject"], "Resource": "arn:aws:s3:::yourcompany-email/email/*" }] } - On the Inbound webhook page, under Attachment storage, enter the bucket and key, and save.
We test it straight away: a small file,
ghostparse-test.txt, is uploaded and its link opened. - Under Attachments, choose Upload to your bucket.
Each attachment then arrives like this:
"attachments": [{
"filename": "invoice-INV-20977.pdf",
"content_type": "application/pdf",
"size": 482113,
"sha256": "9f2c…",
"content": null,
"storage": {
"provider": "aws",
"bucket": "yourcompany-email",
"key": "email/2026/10/16/em_3kq9x2/1-invoice-INV-20977.pdf",
"url": "https://yourcompany-email.s3.eu-west-2.amazonaws.com/email/2026/10/16/em_3kq9x2/1-invoice-INV-20977.pdf?X-Amz-Algorithm=…",
"url_expires_at": "2026-10-23T09:12:04Z"
}
}]
- Links: for a private bucket,
urlis a signed link that works for up to 7 days (you choose, from 1 hour). Download the file, or keep thekeyand make your own links later. If you serve the bucket publicly (a public bucket or your CDN), give us its address and links are permanent (url_expires_atisnull). - Keys:
<folder>/<date>/<email id>/<n>-<file name>. The same email delivered twice uses the same keys, so retries never duplicate files. - Safe to open: files are stored with
Content-Disposition: attachment, so an HTML or SVG attachment downloads instead of running in a browser. Checksha256if you need to be sure a file is unchanged. - If the bucket can't be reached (or refuses the upload), the email isn't delivered without its attachments: it's held and the sender's server tries again, the delivery log shows why, and the Inbound webhook page shows the error until an upload works.
- Everywhere: REST hooks (Make, n8n) and other destinations get the same links. Set up
by API with
PUT /v1/webhook/storage(OpenAPI); the secret key is stored encrypted and never returned. - Retention is yours: add a lifecycle rule to the bucket (e.g. delete after 90 days) if you don't need the files forever.
Parsers & extracted data
A parser pulls the values you care about out of each email (an order number, a total, a tracking code) and
adds them to the webhook as data.extracted, so your code doesn't have to search the text. Create
parsers on the dashboard's Parsers page or with the API (/v1/parsers), and choose one per
address, for a whole domain, or for the instant address. Three kinds: rules, AI
(fields described in words) and your own JSON Schema.
"extracted": {
"parser_id": "prs_…",
"parser": "Orders",
"method": "rules",
"fields": { "order_number": 1042, "total": 42.5, "tracking": "TRK-88213", "gift": null },
"error": null
}
Each field has a name (order_number) and a type: text, number, whole number, yes/no, date
(YYYY-MM-DD) or list. A field the email doesn't contain is null.
Rules parsers
| Rule | Example | Gives |
|---|---|---|
| Text after | Order number on "Order number: 1042" | 1042 (the rest of the line, after any : # or -) |
| Text between | Tracking ( and ) | whatever is between them |
| Regular expression | \b(TRK-\d+) | the first group in brackets, else the whole match |
Rules look in the subject, the body, both, or the sender's address, and ignore upper/lower case. They run on our servers in a time-limited sandbox: a rule that takes too long reports an error instead of holding up mail.
AI parsers
Describe each field in plain words ("The order number, like A-1042", "Is the customer asking for a refund?") and Claude, Anthropic's AI model, reads the email and fills them in. It understands emails rules can't: different layouts, free-text requests, tables, other languages. The answer always matches your fields and types.
- Opt-in: an owner or admin turns AI extraction on for the account on the Parsers page. AI parsers send each email's subject, sender, recipients and text to Anthropic; rules parsers send nothing anywhere.
- Limit: 200 AI extractions per account per day (the dashboard shows today's use).
Very long emails are read up to a limit, and then
truncated: truesays so. - Optional instructions apply to the whole parser ("Totals are in GBP").
Your own JSON Schema (Pydantic, Zod)
Already have a model for the data? Give a parser its JSON Schema and every email arrives as an object in that exact shape, nested objects and lists included, checked against the schema before it's delivered.
class LineItem(BaseModel):
sku: str = Field(max_length=12)
qty: int = Field(ge=1)
class Invoice(BaseModel):
invoice_number: str = Field(pattern=r"^INV-\d+$")
total: float = Field(ge=0)
due_date: date | None = None
lines: list[LineItem]
requests.post("https://ghostparse.com/v1/parsers", headers={"Authorization": f"Bearer {KEY}"}, json={
"name": "Invoices", "mode": "schema", "schema": Invoice.model_json_schema(),
})
const Invoice = z.object({
invoice_number: z.string().regex(/^INV-\d+$/),
total: z.number().min(0),
due_date: z.iso.date().nullable(),
lines: z.array(z.object({ sku: z.string().max(12), qty: z.number().int().min(1) })),
});
await fetch("https://ghostparse.com/v1/parsers", {
method: "POST", headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ name: "Invoices", mode: "schema", schema: z.toJSONSchema(Invoice) }),
});
curl https://ghostparse.com/v1/parsers -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"name":"Invoices","mode":"schema","schema":{"type":"object","properties":{"invoice_number":{"type":"string"}},"required":["invoice_number"]}}'
Then use it for an address, or for a whole domain with PATCH /v1/domains/{id} and
{"parser_id": "prs_…"} (addresses with their own parser keep it). Each email then carries:
"extracted": {
"parser_id": "prs_…", "parser": "Invoices", "method": "schema",
"schema_version": 3, "schema_sha256": "9f2c…",
"valid": true, "errors": [], "error": null,
"data": { "invoice_number": "INV-20977", "total": 312.0, "due_date": "2026-11-14", "lines": [{ "sku": "A1", "qty": 2 }] },
"fields": { "invoice_number": "INV-20977", "total": 312.0, "due_date": "2026-11-14" }
}
- Verified: Claude answers in your schema's shape, then we check the answer against your
whole schema (types, required properties, enums, formats, lengths, ranges, patterns, item counts). If it
doesn't pass, Claude gets one more try with the reasons.
valid: truemeans it passed every check. - Never held back: an answer that still doesn't pass is delivered with
valid: falseanderrors(e.g./lines/0/qty must be >= 1), and so is an email the AI couldn't read (data: null). Send those somewhere else with a routing rule, or checkvalidin your code. - Missing values: say what may be missing. An optional property (
date | None = None) comes backnullor is left out; a required one that can't be null forces a value, so we warn you about those when you save the schema. - Versions: every change to the schema is a new
schema_version; earlier ones are kept (GET /v1/parsers/{id}/versions).schema_sha256identifies the exact schema used. - Supported: objects, lists, nesting,
$defsreferences (as Pydantic writes them),enum,const, unions and the usual formats. Not supported: recursive types, objects with free-form keys (dict[str, …],Record), and references to other files. At most 64 KB, 300 properties and 8 levels deep. - Cost: one AI extraction per email, like an AI parser, including the retry. Try a schema with
POST /v1/parsers/{id}/testbefore you use it.
From the command line, push a Pydantic model (or a JSON Schema file) and try it on a real email:
email-parser schema push models.py:Invoice # creates "Invoice", or a new version of it email-parser schema test prs_… --eml invoice.eml # what data.extracted would be (uses the AI allowance)
In your webhook handler, the SDKs give you the answer as your own type, checked again on your side:
event = verify_webhook(body, request.headers, SECRET)
email = event.email
if email.extracted_valid:
invoice = email.extracted_as(Invoice) # an Invoice instance
save(invoice.invoice_number, invoice.total, invoice.lines)
else:
review_queue.add(email.subject, email.raw["extracted"]["errors"])
import { extractedAs, verifyWebhook } from "@wildye/email-parser";
const event = verifyWebhook(body, req.headers, SECRET);
const invoice = extractedAs(event.data, Invoice); // Invoice.parse(): typed, or throws
save(invoice.invoice_number, invoice.total, invoice.lines);
curl -X POST https://ghostparse.com/v1/parsers/prs_…/test -H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" -d '{"subject":"Invoice INV-20977","text":"Total: £312.00 …"}'
Walkthrough: Turn emails into typed Pydantic objects.
Ready-made parsers
Start from a parser for the email shops get every day, on the Parsers page: couriers (Royal Mail, Parcelforce, DPD, Evri, Yodel, DHL, UPS, FedEx, or any courier: tracking number, status, delivery date and where it was left), marketplace orders (Etsy, eBay, Amazon, TikTok Shop, OnBuy, Not On The High Street, or any shop: order number, items, buyer, delivery address, dispatch-by date), payments (PayPal, Stripe and others), suppliers (invoices, order confirmations and back-orders) and customers (contact forms, return requests, triage of any customer email, new reviews). Those matching email your account received in the last 30 days are suggested first. Each is copied into your account as an AI parser you can change.
Extraction never blocks mail: if it fails (a rule times out, the AI is unavailable or
today's limit is reached) the email is still delivered, with fields empty and the reason in
error. Use Try it on a parser's page to test it on pasted text.
SPF, DKIM & DMARC results
Every inbound message is checked, and the results are in data.authentication:
| Field | Values |
|---|---|
verdict | DMARC result for the From domain: pass, fail, none (no DMARC record), temperror, permerror. The best single answer to "is this really from who it says?" |
spf | { result, domain, client_ip }, or null if the sending IP wasn't available. |
dkim | One entry per signature: { result, domain, selector, aligned }. aligned means the signing domain matches the From domain. |
dmarc | { result, policy, domain }; policy is the sender's published policy (none, quarantine, reject). |
header | The Authentication-Results header we computed. |
By default, mail that fails DMARC when the sender publishes p=reject is refused and never reaches you.
You can turn that off on the Inbound webhook page and decide yourself. Trust data.authentication,
not Authentication-Results headers in data.headers, which come from the sender
(we remove any that claim to be ours).
Verify webhook signatures
Webhooks are signed with Standard Webhooks, so our SDKs and any Standard Webhooks library verify them. Each request has three headers:
webhook-id: evt_6c1d… (the event id) webhook-timestamp: 1790932497 (unix seconds) webhook-signature: v1,unqzZ64edPDGcZVcnf3zGnmbc6EQ6DznDhh3jhZXPIE=
The signature is the base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<raw body>,
keyed with the base64-decoded part of your signing secret after whsec_ (from the Inbound webhook page).
- Use the raw request body; don't parse and re-encode the JSON first.
- After you rotate the secret, there are two space-separated signatures for 24 hours (new secret first): accept the request if any matches.
- Reject the request if the timestamp is more than 5 minutes from your clock (replay protection).
- Respond
400if verification fails,2xxonce you've stored the event. - Skip events whose
webhook-idyou've already processed: see handling duplicates.
import express from "express";
import { verifyWebhook } from "@wildye/email-parser";
const app = express();
// The raw body: re-serialised JSON won't match the signature.
app.post("/webhooks/email", express.raw({ type: "application/json", limit: "40mb" }), (req, res) => {
let event;
try {
event = verifyWebhook(req.body, req.headers, process.env.EMAIL_PARSER_WEBHOOK_SECRET);
} catch {
return res.sendStatus(400);
}
if (event.type === "email.received") {
// event.data.thread_id, event.data.from, event.data.reply_text …
}
res.sendStatus(200);
});
from email_parser import verify_webhook, WebhookVerificationError
@app.post("/webhooks/email")
def email_webhook():
try:
event = verify_webhook(request.get_data(), request.headers, os.environ["EMAIL_PARSER_WEBHOOK_SECRET"])
except WebhookVerificationError:
return "", 400
if event.type == "email.received":
email = event.email # email.thread_id, email.from_address, email.reply_text …
return "", 200
use Wildye\EmailParser\Webhook;
use Wildye\EmailParser\Exception\SignatureVerificationException;
try {
$event = Webhook::fromGlobals(getenv('EMAIL_PARSER_WEBHOOK_SECRET'));
} catch (SignatureVerificationException $e) {
http_response_code(400);
exit;
}
if ($event->isEmailReceived()) {
$email = $event->email();
// $email->threadId, $email->from->address, $email->replyText, $email->attachments …
}
http_response_code(200);
// composer require wildye/email-parser-laravel
// .env: EMAIL_PARSER_WEBHOOK_SECRET=whsec_… Webhook URL: https://your-app/email-parser/webhook
use Wildye\EmailParser\Laravel\Events\InboundEmailReceived;
Event::listen(function (InboundEmailReceived $event) {
Ticket::firstOrCreate(['thread_id' => $event->email->threadId])
->addReply($event->email->replyText);
});
# gem "wildye-email-parser", require: "email_parser"
def create
event = EmailParser::Webhook.verify(request.raw_post, request.headers, ENV.fetch("EMAIL_PARSER_WEBHOOK_SECRET"))
Ticket.find_or_create_by!(thread_id: event.email.thread_id) if event.email_received?
head :ok
rescue EmailParser::WebhookVerificationError
head :bad_request
end
// go get github.com/dwildman86/emailParser/sdk/go
body, _ := io.ReadAll(r.Body)
event, err := emailparser.VerifyWebhook(body, r.Header, os.Getenv("EMAIL_PARSER_WEBHOOK_SECRET"))
if err != nil {
http.Error(w, "bad signature", http.StatusBadRequest)
return
}
if email, ok := event.Email(); ok {
_ = email.ThreadID // email.From.Address, email.ReplyText …
}
w.WriteHeader(http.StatusOK)
import crypto from "node:crypto";
// raw: the request body as a string; secret: "whsec_…"
function verify(raw, headers, secret) {
const id = headers["webhook-id"], ts = headers["webhook-timestamp"];
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = crypto.createHmac("sha256", key).update(`${id}.${ts}.${raw}`).digest("base64");
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
const valid = (headers["webhook-signature"] ?? "").split(" ").some((entry) => {
const sig = entry.slice("v1,".length);
return entry.startsWith("v1,") && sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
});
return fresh && valid;
}
Handling duplicates (idempotency)
Webhooks are delivered at least once, so occasionally the same event arrives twice: for example, your
endpoint stored it but timed out before replying, or a sending mail server delivered the email again after we
asked it to retry. The webhook-id header (the same as the event's id) is the same every
time the same event is delivered:
- email.received: the same email (byte for byte) to the same recipients and endpoint always has the
same
webhook-id, including when the sending server redelivers it hours later. Itsdata.idis stable too. - email.bounced and email.complained: the same report about the same recipient has the
same
webhook-id. - The signature and
webhook-timestampare fresh on every attempt, so the 5-minute check still blocks replays.
So: verify the signature, then record the webhook-id in the same database transaction as the email,
with a unique constraint. A duplicate fails the insert, and you return 200 without processing it again:
CREATE TABLE webhook_events ( id VARCHAR(64) PRIMARY KEY, -- the webhook-id header received_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ); -- for each verified webhook, in one transaction: INSERT INTO webhook_events (id) VALUES (?); -- duplicate key? already processed: commit nothing, respond 200 INSERT INTO emails (...) VALUES (...); COMMIT;
Keep ids for at least a week (sending servers retry for up to 5 days), then delete old rows.
The original signature format
Accounts created before Standard Webhooks support keep the format their endpoints already verify:
webhook-signature: t=<unix seconds>,v1=<hex>, the hex HMAC-SHA256 of
<t>.<raw body> keyed with the whole secret string. All our SDKs accept both formats, so
switching is safe once you use one. Switch on the Inbound webhook page, or with
PATCH /v1/webhook {"webhook_signature": "standard"}. A secret made before Standard Webhooks
support can't be used for it: rotate the secret first (the dashboard offers to do both together).
Multipart deliveries (attachments as separate files): the signature covers the
event form field instead of the whole body, and each file is covered by the sha256 listed in the
signed event. The SDKs check both.
A complete endpoint, with no SDK
Each of these is a whole webhook endpoint you can copy, run and change: it verifies the signature (with the rules above), then logs each email. They use only the language's standard library. The dashboard's Inbound webhook page has the same code, and the webhook inspector shows what we send.
<?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))
}
The webhook inspector
On the dashboard's Webhook inspector page, create a temporary URL and every request sent to it appears
there within seconds: method, headers and body, and whether our signature checks out with your secret. Send it a test
event, or use it as the webhook URL of a test address, a domain or a destination to see exactly what your app will
get. Choose the status it answers with (such as 500) to watch how we retry.
An inspector lasts two hours. It keeps its last 50 requests (the first 1 MB of each body) in memory only, never on disk, and they're gone when it expires or you delete it.
Delivery & retries
- Success is any
2xxresponse within 10 seconds. Respond quickly and do slow work (virus scanning, AI, notifications) in a background job. - Temporary failures (timeouts, network errors,
408,429,5xx) are retried up to 3 attempts in total with a short backoff. If they all fail, we tell the sending mail server to try again later. Mail servers keep retrying for hours to days, so a brief outage on your side doesn't lose email. - Other
4xxresponses (except 408 and 429) are permanent: the email is bounced back to the sender. Return400only for genuinely bad requests, such as a failed signature check. - Redirects aren't followed. Your URL must be public
https://; private and internal addresses are refused. - Duplicates are possible (e.g. your endpoint stored the email but timed out before replying). Make
your handler idempotent: skip events whose
webhook-idyou've already processed (how). - Backup URL: if you set one, it's tried before the sender is asked to retry. See below.
- Source IP addresses: webhooks come from 77.72.7.69, 2a03:2800:500::52f, if your firewall needs to allow them
(also at
/v1/meta). webhook-idis the eventid. It stays the same across our retries, backup URL attempts and the sending server's later redeliveries of the same email. The signature timestamp is fresh on every attempt.
Backup webhook URL
Set a second URL on the Inbound webhook page (or PATCH /v1/webhook
{"backup_webhook_url": "https://…"}). When your main webhook can't be reached, times out or returns
5xx after its 3 attempts, the same signed request goes to the backup before we ask the
sending server to retry. The email is delivered without waiting hours for a redelivery, and we still store nothing.
- A
4xxfrom the main webhook is its final answer: the backup isn't tried. - The delivery log shows these as delivered with a backup flag and the main webhook's error. A run of them triggers the usual "your webhook is failing" alert, saying mail is going to the backup.
- If both fail, the sender is asked to retry later, as before.
- Point it at a different server or region from the main one, e.g. a queue such as an AWS Lambda URL that only
stores the event for later. Use Test backup URL (or
POST /v1/webhooks/test{"target": "backup"}) to check it.
Delivery log & alerts
The dashboard's Delivery log shows what happened to each inbound email for 90 days: delivered (with your endpoint's status code, attempts and response time), retrying, failed, refused (unknown address, DMARC, sender rule, spam, virus, size) or dropped. It records the sender's domain, your recipient addresses and the Message-ID: never the content, subject or the sender's address. The same data is available over the API:
GET /v1/deliveries?status=rejected&limit=50
GET /v1/deliveries?message_id=%3Creply-1%40example.com%3E
GET /v1/deliveries?before=<next_before from the previous page>
{ "deliveries": [ { "id": 812, "status": "deferred", "reason": "Webhook responded 503", "recipients": ["support@yourapp.com"],
"sender_domain": "example.com", "message_id": "<reply-1@example.com>", "http_status": 503, "attempts": 3,
"duration_ms": 3120, "spam_score": 1.2, "flags": { "dmarc": "pass" }, "created_at": "…", … } ],
"next_before": 812 }
Alerts: account owners and admins get an email when the webhook has failed 3 times in a row (once per outage), another when it recovers, and one if the regular DNS check finds a domain's records gone. Turn them off on the Inbound webhook page.
Sender rules, spam & viruses
Sender rules (per domain, in the dashboard or the API):
a block rule refuses mail from an address (jane@example.com), a domain (example.com)
or its subdomains (*.example.com). Add any allow rule and only matching senders are accepted, which
suits an address that should only hear from one supplier or system. Because a From address is easy to fake, allowed
senders must also pass authentication: DMARC, or (for domains without DMARC) DKIM or SPF for their own domain.
Spam and viruses (when this platform has scanning switched on): every email gets
data.spam (an rspamd score; around 6 is probably spam, 15 definitely) and data.virus
(ClamAV). Emails with a virus are refused by default. Set a spam score on the Inbound webhook page to refuse anything
above it; otherwise you get everything with its score and can decide yourself. If a scanner is unavailable, mail is
still delivered, with that field null.
Refused mail gets a permanent SMTP error, so the sender knows it didn't arrive; it never reaches your webhook and shows in the delivery log with the reason.
Test your webhook
POST /v1/webhooks/test
Sends a signed webhook.test event to your configured webhook URL, once, and reports what happened.
There's also a Send test event button on the Inbound webhook page.
curl -X POST https://ghostparse.com/v1/webhooks/test -H "Authorization: Bearer $EMAIL_PARSER_API_KEY"
{ "delivered": true, "event_id": "evt_…" } // 200
{ "delivered": false, "event_id": "evt_…", "error": "Webhook responded 500" } // 502
The test event's data is { "message": "Test event from GhostParse" }.
Sample emails
See exactly what your webhook will receive without writing an email: Send a sample email on the
Domains or Inbound webhook page, email-parser sample, or:
POST /v1/samples
curl -X POST https://ghostparse.com/v1/samples -H "Authorization: Bearer $EMAIL_PARSER_API_KEY" \
-H "Content-Type: application/json" -d '{ "to": "support@yourapp.com" }'
{ "to": "support@yourapp.com", "delivered": true }
A realistic customer reply (with quoted history, an attachment and an order number) goes through the real
pipeline: parsing, checks, your address's parser, signing and delivery, and appears in the delivery log. Without
to it goes to your instant address, else your first receiving address. It carries the header
X-Email-Parser-Sample: true (in data.headers) so your code can tell. 10 per minute.
CLI: email on localhost
Develop your webhook handler on your laptop without deploying it or opening a tunnel:
export EMAIL_PARSER_API_KEY=ek_live_… export EMAIL_PARSER_URL=https://ghostparse.com npx @wildye/email-parser-cli listen --forward http://localhost:3000/webhooks/email Ready. No webhook URL is set, so your mail comes here. Send mail to k3j9x2m4q8a7@in.example.com, or run email-parser sample in another terminal. 10:42:07 200 jane@example.com → support@yourapp.com Re: Order #1042 38 ms
Each email is POSTed to your local URL exactly as a webhook would be, signature included, so your verification code runs unchanged.
- No webhook URL on the account: the CLI is where mail goes. Your local endpoint's status is
passed back: a
2xxaccepts the email, an error makes the sender retry later, just like a webhook. - A webhook URL is set: the CLI gets a copy of every email; your webhook still decides.
| Command | Does |
|---|---|
email-parser listen --forward URL | Stream inbound email to a local URL (without --forward, just print it; --print shows the JSON) |
email-parser simulate URL | Sandbox: POST a signed webhook to a local URL, with no email sent (see below) |
email-parser sample [--to ADDRESS] | Send a sample email |
email-parser inbox | Print your instant address |
email-parser deliveries [--status S] [--follow] | Show (and watch) the delivery log |
email-parser reply-address ADDRESS TAG | Make a signed reply address |
Needs Node.js 18+; no other dependencies. The CLI uses GET /v1/listen (a Server-Sent Events
stream) and POST /v1/listen/ack; any API key works. Connecting is recorded in the audit log.
Importing old email: POST /v1/parse
Moving a mailbox here? Send each old message as raw MIME (Content-Type: message/rfc822). You get back
the same JSON as an email.received event's data, with attachments inline, so imported mail
looks and threads like new mail. Nothing is stored or delivered, and it doesn't count towards your plan.
The limits are 600 requests a minute per key and 100,000 messages a day per account. Desk's
Import email uses it.
curl -X POST https://ghostparse.com/v1/parse \
-H "Authorization: Bearer $API_KEY" -H "Content-Type: message/rfc822" \
--data-binary @old-message.eml
# → { "data": { "message_id": "<…>", "subject": "…", "from": {…}, "text": "…", "attachments": [ … ], "thread_id": "…" }, "size_bytes": 18234 }
Sandbox: simulate webhooks
Test your handler before you have a domain, an account, or any email at all. simulate POSTs a
realistic event to a local URL, signed exactly as we sign real ones:
# No account needed: built-in sample events, signed with your secret npx @wildye/email-parser-cli simulate http://localhost:3000/webhooks/email --secret whsec_… npx @wildye/email-parser-cli simulate http://localhost:3000/webhooks/email --event bounced # Your own email, parsed by the real parser (needs an API key; nothing is delivered, stored or counted) email-parser simulate http://localhost:3000/webhooks/email --eml ./invoice.eml --to invoices@yourapp.com # …and with what your rules parser extracts from it, in "extracted" email-parser simulate http://localhost:3000/webhooks/email --eml ./invoice.eml --parser prs_… # Check your endpoint refuses a forged webhook, and handles retries of the same webhook-id email-parser simulate http://localhost:3000/webhooks/email --bad-signature email-parser simulate http://localhost:3000/webhooks/email --repeat 3
- Events:
email.received(default),email.bouncedandemail.complained. Each hasdata.sandbox: true, so your code can tell a test from real mail. - Signing:
--secret(orEMAIL_PARSER_WEBHOOK_SECRET) with your real signing secret; without one, a test secret is made up and shown.--legacysigns the original way. - The API behind it:
POST /v1/sandbox/events?type=…&to=…&parser=…(any API key) returns the event as JSON. Send a raw email (Content-Type: message/rfc822) to buildemail.receivedfrom it. Withparser(a rules parser's id),extractedis filled in; AI parsers aren't run here, as each run uses your allowance (use the parser's Test button).
Walkthrough: Test your webhook handler locally.
Integrations: Make, n8n, Slack, Teams, Sheets
Besides your webhook, email can go to destinations: a Slack or Microsoft Teams channel, a Google Sheet, more webhooks, or a Make scenario or n8n workflow. Set them up on the dashboard's Integrations page (or with the API), and choose which email goes where with routing rules.
- A destination can get every email (optionally only email to addresses matching a pattern), or only what routing rules send it.
- With no webhook URL at all, email still flows as long as the account has a destination.
- Destinations get the email the moment it arrives. Nothing is stored, and the same no-storage promise applies.
Make and n8n connect with an API key that has the Integrations permission
(integrations). Create one under API keys in the dashboard. Each automation you turn on appears on
the Integrations page; turning it off removes it.
Make
Add the GhostParse → Watch emails module at the start of a scenario, create a connection
with your API key, and optionally set Only email sent to. Make registers its webhook with us when the
scenario is created, so you never copy a URL. Every field of the email can be
mapped, including extracted.fields.
n8n
Install the community node n8n-nodes-ghostparse (Settings → Community nodes), add a
GhostParse Trigger, and create its credential with your API key. Activating the workflow
registers it with us, and deactivating it removes it. If you also paste your whsec_… signing secret into the
credential, the node rejects any request that isn't signed by us.
WordPress
The GhostParse plugin for WordPress sends the site's email through GhostParse and receives email into WordPress. Install it from the WordPress plugin directory (search for GhostParse) or upload the plugin zip under Plugins → Add New → Upload Plugin, then open Settings → GhostParse and paste an API key with the Send email and Integrations permissions.
Sending
- Every
wp_mail()email (password resets, WooCommerce, contact forms) goes throughPOST /v1/emails: recipients, HTML or text, attachments and custom headers. Other plugins keep working unchanged. - Set the From address to one of your sending addresses. It's always used; another plugin's From address (a contact form's visitor) becomes the Reply-To.
- Send a test email to me checks it, and the settings page lists recent sends with any error. Optionally, WordPress sends an email the usual way when GhostParse can't.
Receiving
- Paste your webhook signing secret (Inbound webhook page) and click Connect receiving. The site
subscribes itself as a REST hook (
POST /v1/hooks), so your own webhook keeps getting email too. Limit it to some addresses with a pattern likesupport@*. - Inbox: received email appears in the WordPress admin (administrators only), with attachments in the Media Library if you choose and a reply box that sends a threaded reply.
- Post by email: email to an address you choose, from someone with an account who can write posts, becomes a post: a draft, for review, or published. By default only senders that pass DMARC can post.
- Developers:
do_action('ghostparse_email_received', $email, $event)gets every email as the webhook'sdata(see Webhook payload); other events arrive onghostparse_event. - Every request is checked against the signing secret, and each event is handled once. Deactivating the plugin stops the deliveries.
WooCommerce
With WooCommerce active (orders stored as posts or in order tables), the plugin adds:
- Customer replies on the order: order emails to customers get a Reply-To made for that order
(
shop+o1234.<signature>@yourdomain.com, fromPOST /v1/reply-addresses). A reply arrives with the verified tag, so it's added to the order as a private note, the order is flagged Customer replied in the orders list, and you're emailed. A faked tag only reaches the Inbox. Set Replies go to to an address with Receive on that's delivered to the site (it defaults to the From address). - Email customer from the order page, in your WooCommerce email style, with saved messages and
placeholders (
{first_name},{order_number},{order_total},{order_link}…). It's noted on the order, and replies come back to it. - Replying from the Inbox to a customer's email keeps the order's Reply-To and notes the reply on the order.
Developers get
do_action('ghostparse_woocommerce_customer_replied', $order, $email).
The Autopilot for WooCommerce
Plugin 1.1 adds the Autopilot to WooCommerce. Turn it on under Settings → GhostParse → Autopilot (it needs receiving connected, the Inbox on, sending on, and AI turned on for your GhostParse account on the Parsers page). Then each customer email that reaches the Inbox is read in the background (WooCommerce's Action Scheduler, or WP-Cron):
- The order: a reply to an order email goes to its order; otherwise an order number in the subject, then the sender's latest order. Its details are used only when the sender is shown to be its customer: a reply to the order's signed address, or the billing address with DMARC passing.
- The facts are read in WordPress: status, payment, items, shipping method and address, notes already sent to
the customer, and tracking from WooCommerce Shipment Tracking, Advanced Shipment Tracking or YITH Order Tracking. Add
others with the
ghostparse_autopilot_order_factsfilter ($facts['tracking'][] = ['carrier' => …, 'number' => …, 'link' => …, 'shipped' => timestamp]); custom order numbers withghostparse_autopilot_order_by_number. - The decision: the plugin sends the email and the facts to
POST /v1/autopilot/decide(an API key with Send email). GhostParse asks the AI and returns the kind of email, how sure it is, a summary, anything to do, and the reply. Nothing is kept on our side. - What happens: you choose per kind of email. Automatic replies go to the sender's own address, threaded, in your WooCommerce email style, and are noted on the order. Drafts open in the Inbox with the reply written (Send reply or Dismiss draft; the Drafts to check view lists them). Changes, cancellations and returns put a To do on the order and in the orders list until you tick it done.
Any other platform: REST hooks
The apps above use a small subscription API that any automation tool can use (key with the
integrations permission):
| Endpoint | Does |
|---|---|
POST /v1/hooks | Subscribe a URL to email.received: { "target_url", "source": "make"|"n8n"|"webhook", "filter": { "address": "invoices@*" } }. Returns 201 with the hook's id. |
GET /v1/hooks | List your subscriptions |
DELETE /v1/hooks/{id} | Unsubscribe |
GET /v1/hooks/sample | A realistic email.received event in an array, for field mapping |
GET /v1/me | The account and key (any key): use it to test a connection |
Each email is POSTed to the hook as JSON, signed like your webhook (verify it the same
way). Attachments are included as base64 up to 5 MB in total. Above that, content is null
and the name, type and size are still given. Answer 410 Gone and the hook is removed. Any other
failure is shown on the Integrations page and in the delivery log.
Slack
- At api.slack.com/apps, create an app From scratch, open Incoming Webhooks and switch it on.
- Choose Add New Webhook to Workspace, pick the channel and copy the URL
(
https://hooks.slack.com/services/…). - On our Integrations page, add a Slack destination with that URL.
Each email is posted with its subject, sender, text (untick Include the message text to leave it out), your parser's extracted fields, and the attachment names. The URL is stored encrypted and never shown again.
Microsoft Teams
- In the Teams channel, open ⋯ → Workflows and choose Post to a channel when a webhook request is received.
- Finish the steps and copy the workflow's URL.
- Add a Microsoft Teams destination with it.
Emails arrive as an Adaptive Card. Older Office 365 connector URLs (….webhook.office.com) work as well.
Google Sheets
Each email adds one row with the columns you choose, in order: received_at, from,
from_name, to, cc, subject, text,
reply_text, attachments, attachment_count, spam_score,
thread_id, message_id, email_id, extracted (all fields as
JSON), or extracted.<field> for one parser field. Values are always written as plain text,
so an email can't slip a formula into your sheet.
Connect with a small Apps Script in your sheet. It adds the rows itself, so we never get access to your Google account:
- In the sheet, open Extensions → Apps Script, replace the code with the script below and save.
- Deploy → New deployment → Web app, set Execute as: Me and Who has access: Anyone,
deploy, and copy the URL that ends in
/exec. - Add a Google Sheets destination, choose Apps Script web app and paste the URL.
function doPost(e) {
var body = JSON.parse(e.postData.contents);
var book = SpreadsheetApp.getActiveSpreadsheet();
var sheet = (body.sheet && book.getSheetByName(body.sheet)) || book.getSheets()[0];
if (sheet.getLastRow() === 0) sheet.appendRow(body.columns);
sheet.appendRow(body.row);
return ContentService.createTextOutput("ok");
}
Anyone who knows the /exec URL can add rows, so keep it private, as you would a password.
Routing rules
Send email to different places depending on its subject, sender, recipient, text, attachments or spam score. Rules are checked from the top of the list:
| Action | What happens |
|---|---|
route | Send only to the rule's targets (destinations and/or "webhook", the address's usual webhook). Stop. |
copy | Also send to the rule's destinations, and carry on down the list. |
drop | Accept the email but deliver it nowhere (logged as dropped). Stop. |
Email that no route or drop rule matches goes to your webhook and to every destination set to
get every email. A rule can apply to one domain (domain_id) or to all of them, and matches when
all (or any) of its conditions are true.
field | op |
|---|---|
subject, from, from_domain, from_name, to (your address it was sent to), cc, body, attachment_name, header (with header: the name) |
contains, not_contains, equals, not_equals, starts_with, ends_with, matches, not_matches. Case doesn't matter; matches takes a pattern where * is any text and ? one character. |
spam_score | gte, lt (a number) |
has_attachments | is_true, is_false |
POST /v1/rules
{
"name": "Invoices to the finance sheet",
"conditions": [
{ "field": "from_domain", "op": "ends_with", "value": "stripe.com" },
{ "field": "subject", "op": "contains", "value": "invoice" }
],
"action": "route",
"targets": ["dst_9f2k…", "webhook"]
}
Delivery: the targets an email is routed to must all take it. If one is temporarily down, the
sender is asked to retry, just as when your webhook is down, so a target that already took it may see it again
(de-duplicate on the webhook-id header, or the event id in the body). Copies are best effort: a failing copy never holds up the email,
but it shows on the Integrations page and in the delivery log. If a rule routes to destinations that are all switched
off, the email waits (the sender retries) instead of being lost.
Rules run before your plan's allowance is checked, so dropped email isn't counted.
Destinations & rules API
Everything on the Integrations and Routing rules pages is also available through the API (key with the
integrations permission):
| Endpoint | Does |
|---|---|
GET / POST /v1/destinations | List or add a destination: { "type": "slack"|"teams"|"google_sheets"|"webhook", "name", "url", "all_mail", "filter", "include_body" }; for Sheets, mode, spreadsheet, sheet, columns |
GET / PATCH / DELETE /v1/destinations/{id} | Read, change (e.g. { "enabled": false }) or delete one. URLs are never returned, only a summary. |
POST /v1/destinations/{id}/test | Send it the sample email |
GET / POST /v1/rules | List rules in order, or add one (position puts it at that place, 1 = first) |
GET / PATCH / DELETE /v1/rules/{id} | Read, change (including position) or delete a rule |
POST /v1/rules/test | Where would this email go? { "subject", "from", "to", "body" } → { "action", "targets", "copies", "matched" }. Nothing is sent. |
Deleting a destination removes it from the rules that send to it. A route rule left with no targets is switched off.
Domains API: overview & permissions
Everything you can do on the dashboard's Domains pages is also available through the API, so a web hosting company, agency or SaaS platform can set up email for its own customers automatically: add the customer's domain and the addresses that receive mail, publish the DNS records we return, verify, and route the customer's inbound mail to its own webhook.
domains). Tick it when creating the key under API keys. Keys made for
sending only have the send scope and get 403 insufficient_scope here. Use separate keys for
your control panel and for your apps, so a leaked sending key can't change your domains.
| Endpoint | Does |
|---|---|
GET /v1/domains | List domains (filter with ?reference= or ?name=) |
POST /v1/domains | Add a domain, optionally with its addresses and settings |
GET /v1/domains/{id} | Get one domain, including DNS records and their status |
PATCH /v1/domains/{id} | Turn inbound on/off, set its webhook URL or reference |
POST /v1/domains/{id}/verify | Check DNS now (30 per minute per key) |
DELETE /v1/domains/{id} | Remove the domain and its addresses; sending and receiving stop immediately |
POST /v1/domains/{id}/addresses | Add an email address |
PATCH /v1/domains/{id}/addresses/{addressId} | Change its Send/Receive permissions, webhook or signed-tag requirement |
DELETE /v1/domains/{id}/addresses/{addressId} | Remove an email address |
GET / POST /v1/domains/{id}/sender-rules | List or add sender rules |
DELETE /v1/domains/{id}/sender-rules/{ruleId} | Remove a sender rule |
Every change is recorded in your audit log against the API key that made it. Accounts can have up to 20 domains.
Create a domain
POST /v1/domains
curl https://ghostparse.com/v1/domains \
-H "Authorization: Bearer $EMAIL_PARSER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "customer-shop.com",
"reference": "hosting-customer-1001",
"inbound_enabled": true,
"webhook_url": "https://customer-shop.com/webhooks/email",
"addresses": [
{ "local_part": "info", "can_send": true, "can_receive": true },
{ "local_part": "noreply", "can_send": true, "can_receive": false }
]
}'
| Field | Type | Notes |
|---|---|---|
name required | string | The domain, e.g. customer-shop.com or a subdomain like mail.customer-shop.com. |
reference | string or null | Your own ID for this domain (e.g. your customer number), up to 255 characters. Filter by it with GET /v1/domains?reference=…. |
inbound_enabled | boolean | Receive mail for this domain. Default false. |
max_message_bytes | integer or null | Largest email accepted for this domain, from 1024 up to the platform limit (25 MB). null = the platform limit. |
webhook_url | string or null | Where this domain's inbound mail is POSTed. Overrides the account's webhook URL; leave empty to use the account's. Must be public https://. Webhooks are always signed with your account's signing secret. |
addresses | array | Email addresses to allow, each { local_part, can_send, can_receive } (both default true), optionally with webhook_url and require_signed_tag. local_part may be a pattern like ticket-* or *. local_part is the part before the @. |
Returns 201 with the domain object, including the records to
publish. The domain and its addresses are created together: if anything is invalid, nothing is created.
Publish DNS and verify
Each domain gets its own DKIM key. Publish every record in the domain's records array at the
customer's DNS (if you host their DNS, do it automatically), then:
POST /v1/domains/{id}/verify
{
"domain": { "id": "dom_…", "sending_ready": true, "inbound_ready": false, … },
"checks": {
"spf": { "ok": true, "found": ["v=spf1 include:_spf.ghostparse.com ~all"] },
"dkim": { "ok": true, "found": ["v=DKIM1; k=rsa; p=MIIBIjAN…"] },
"dmarc": { "ok": true, "found": ["v=DMARC1; p=quarantine"], "warning": "Your DMARC record doesn't send reports to us, …" },
"mx": { "ok": false, "found": ["5 mail.example.com", "10 mx.ghostparse.com"],
"error": "Mail goes to mail.example.com first (a lower number is tried first), so it doesn't reach us. …" }
}
}
MX entries in found are "priority host". MX only counts when ours is first in line: the
lowest priority number, not shared with another server. Mail servers try the lowest number first, so another server
ahead of ours, or level with it, keeps the mail. A warning is something worth fixing in a record that
works, such as a DMARC record that doesn't send its reports to us.
DNS changes can take a few minutes to propagate. Retry verification with a backoff (e.g. after 1, 5 and 15 minutes) rather than in a tight loop. Verified domains are also re-checked automatically every few hours. Only the DKIM record proves ownership, and a domain can only be verified on one account at a time.
List, update and delete domains
GET /v1/domains → { "domains": [ … ] }
GET /v1/domains?reference=hosting-customer-1001
GET /v1/domains?name=customer-shop.com
GET /v1/domains/{id} → domain object
PATCH /v1/domains/{id} → domain object
DELETE /v1/domains/{id} → 204 No Content
PATCH accepts any of inbound_enabled, webhook_url (set null to
fall back to the account's) and reference:
{ "inbound_enabled": false }
When a hosting customer leaves, DELETE the domain. Their addresses are removed with it, and mail to
the domain is refused from then on.
Manage email addresses
POST /v1/domains/{id}/addresses { "local_part": "billing", "can_send": true, "can_receive": false }
PATCH /v1/domains/{id}/addresses/{addressId} { "can_receive": true }
DELETE /v1/domains/{id}/addresses/{addressId} → 204 No Content
POST returns 201 and PATCH returns 200, each with the address:
{
"id": "adr_…",
"address": "billing@customer-shop.com",
"local_part": "billing",
"can_send": true,
"can_receive": false,
"created_at": "2026-10-02T09:00:00.000Z"
}
Local parts are lower-cased and may contain letters, digits and . _ - (and the other characters
allowed in email addresses), but not +: sub-addresses such as billing+invoices@ match their
base address automatically. An address must allow sending, receiving or both. Up to 100 addresses per domain.
Addresses also take parser_id (a parser from the dashboard; null
for none), webhook_url (send this address's mail to its own endpoint; null to
use the domain's or account's) and require_signed_tag (accept only signed reply
addresses). A local_part containing * is a pattern; responses
say so with is_pattern. Patterns can only receive (422 pattern_cannot_send).
Sender rules
GET /v1/domains/{id}/sender-rules → { "sender_rules": [ { "id": "rul_…", "action": "block", "pattern": "spammer.example", "created_at": "…" } ] }
POST /v1/domains/{id}/sender-rules { "action": "allow", "pattern": "*.supplier.example" } → 201 with the rule
DELETE /v1/domains/{id}/sender-rules/{ruleId} → 204 No Content
action is block or allow; pattern is an address, a domain, or
*. plus a domain for its subdomains (lower-cased). Up to 200 rules per domain. How they're applied:
Sender rules, spam & viruses. The domain object lists them in sender_rules.
The domain object
{
"id": "dom_…",
"name": "customer-shop.com",
"reference": "hosting-customer-1001",
"created_at": "2026-10-02T09:00:00.000Z",
"last_checked_at": "2026-10-02T09:05:00.000Z",
"inbound_enabled": true,
"webhook_url": "https://customer-shop.com/webhooks/email",
"max_message_bytes": null,
"sending_ready": true,
"inbound_ready": true,
"records": [
{ "kind": "spf", "type": "TXT", "host": "customer-shop.com", "value": "v=spf1 include:_spf.ghostparse.com ~all", "verified": true, "purpose": "…", "note": "…" },
{ "kind": "dkim", "type": "TXT", "host": "ep1a2b3c._domainkey.customer-shop.com", "value": "v=DKIM1; k=rsa; p=MIIBIjAN…", "verified": true, "purpose": "…" },
{ "kind": "dmarc", "type": "TXT", "host": "_dmarc.customer-shop.com", "value": "v=DMARC1; p=none; adkim=r; aspf=r; rua=mailto:dmarc+k3x9q2m7wb4t@mx.ghostparse.com", "verified": true, "purpose": "…", "note": "…" },
{ "kind": "mx", "type": "MX", "host": "customer-shop.com", "value": "mx.ghostparse.com", "priority": 10, "verified": true, "purpose": "…", "note": "…" }
],
"dmarc_report_address": "dmarc+k3x9q2m7wb4t@mx.ghostparse.com",
"addresses": [
{ "id": "adr_…", "address": "info@customer-shop.com", "local_part": "info", "is_pattern": false, "can_send": true, "can_receive": true,
"webhook_url": null, "require_signed_tag": false, "parser_id": null, "created_at": "…" }
],
"sender_rules": []
}
| Field | Notes |
|---|---|
records | What to publish. host is the full name; some DNS providers want only the part before the domain. verified is the latest check's result. On Cloudflare, the dashboard can add them for you: on the domain's page, click Connect Cloudflare (or paste an API token that can edit the zone's DNS), preview the changes and confirm. On cPanel hosting, choose Connect cPanel instead and paste your cPanel address, username and an API token (Security → Manage API Tokens). It can also replace cPanel's own MX records with ours if you tick the box, and install the webmail on the hosting. Existing SPF and DMARC records are added to, existing MX records are left alone unless you ask, and the access is used for that change only. The SPF note explains merging with an existing SPF record. |
dmarc_report_address | Where this domain's DMARC reports go: the rua= in its DMARC record. |
sending_ready | SPF, DKIM and DMARC verified and at least one address can send. |
inbound_ready | DKIM and MX verified, inbound on, a webhook URL (domain's or account's) set, and at least one address can receive. |
DMARC reports
Gmail, Outlook, Yahoo and other mailbox providers send a daily aggregate report to the address in a
domain's DMARC record (rua=): every server that sent email using the domain, how many emails, and whether
they passed SPF, DKIM and DMARC. It's how you find a service you forgot to set up, or someone spoofing your domain,
before moving your policy from p=none to quarantine or reject.
Every domain gets its own report address, dmarc_report_address, already included in the DMARC record
we show you. Reports sent there appear on the dashboard's DMARC reports page and through these
endpoints. Already have a DMARC record? Keep it, and add the address to its rua= (separate several with
commas):
_dmarc.customer-shop.com TXT "v=DMARC1; p=none; rua=mailto:dmarc+k3x9q2m7wb4t@mx.ghostparse.com,mailto:you@customer-shop.com"
- If the domain's mail comes to us, reports sent to
dmarc@the domain itself count too (unless you've added admarcaddress of your own, which then gets them as normal email). - Reports are read automatically (XML,
.gzor.zip) and never sent to your webhook. A report that arrives twice is kept once. Reports about a different domain are ignored. - They hold sending IP addresses, domains and counts, never email content, and are kept for 90 days.
- The first reports usually arrive 24 to 48 hours after you publish the record, once the domain has sent email.
| Endpoint | Returns |
|---|---|
GET /v1/dmarc | Every domain with its report address and the last 30 days' totals |
GET /v1/domains/{id}/dmarc?days=30 | One domain over 1 to 90 days: totals, each sending source, and the reports |
GET /v1/dmarc/reports/{id} | One report with every row |
They need an API key with the Manage domains permission (domains).
GET /v1/domains/dom_…/dmarc?days=30
{
"domain_id": "dom_…", "domain": "customer-shop.com", "report_address": "dmarc+k3x9q2m7wb4t@mx.ghostparse.com", "days": 30,
"totals": { "reports": 21, "messages": 6601, "passed": 6475, "failed": 126, "pass_rate": 98.1 },
"sources": [
{ "source_ip": "209.85.220.41", "hostname": "mail-sor-f41.google.com", "messages": 4046, "passed": 4046,
"dkim_pass": 4046, "spf_pass": 4046, "quarantined": 0, "rejected": 0, "header_from": "customer-shop.com",
"reporters": ["google.com", "Outlook.com", "Yahoo"] },
{ "source_ip": "198.51.100.66", "hostname": null, "messages": 126, "passed": 0, "dkim_pass": 0, "spf_pass": 0,
"quarantined": 126, "rejected": 0, "header_from": "customer-shop.com", "reporters": ["google.com"] }
],
"reports": [
{ "id": "dmr_…", "org_name": "google.com", "org_email": "noreply-dmarc-support@google.com", "report_id": "1234567890",
"date_begin": "2026-10-04T00:00:00.000Z", "date_end": "2026-10-04T23:59:59.000Z",
"policy": { "domain": "customer-shop.com", "p": "none", "pct": 100 }, "messages": 542, "passed": 537, "pass_rate": 99.1,
"received_at": "…" }
]
}
DMARC passes when either DKIM or SPF passes and aligns with the From domain, so passed counts
rows where dkim_pass or spf_pass applies. A report from /v1/dmarc/reports/{id}
adds records, one per source and result, each with source_ip, count,
disposition (none, quarantine or reject), dkim and
spf (the DMARC verdicts), header_from, envelope_from, and the raw
dkim_auth and spf_auth results.
Resellers: sub-accounts
Hosting companies and platforms can run their customers as sub-accounts: each has its own domains,
webhook, signing secret, delivery log and team, while you create and manage them all through one API key. The
platform operator turns reseller features on for your account (or they come with a Reseller plan, priced per mailbox); then a Reseller page appears in the
dashboard and you can create keys with the Manage sub-accounts permission (scope accounts).
Selling to web-hosting customers? The partner programme has the WHMCS module.
| Endpoint | Does |
|---|---|
GET /v1/accounts | List sub-accounts (filter with ?reference=), with domain, user and delivery counts |
POST /v1/accounts | Create one: name, optional reference (your ID), webhook_url, owner_email (sends a branded invitation to the dashboard) and package (a customer package's id or name). Returns its webhook_secret once. |
GET / PATCH / DELETE /v1/accounts/{id} | Read, rename, suspend ({"suspended": true}), move to another package ({"package": "Email Pro"}), pause or resume its sending ({"sending_paused": false}), or delete with everything in it |
GET / POST /v1/packages, PATCH / DELETE /v1/packages/{id} | Customer packages: name, max_mailboxes, max_domains, monthly_emails (each null for no limit) and over_limit (block or allow) |
GET /v1/accounts/usage | Each customer's month, to bill them: ?month=2026-11, and &format=csv for a CSV file. One customer: GET /v1/accounts/{id}/usage |
POST /v1/accounts/{id}/invitations | Invite someone to its dashboard |
POST /v1/accounts/{id}/api-keys | Create a key that belongs to the sub-account (send, domains, integrations), for an app you install for your customer. It's shown once. Revoke it with DELETE /v1/accounts/{id}/api-keys/{keyId} |
GET /v1/accounts/{id}/webhook-secret | Its webhook signing secret, for an app you set up that checks the signatures |
On cPanel & WHM? The free cPanel plugin does all of this from your customers' own cPanel. It creates their sub-account, writes their DNS records in the zone on your server, and installs their webmail. To build the same for another control panel, POST /v1/domains/{id}/dns-plan takes the TXT and MX records a zone has now and returns the changes to make, with SPF and DMARC merged.
Acting on a sub-account: send the Email-Parser-Account header with any other endpoint, and
the request applies to that sub-account with your key's other permissions:
curl -X POST https://ghostparse.com/v1/accounts \
-H "Authorization: Bearer $RESELLER_KEY" -H "Content-Type: application/json" \
-d '{ "name": "Bob'\''s Bakery", "reference": "cust-77", "webhook_url": "https://bobsbakery.example/webhooks/email" }'
# → { "id": "acct_mb_kwrlaq_jhk2AQ", "webhook_secret": "whsec_…", … }
curl -X POST https://ghostparse.com/v1/domains \
-H "Authorization: Bearer $RESELLER_KEY" -H "Email-Parser-Account: acct_mb_kwrlaq_jhk2AQ" \
-H "Content-Type: application/json" \
-d '{ "name": "bobsbakery.example", "inbound_enabled": true, "addresses": [{ "local_part": "orders" }] }'
- Everything a sub-account's own key could do works this way: domains,
/v1/webhooksettings and secret rotation, samples, the delivery log, reply addresses and the CLI listener. - Changes are audit-logged in the sub-account, naming your key.
- Suspended sub-accounts have their mail refused, their users signed out and their own API keys blocked; you can still manage them and unsuspend.
- Up to 500 sub-accounts per reseller; each has the normal per-account limits.
Customer packages
A package is a product you sell: how many mailboxes (email addresses) and domains a customer can add, and how many
emails a calendar month (received and sent) they get. Put a customer on one when you create them, or later. Adding
beyond it is refused with package_limit, telling the customer to ask you to upgrade. At the email limit, a
package either holds new email back ("over_limit": "block": incoming senders retry, and sending through the
API is refused) or lets it through and counts it as over ("allow"), for you to charge for. Changing a
customer's package only limits what they add from then on.
curl -X POST https://ghostparse.com/v1/packages \
-H "Authorization: Bearer $RESELLER_KEY" -H "Content-Type: application/json" \
-d '{ "name": "Email Basic", "max_mailboxes": 3, "max_domains": 1, "monthly_emails": 2000, "over_limit": "block" }'
curl -X POST https://ghostparse.com/v1/accounts \
-H "Authorization: Bearer $RESELLER_KEY" -H "Content-Type: application/json" \
-d '{ "name": "Bob'\''s Bakery", "reference": "whmcs-1042", "owner_email": "bob@bobsbakery.example", "package": "Email Basic" }'
Usage reports
GET /v1/accounts/usage gives every customer's month: mailboxes and domains now (and their package's
limits), emails received and sent, emails over the limit (to charge for) and held back by it, and permanent bounces
and spam complaints, with totals and your own plan's figures. ?format=csv returns a CSV file, one row per
customer, for a spreadsheet or a billing system. The same report is on the Reseller page.
Sending reputation
Bounces and complaints from one customer affect delivery for everyone, so your customers' sending is protected:
- New customers ramp up: up to 200 emails a day for their first week, then 1,000 a day until they're
a month old. Beyond that, sending is refused with
ramp_limit(429) until the next day. - Too many bounces or complaints pause sending: checked every hour over the last 7 days, at 8%
permanent bounces (at least 10) or 0.3% spam complaints (at least 3). Sending is refused with
sending_paused(403), receiving carries on, and you and the customer are emailed. Resume it once the cause is fixed with{"sending_paused": false}or on the Reseller page: from then, only what happens after counts. - You can pause a customer's sending yourself the same way (
{"sending_paused": true}).
White-label branding
On the Reseller page, set your brand name, logo, colour and support address. Your sub-accounts' users then see your brand, not ours: in the dashboard, and in their account emails (invitations, password resets, alerts), which come from your name with replies going to your support address.
- Your own MX hostname, e.g.
mx.hostco.example: point it atmx.ghostparse.comwith a CNAME (or the same A/AAAA records) and click Check hostnames. Your customers' DNS instructions then use your hostname. Records pointing at ours keep working. - Your own dashboard hostname, e.g.
mail.hostco.example: point it atghostparse.comthe same way. Your customers log in there and see only your brand; sign-up is off on that hostname, because you create their accounts. HTTPS is set up for it automatically a few minutes after Check hostnames passes.
Errors
Errors return a JSON body with a machine-readable error and a human-readable message:
{ "error": "sender_not_allowed", "message": "\"ceo@yourapp.com\" is not an allowed sending address. …" }
| Status | error | Meaning | Retry? |
|---|---|---|---|
| 401 | Unauthorized | Missing, wrong or revoked API key. | No |
| 403 | domain_not_verified | The from domain isn't added or its SPF, DKIM and DMARC aren't verified. | No |
| 403 | sender_not_allowed | The from address isn't listed under the domain's Email addresses with Send on. | No |
| 402 | quota_exceeded, spend_cap | Sending: your plan's email allowance (shared by sent and received email) or your spending cap is used up. See Plans & usage. | After upgrading |
| 422 | recipients_suppressed | Every recipient is on your suppression list (an earlier hard bounce or spam complaint). suppressed lists them. | No |
| 403 | policy_violation | Too many recipients, or a forbidden/bulk header. | No |
| 403 | insufficient_scope | The API key lacks the permission this endpoint needs (send, domains, integrations or accounts). | No |
| 404 | not_found | The domain or address doesn't exist on your account. | No |
| 409 | domain_exists / address_exists | Already on your account. | No |
| 422 | invalid_domain, invalid_address, wrong_domain, duplicate_address, no_permissions, invalid_reference, invalid_webhook_url | Domains API input problems; message says exactly what's wrong. | No |
| 422 | too_many_domains / too_many_addresses / too_many_rules | Account or domain limit reached. | No |
| 422 | pattern_cannot_send, invalid_max_message_bytes, invalid_pattern | An address pattern with Send on, a size cap out of range, or a sender rule that isn't an address or domain. | No |
| 409 | rule_exists | That sender rule is already on the domain. | No |
| 422 | invalid_tag, address_not_receiving | Reply addresses: the tag has characters other than letters, digits, - and _, or the address isn't a receiving address on your domain. | No |
| 422 | invalid_status | Delivery log: unknown status filter. | No |
| 422 | no_receiving_address, not_receiving | Sample emails: nothing on the account can receive mail yet, or to isn't one of your receiving addresses (or no webhook URL or CLI listener is set). | After fixing the setup |
| 404 | parser_not_found | parser_id isn't one of your parsers. | No |
| 422 | invalid_destination, invalid_rule | Destinations and routing rules: message says what's wrong (for example a URL that isn't a Slack webhook, or a spreadsheet not shared with us). | No |
| 404 | destination_not_found, hook_not_found, rule_not_found | Not on your account. | No |
| 422 | too_many_destinations, too_many_routing_rules | An account can have 50 destinations (hooks included) and 100 routing rules. | No |
| 422 | package_limit | Adding a domain or mailbox beyond the customer's package. Sending at the package's monthly email limit is refused with 402 package_limit. | After an upgrade |
| 404 / 409 / 422 | package_not_found, package_exists, too_many_packages, invalid_limit, invalid_over_limit, invalid_month | Customer packages and usage reports: no such package, the name is taken, at most 100 packages, a limit that isn't a whole number, or a month that isn't like 2026-11. | No |
| 403 / 429 | sending_paused, ramp_limit | A reseller's customer: sending is paused (too many bounces or complaints, or by the reseller), or a new customer is at its daily limit. See Sending reputation. | After resuming / the next day |
| 403 | not_reseller | Reseller features aren't on for this account, so it can't use /v1/accounts or the accounts permission. | No |
| 403 | account_suspended | The account is suspended (by its reseller). | No |
| 404 | account_not_found | Not one of your sub-accounts (an Email-Parser-Account header or /v1/accounts/{id}). | No |
| 409 | secret_incompatible | Switching to Standard Webhooks with a secret made before it was supported: rotate the secret first. | After rotating |
| 422 | too_many_accounts | The reseller's sub-account limit is reached. | No |
| 422 | plan_limit | Your plan's limit on domains or team members is reached. Upgrade on the Billing page. | After upgrading |
| 422 | validation_error | The body is invalid. issues lists each problem with its path. | No |
| 429 | daily_limit_reached | Your account's daily sending limit is used up. | After it resets |
| 429 | Too Many Requests | More than 120 requests per minute for this key. Wait the number of seconds in the Retry-After header. | Yes |
| 409 | store_exists | BigCommerce: that store is already connected. | No |
| 422 | invalid_store, invalid_api_token | BigCommerce: not a store address or API path, or no token. | No |
| 422 | bigcommerce_error | BigCommerce refused the token (or didn't answer: 502); message says why. | With a working token |
| 409 | bigcommerce_token_needed | BigCommerce: the store has no API token to read the order with. | No |
| 503 | bigcommerce_unavailable | BigCommerce isn't available on this platform. | No |
| 502 | send_failed | Our outbound mail server couldn't take the message. | Yes, with the same Idempotency-Key |
// 422 example
{
"error": "validation_error",
"issues": [
{ "code": "invalid_format", "path": ["attachments", 0, "content"], "message": "Invalid base64-encoded string" },
{ "code": "custom", "path": ["to"], "message": "At least one recipient is required" }
]
}
Limits
These limits apply on every plan. Your plan's monthly allowances are under Plans & usage.
| Limit | Value |
|---|---|
| Outbound emails per account | 1,000 per rolling 24 hours |
| API requests per key | 120 per minute |
| Recipients per email (to + cc + bcc) | 50 |
| Message size | 25 MB (inbound and outbound) |
| Domains per account | 20 |
| Domain verification checks | 30 per minute per key |
| Email addresses per domain | 100 (patterns count as one) |
| Sender rules per domain | 200 |
| Delivery log | Kept 90 days |
| Parsers | 20 per account, 30 fields each |
| AI extractions | 200 per account per day |
| Sample emails | 10 per minute |
| Active API keys | 10 |
| Team members | 25 |
| Sub-accounts per reseller | 500 |
| Inbound email | No volume limit for your listed addresses (transactional use) |
Plans & usage
| Free | Pay as you go | Starter | Pro | Business | |
|---|---|---|---|---|---|
| Price | £0 | £0/month + usage | £9/month | £29/month | £99/month |
| Emails a month (sent + received) | 1,000 | 1,000 free | 10,000 | 50,000 | 250,000 |
| AI extractions a month | 50 | 250 | 500 | 2,500 | 10,000 |
| Domains | 1 + instant address | 5 | 5 | 25 | Unlimited |
| Team members | 2 | 5 | 5 | 15 | Unlimited |
| Delivery log | 3 days | 30 days | 30 days | 90 days | 90 days |
| Extra emails, per 1,000 | Held back | £1.50 | £1 | £0.80 | £0.50 |
| Reseller sub-accounts | – | – | – | – | ✓ |
- What counts: each email delivered to your webhook (or CLI listener), and each
recipient of an email you send through
/v1/emails(one email to three people counts as three). Sent and received email share one allowance. Refused, dropped and deferred emails don't, nor do suppressed recipients, and nor do bounce reports, DMARC reports or test events. - At the limit: paid plans keep delivering and bill extra emails on the next invoice (set a
spending cap on the Billing page if you want one). Free accounts get 10% extra, then new email is
deferred: SMTP senders get
451(HTTP relays503), so they retry, usually for several days. Upgrading in that time delivers it. The delivery log shows these as deferred withflags.code: "quota_exceeded"(or"spend_cap"). Sending through/v1/emailsis refused with402and the same codes. Owners and admins get emails at 80% and 100%. - Periods: Free counts calendar months (UTC); paid plans follow their billing period. Yearly plans pool 12 months' allowance over the year.
- Resellers: sub-accounts' emails count towards the reseller's plan, and they use its limits.
GET /v1/usage
{
"plan": "pro", "plan_name": "Pro", "interval": "month",
"period_start": "2026-10-01T09:00:00.000Z", "period_end": "2026-11-01T09:00:00.000Z",
"emails": { "used": 51200, "received": 38900, "sent": 12300, "included": 50000, "overage": 1200 },
"ai": { "used": 830, "included": 2500 },
"overage_pence_per_1000": 80, "overage_cost_pence": 96
}
Any API key can read its account's usage. Plans are changed on the dashboard's Billing page.
Status, IP addresses & data
- Status page: /status shows receiving (SMTP), webhook delivery and the
API, each checked every minute, with 90 days of uptime and any incidents. Machine-readable at
/status.json. - IP addresses: webhooks come from 77.72.7.69, 2a03:2800:500::52f.
GET /v1/meta(no key needed) lists the addresses webhooks come from, our MX hostname and where email is processed, for firewalls and compliance checks. - Data residency: email is processed on servers in the United Kingdom, except that AI extraction, if you turn it on, sends the email's text to Anthropic in the United States. It isn't stored: only delivery metadata is kept, for 90 days.
- Data Processing Agreement: our DPA (UK GDPR and EU GDPR Article 28) is part of the Terms, with the list of sub-processors. Nothing to sign.
Libraries & OpenAPI
Every SDK verifies webhooks (both signature formats, JSON and multipart), gives you the typed email, has a
thread_id helper, and wraps the API, including reseller sub-accounts.
| Language | Install |
|---|---|
| Node.js / TypeScript | npm install @wildye/email-parser |
| Python | pip install wildye-email-parser |
| PHP | composer require wildye/email-parser (also sending, with retries and idempotency) |
| Laravel | composer require wildye/email-parser-laravel: a webhook route that dispatches InboundEmailReceived events |
| Ruby | gem "wildye-email-parser" |
| Go | go get github.com/dwildman86/emailParser/sdk/go |
| CLI | npx @wildye/email-parser-cli: stream email to localhost, send samples, watch the delivery log (details) |
Any Standard Webhooks library also verifies our webhooks.
OpenAPI 3.1: /openapi.json. Import it into Postman or Insomnia,
or generate a client for your language.
Questions? Contact hello@wildye.com.