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 URLhttps://ghostparse.com
FormatJSON request and response bodies, UTF-8. Send Content-Type: application/json.
AuthAuthorization: Bearer <API key>
SendingPOST /v1/emails
ReceivingWe POST each inbound email to your webhook URL as signed JSON.
Transactional email only. Replies, support requests, notifications, documents emailed into your app. Newsletters, promotions, bulk or unsolicited email break the Terms and get accounts closed.
We don't store email. The API returns IDs when you send; your webhook receives each inbound email once it's accepted. Save what you need on your side.

Quick start

  1. Create a free account and verify your email address.
  2. In Domains, add your domain and publish the SPF, DKIM and DMARC records shown (plus MX if you want to receive mail). Click Verify.
  3. Under that domain's Email addresses, add the addresses you'll use, e.g. orders with Send on and support with Receive on. Only listed addresses can send or receive.
  4. In API keys, create a key. It's shown once: store it as a secret.
  5. 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."
  }'

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"
}
FieldDescription
idOur ID for this send. Store it; we don't keep a copy of the email.
message_idThe Message-ID header. Replies to this email reference it in In-Reply-To, so you can match them to the original.
fromThe From the email was sent with: its address and the name used (yours, or the address's saved From name; null when none).
accepted / rejectedRecipients the outbound server accepted or refused.
thread_idThe conversation this email starts (or continues): replies arrive with the same data.thread_id.
sent_atISO 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.

FieldTypeNotes
from requiredaddressMust 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_namestringThe 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, bccaddress or address[]At least one recipient across the three; at most 50 in total.
reply_toaddress or address[]
subject requiredstring1–998 characters.
textstringAt least one of text or html. Sending both is recommended.
htmlstring
headersobject of stringsCustom 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.
attachmentsattachment[]See Attachments.
in_reply_tostringThe Message-ID you're replying to. See threading.
referencesstring[]The thread's earlier Message-IDs.

Attachments & inline images

FieldTypeNotes
filename requiredstringShown to the recipient.
content requiredstringFile bytes, base64-encoded.
content_typestringe.g. application/pdf. Guessed from the filename if omitted.
content_idstringMakes 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 from has 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": false to 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 null or "" to clear a field.
  • With only html in 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 with 422 recipients_suppressed.
  • Told by webhook: your webhook receives email.bounced and email.complained events, so you can flag the address in your own app.
  • A text part is added when you send HTML only, and a Feedback-ID header 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.

EndpointDoes
GET /v1/suppressionsThe addresses you no longer send to, newest first
POST /v1/suppressionsAdd 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

  1. 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.
  2. BigCommerce shows the access token and the API path once (and downloads them as a file).
  3. 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.
  4. In BigCommerce, Marketing → Transactional emails: turn off its own order confirmation, shipped, cancelled and refunded emails, so customers get only ours.
BigCommerce webhookEmail
store/order/createdOrder confirmation (once the order is past Incomplete; a checkout that finishes later sends it then)
store/order/statusUpdatedOrder cancelled, when the status changes to Cancelled
store/shipment/createdShipping confirmation, for what's in that shipment
store/order/refund/createdRefund 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

  1. 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.com if your main domain's mail is handled elsewhere.
  2. 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.
  3. Turn on Inbound for the domain.
  4. 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"
  }
}
FieldNotes
typeemail.received, or webhook.test for test events, or email.bounced / email.complained for mail you sent. Ignore types you don't recognise.
tenant_idYour account ID.
data.thread_id, threadThe conversation: the same for the first message and every reply. See below.
data.message_idThe sender's Message-ID. To de-duplicate deliveries, use the webhook-id header instead: see handling duplicates.
data.envelope.rcpt_toThe 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_toFrom the message headers. from may be null.
data.text, htmlEither may be null.
data.reply_textJust 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.recipientsEach envelope recipient split up: base_address (the listed address it matched), tag (after the +) and tag_verified for signed reply addresses.
data.auto_submitted, bounceauto_reply, bounce, auto_generated or null. See below.
data.calendarMeeting invites found in the email. See below.
data.spam, virusScan results when this platform runs spam/virus scanning, else null. See below.
data.extractedThe fields your parser pulled out, or null when the address has none.
data.sizeSize of the original message in bytes.
data.headersAll headers, names lower-cased; repeated headers are joined with a newline.
data.attachments[].contentBase64 (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.authenticationOur 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.

EntryReceives
supportsupport@, 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.

Signed reply addresses

When your app emails someone about a ticket or thread, set its Reply-To to an address that says which one, and that nobody else can make up:

POST /v1/reply-addresses

curl https://ghostparse.com/v1/reply-addresses \
  -H "Authorization: Bearer $EMAIL_PARSER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "address": "support@yourapp.com", "tag": "t42" }'

{ "address": "support+t42.k3j9x2m4q8a7b@yourapp.com", "base_address": "support@yourapp.com", "tag": "t42" }

The tag is your own ID (1-40 letters, digits, - and _; lower-cased). Replies arrive with recipients[0].tag = "t42" and tag_verified: true. A tampered or guessed signature gives tag_verified: false; a plain support+anything@ gives null.

Tick Signed tags only on an address (or set require_signed_tag through the API) to refuse everything except valid signed addresses: then only people you've emailed can write to it. Make the address once when you send, store it if you like; it never expires. Any API key can call this endpoint.

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), else In-Reply-To, else Outlook's Thread-Index, else the email's own Message-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/emails returns it as thread_id.
  • Signed reply addresses: when the email came to a signed reply address, thread.tag is 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 References and In-Reply-To starts 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:

ValueMeansDetected by
auto_replyOut-of-office or other automatic replyAuto-Submitted: auto-replied, X-Autoreply, Precedence: auto_reply, or subjects like "Automatic reply:" / "Out of Office"
bounceA delivery failure report about an email sent from your addressA delivery-status report, or an empty envelope sender from MAILER-DAEMON / postmaster
auto_generatedOther machine-sent mailAuto-Submitted: auto-generated
nullSent 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:

SettingWhat you receive
Inside the JSON (default)application/json; each attachment's content is base64.
As separate filesmultipart/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 outJSON with names, types, sizes and hashes only (content is null).
Upload to your bucketJSON 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:

ServiceEndpointRegion
Amazon S3(not needed)Your bucket's, e.g. eu-west-2
Cloudflare R2https://<account id>.r2.cloudflarestorage.comauto
Backblaze B2https://s3.<region>.backblazeb2.come.g. us-west-004
Google Cloud Storagehttps://storage.googleapis.com (with an HMAC key)auto
DigitalOcean Spaceshttps://<region>.digitaloceanspaces.come.g. nyc3
Wasabi, MinIO, othersThe service's S3 endpointAs the service says
  1. 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/*"
      }]
    }
  2. 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.
  3. 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, url is a signed link that works for up to 7 days (you choose, from 1 hour). Download the file, or keep the key and 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_at is null).
  • 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. Check sha256 if 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

RuleExampleGives
Text afterOrder number on "Order number: 1042"1042 (the rest of the line, after any : # or -)
Text betweenTracking ( 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: true says 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(),
})

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: true means it passed every check.
  • Never held back: an answer that still doesn't pass is delivered with valid: false and errors (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 check valid in your code.
  • Missing values: say what may be missing. An optional property (date | None = None) comes back null or 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_sha256 identifies the exact schema used.
  • Supported: objects, lists, nesting, $defs references (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}/test before 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"])

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:

FieldValues
verdictDMARC 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.
dkimOne 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).
headerThe 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).

  1. Use the raw request body; don't parse and re-encode the JSON first.
  2. After you rotate the secret, there are two space-separated signatures for 24 hours (new secret first): accept the request if any matches.
  3. Reject the request if the timestamp is more than 5 minutes from your clock (replay protection).
  4. Respond 400 if verification fails, 2xx once you've stored the event.
  5. Skip events whose webhook-id you'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);
});

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. Its data.id is stable too.
  • email.bounced and email.complained: the same report about the same recipient has the same webhook-id.
  • The signature and webhook-timestamp are 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';

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 2xx response 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 4xx responses (except 408 and 429) are permanent: the email is bounced back to the sender. Return 400 only 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-id you'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-id is the event id. 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 4xx from 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 2xx accepts 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.
CommandDoes
email-parser listen --forward URLStream inbound email to a local URL (without --forward, just print it; --print shows the JSON)
email-parser simulate URLSandbox: 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 inboxPrint your instant address
email-parser deliveries [--status S] [--follow]Show (and watch) the delivery log
email-parser reply-address ADDRESS TAGMake 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.bounced and email.complained. Each has data.sandbox: true, so your code can tell a test from real mail.
  • Signing: --secret (or EMAIL_PARSER_WEBHOOK_SECRET) with your real signing secret; without one, a test secret is made up and shown. --legacy signs 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 build email.received from it. With parser (a rules parser's id), extracted is 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 through POST /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 like support@*.
  • 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's data (see Webhook payload); other events arrive on ghostparse_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, from POST /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_facts filter ($facts['tracking'][] = ['carrier' => …, 'number' => …, 'link' => …, 'shipped' => timestamp]); custom order numbers with ghostparse_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):

EndpointDoes
POST /v1/hooksSubscribe a URL to email.received: { "target_url", "source": "make"|"n8n"|"webhook", "filter": { "address": "invoices@*" } }. Returns 201 with the hook's id.
GET /v1/hooksList your subscriptions
DELETE /v1/hooks/{id}Unsubscribe
GET /v1/hooks/sampleA realistic email.received event in an array, for field mapping
GET /v1/meThe 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

  1. At api.slack.com/apps, create an app From scratch, open Incoming Webhooks and switch it on.
  2. Choose Add New Webhook to Workspace, pick the channel and copy the URL (https://hooks.slack.com/services/…).
  3. 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

  1. In the Teams channel, open ⋯ → Workflows and choose Post to a channel when a webhook request is received.
  2. Finish the steps and copy the workflow's URL.
  3. 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:

  1. In the sheet, open Extensions → Apps Script, replace the code with the script below and save.
  2. Deploy → New deployment → Web app, set Execute as: Me and Who has access: Anyone, deploy, and copy the URL that ends in /exec.
  3. 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:

ActionWhat happens
routeSend only to the rule's targets (destinations and/or "webhook", the address's usual webhook). Stop.
copyAlso send to the rule's destinations, and carry on down the list.
dropAccept 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.

fieldop
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_scoregte, lt (a number)
has_attachmentsis_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):

EndpointDoes
GET / POST /v1/destinationsList 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}/testSend it the sample email
GET / POST /v1/rulesList 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/testWhere 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.

Permissions. These endpoints need an API key with the Manage domains & addresses permission (scope 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.
EndpointDoes
GET /v1/domainsList domains (filter with ?reference= or ?name=)
POST /v1/domainsAdd 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}/verifyCheck 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}/addressesAdd 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-rulesList 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 }
    ]
  }'
FieldTypeNotes
name requiredstringThe domain, e.g. customer-shop.com or a subdomain like mail.customer-shop.com.
referencestring or nullYour own ID for this domain (e.g. your customer number), up to 255 characters. Filter by it with GET /v1/domains?reference=….
inbound_enabledbooleanReceive mail for this domain. Default false.
max_message_bytesinteger or nullLargest email accepted for this domain, from 1024 up to the platform limit (25 MB). null = the platform limit.
webhook_urlstring or nullWhere 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.
addressesarrayEmail 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": []
}
FieldNotes
recordsWhat 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_addressWhere this domain's DMARC reports go: the rua= in its DMARC record.
sending_readySPF, DKIM and DMARC verified and at least one address can send.
inbound_readyDKIM 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 a dmarc address of your own, which then gets them as normal email).
  • Reports are read automatically (XML, .gz or .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.
EndpointReturns
GET /v1/dmarcEvery domain with its report address and the last 30 days' totals
GET /v1/domains/{id}/dmarc?days=30One 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.

EndpointDoes
GET /v1/accountsList sub-accounts (filter with ?reference=), with domain, user and delivery counts
POST /v1/accountsCreate 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/usageEach 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}/invitationsInvite someone to its dashboard
POST /v1/accounts/{id}/api-keysCreate 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-secretIts 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/webhook settings 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 at mx.ghostparse.com with 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 at ghostparse.com the 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. …" }
StatuserrorMeaningRetry?
401UnauthorizedMissing, wrong or revoked API key.No
403domain_not_verifiedThe from domain isn't added or its SPF, DKIM and DMARC aren't verified.No
403sender_not_allowedThe from address isn't listed under the domain's Email addresses with Send on.No
402quota_exceeded, spend_capSending: your plan's email allowance (shared by sent and received email) or your spending cap is used up. See Plans & usage.After upgrading
422recipients_suppressedEvery recipient is on your suppression list (an earlier hard bounce or spam complaint). suppressed lists them.No
403policy_violationToo many recipients, or a forbidden/bulk header.No
403insufficient_scopeThe API key lacks the permission this endpoint needs (send, domains, integrations or accounts).No
404not_foundThe domain or address doesn't exist on your account.No
409domain_exists / address_existsAlready on your account.No
422invalid_domain, invalid_address, wrong_domain, duplicate_address, no_permissions, invalid_reference, invalid_webhook_urlDomains API input problems; message says exactly what's wrong.No
422too_many_domains / too_many_addresses / too_many_rulesAccount or domain limit reached.No
422pattern_cannot_send, invalid_max_message_bytes, invalid_patternAn address pattern with Send on, a size cap out of range, or a sender rule that isn't an address or domain.No
409rule_existsThat sender rule is already on the domain.No
422invalid_tag, address_not_receivingReply addresses: the tag has characters other than letters, digits, - and _, or the address isn't a receiving address on your domain.No
422invalid_statusDelivery log: unknown status filter.No
422no_receiving_address, not_receivingSample 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
404parser_not_foundparser_id isn't one of your parsers.No
422invalid_destination, invalid_ruleDestinations 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
404destination_not_found, hook_not_found, rule_not_foundNot on your account.No
422too_many_destinations, too_many_routing_rulesAn account can have 50 destinations (hooks included) and 100 routing rules.No
422package_limitAdding 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 / 422package_not_found, package_exists, too_many_packages, invalid_limit, invalid_over_limit, invalid_monthCustomer 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 / 429sending_paused, ramp_limitA 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
403not_resellerReseller features aren't on for this account, so it can't use /v1/accounts or the accounts permission.No
403account_suspendedThe account is suspended (by its reseller).No
404account_not_foundNot one of your sub-accounts (an Email-Parser-Account header or /v1/accounts/{id}).No
409secret_incompatibleSwitching to Standard Webhooks with a secret made before it was supported: rotate the secret first.After rotating
422too_many_accountsThe reseller's sub-account limit is reached.No
422plan_limitYour plan's limit on domains or team members is reached. Upgrade on the Billing page.After upgrading
422validation_errorThe body is invalid. issues lists each problem with its path.No
429daily_limit_reachedYour account's daily sending limit is used up.After it resets
429Too Many RequestsMore than 120 requests per minute for this key. Wait the number of seconds in the Retry-After header.Yes
409store_existsBigCommerce: that store is already connected.No
422invalid_store, invalid_api_tokenBigCommerce: not a store address or API path, or no token.No
422bigcommerce_errorBigCommerce refused the token (or didn't answer: 502); message says why.With a working token
409bigcommerce_token_neededBigCommerce: the store has no API token to read the order with.No
503bigcommerce_unavailableBigCommerce isn't available on this platform.No
502send_failedOur 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.

LimitValue
Outbound emails per account1,000 per rolling 24 hours
API requests per key120 per minute
Recipients per email (to + cc + bcc)50
Message size25 MB (inbound and outbound)
Domains per account20
Domain verification checks30 per minute per key
Email addresses per domain100 (patterns count as one)
Sender rules per domain200
Delivery logKept 90 days
Parsers20 per account, 30 fields each
AI extractions200 per account per day
Sample emails10 per minute
Active API keys10
Team members25
Sub-accounts per reseller500
Inbound emailNo volume limit for your listed addresses (transactional use)

Plans & usage

FreePay as you goStarterProBusiness
Price£0£0/month + usage£9/month£29/month£99/month
Emails a month (sent + received)1,0001,000 free10,00050,000250,000
AI extractions a month502505002,50010,000
Domains1 + instant address5525Unlimited
Team members25515Unlimited
Delivery log3 days30 days30 days90 days90 days
Extra emails, per 1,000Held 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 relays 503), so they retry, usually for several days. Upgrading in that time delivers it. The delivery log shows these as deferred with flags.code: "quota_exceeded" (or "spend_cap"). Sending through /v1/emails is refused with 402 and 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.

LanguageInstall
Node.js / TypeScriptnpm install @wildye/email-parser
Pythonpip install wildye-email-parser
PHPcomposer require wildye/email-parser (also sending, with retries and idempotency)
Laravelcomposer require wildye/email-parser-laravel: a webhook route that dispatches InboundEmailReceived events
Rubygem "wildye-email-parser"
Gogo get github.com/dwildman86/emailParser/sdk/go
CLInpx @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.