Inbound Webhooks

Process incoming emails with real-time webhooks.

Postscale can parse incoming emails and deliver them to your application via webhooks. This enables powerful use cases like support ticket systems, reply detection, and email-based workflows.

Each accepted inbound message consumes one unit of your shared monthly email quota. Messages rejected before Postscale stores or dispatches them do not consume quota. On Free, monthly quota exhaustion is a hard cap and returns a permanent failure; temporary throughput deferrals count only if a later retry is accepted.

Receiving mail, but no webhook attempts?

Start with the troubleshooting checklist. For a new setup, choose the recipe for all incoming mail or one address.

Setup

  1. Add an inbound domain in Domains. For Free accounts, use a subdomain such as inbound.example.com.
  2. Configure that domain or subdomain's MX records to point to Postscale.
  3. From the dashboard, open Webhooks, click Add Webhook, point it at your endpoint URL, and check email.received (any other events you want are also fine: one webhook can subscribe to many).
  4. Copy the signing secret (whsec_…) shown in the dialog. It is only displayed once; save it in your secrets manager.
  5. Configure a recipient route: create an exact or wildcard alias that uses the endpoint, or enable domain catch-all and create a domain-wide webhook rule that selects it. A webhook endpoint by itself does not make an email address routable. Follow the dashboard recipe below to route all incoming mail for a domain.

For root-domain inbound processing, the domain must be configured as inbound, both, or alias, and its MX record must point to mx.postscale.io. If Google Workspace, Microsoft 365, or another mailbox provider receives mail for your root domain, keep that domain outbound in Postscale and use an inbound subdomain for webhooks.

On Free, inbound is scoped to one subdomain with two aliases/routes. Root-domain inbound, catch-all, and combined send/receive domains require a paid plan or manual review.

You can also create the webhook via API:

curl -X POST https://api.postscale.io/v1/webhooks \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/postscale-inbound",
    "events": ["email.received"]
  }'

The response body contains the webhook record and the plaintext secret. Save it then: GET /v1/webhooks will not return it again.

An org-wide webhook (shown with domain *) subscribes to events generated by configured aliases and rules across the organization. It is not a fallback recipient route and does not cause Postscale to accept arbitrary addresses.

Send All Incoming Mail to a Webhook

Use this dashboard recipe for a verified inbound-capable domain whose MX records point to Postscale. Catch-all must be available on your plan as described above.

1. Confirm the endpoint and catch-all
  • Open Webhooks. Your endpoint must be active and subscribe to email.received.
  • Open Domains → your domain → Overview. Confirm Catch-all is enabled.

Ready to continue: the domain accepts mail for addresses without an explicit alias, and your endpoint is available to select in a rule.

2. Add a rule that selects the endpoint

Open Domains → your domain → Rules → Add Rule. Enter these values:

FieldSet to
NameAll incoming mail to webhook
ScopeAll routed aliases and catch-all recipients
WhenAll of these conditions match
Condition fieldSender (From)
ComparatorMatches (Regex)
Value.*
ActionWebhook
WebhookYour existing endpoint URL

Condition to enter: Sender (From) → Matches (Regex) → .*. Use one condition. The value is a dot followed by an asterisk and matches any sender. Enter it in the rule's Value field, not the webhook endpoint's match pattern.

For a domain with no other rules, keep Priority at 100 and Stop processing subsequent rules checked. Click Create Rule and confirm the rule is active.

If this domain already has aliases or rules

This rule covers existing aliases as well as direct catch-all recipients. Its webhook action overrides the alias's default action when it is the effective matching rule. Review the evaluation order and place it after filters or exceptions that should take precedence. An earlier matching rule with Stop processing subsequent rules checked prevents it from running.

3. Send a fresh email and verify delivery

Send a new message to an address on the receiving domain, for example support@inbound.example.com. Use a fresh Message-ID.

Expected result: Activity → Operations shows a webhook delivery, your endpoint receives an email.received POST, and returns a 2xx response.

Previously stored messages are not replayed automatically. If the new message still has no delivery, work through the checks below.

Only Need One Address?

Create an exact alias instead

Open Domains → your domain → Aliases → Add Alias. To receive support@inbound.example.com, select the inbound.example.com domain and use:

FieldSet to
Addresssupport (the part before @)
ActionWebhook
WebhookYour existing endpoint URL

Save the alias and confirm it is active, then send a fresh test email. An exact alias can receive mail without domain catch-all. Matching inbound rules can still override its default action.

Mail Is Stored but There Are Zero Webhook Attempts

Likely cause: no route selects your webhook

If catch-all accepts an address with no alias and no matching rule, Postscale defaults to Store Only and creates no webhook delivery job. An active email.received endpoint with match pattern * does not change that default.

Next step: connect the recipient to the endpoint using a domain-wide webhook rule or an exact alias.

Check whether a delivery exists

Open Activity → Operations and look for a fresh test message's webhook delivery. Use its delivery status to choose the next step:

What you seeWhat to do
No webhook delivery recordCheck the alias or rule using the steps below.
A queued delivery with zero attemptsRouting already happened. Inspect the delivery's status; creating another route is not the fix.
A failed deliveryInspect its HTTP status and error, correct the reported issue, then retry the failed delivery.
A succeeded deliveryPostscale received a successful HTTP response. Check processing inside your application.

The Failed webhook deliveries panel only lists terminal failures. An empty panel alone does not establish that no attempts occurred.

API alternative: list deliveries for this endpoint

Replace {webhook_id} with your endpoint's ID and use your API key. Leave out the status filter to include all delivery statuses.

curl "https://api.postscale.io/v1/webhooks/{webhook_id}/deliveries" \
  -H "Authorization: Bearer ps_live_your_api_key"

Fix the route and test again

1. Select the endpoint in the receiving route
How the address receives mailRequired configuration
An exact or wildcard aliasSet action to Webhook or Both (Forward + Webhook) and select the endpoint.
Domain catch-all without an aliasAdd the domain-wide webhook rule.

Confirm that both the route and the selected endpoint are active, and that the endpoint subscribes to email.received.

2. Check the effective rule action

Open Domains → your domain → Rules → Test Rules. Enter the actual recipient and sample email values.

Expected result: the recipient is routable and the effective action is Webhook. If no rule matches an alias, check its fallback action instead: it should be Webhook or Both (Forward + Webhook). If the result is Store Only, Drop, or Forward, review the matching rules and their order.

Test Rules evaluates routing; it does not send an HTTP request.

3. Verify with a new message

Send a fresh email with a new Message-ID. Check Activity → Operations and your endpoint's request logs for the new delivery.

Existing stored messages are not automatically replayed. Retrying a failed webhook delivery only retries an existing delivery; it cannot create one for a message that was never queued.

What “stored” and “delivered” mean here

TermMeaning
Stored emailSender, recipient, subject, parsed text and HTML bodies, headers, and attachments successfully uploaded within the size limits are retained. Raw MIME storage is disabled by default. A webhook route also stores the message before queuing delivery.
Inbound status deliveredInbound processing completed. This does not confirm an HTTP request to your webhook.
Webhook status succeededThe webhook request received a successful HTTP response. This is separate from the inbound email's status.

Webhook Payload

When an email arrives, Postscale POSTs a JSON body like this to your endpoint:

{
  "event": "email.received",
  "timestamp": "2026-04-25T10:30:00Z",
  "email_id": "0c1f2a3b-…",
  "message_id": "<unique-id@example.com>",
  "from": "customer@example.com",
  "to": "support@yourapp.com",
  "subject": "Help with my order",
  "text": "Hi, I need help with order #12345...",
  "html": "<p>Hi, I need help with order #12345...</p>",
  "headers": [
    { "name": "Message-ID", "value": "<unique-id@example.com>" },
    { "name": "In-Reply-To", "value": "<previous-id@yourapp.com>" }
  ],
  "attachments": [
    {
      "id": "5b7d9c0e-…",
      "filename": "screenshot.png",
      "content_type": "image/png",
      "size": 45678,
      "url": "https://api.postscale.io/v1/inbound-emails/0c1f2a3b-…/attachments/5b7d9c0e-…/download"
    }
  ],
  "spf": "pass",
  "dkim": "pass",
  "auth_results": {
    "dkim": {
      "result": "pass",
      "domain": "example.com",
      "selector": "s1",
      "passed_domains": ["example.com"],
      "from_aligned": true
    },
    "spf": {
      "result": "pass",
      "domain": "example.com",
      "from_aligned": true
    },
    "dmarc": {
      "result": "pass",
      "from_domain": "example.com",
      "dkim_aligned": true,
      "spf_aligned": true
    }
  }
}

The legacy spf and dkim fields are available on all plans. Paid plans also receive auth_results, which includes the validated DKIM d= domain, selector, all DKIM domains that passed, and the computed DMARC alignment result for the MIME From domain.

Each request also carries metadata headers:

X-Postscale-Event: email.received
X-Postscale-Delivery-ID: <uuid>      (unique per attempt: use for dedup)
X-Postscale-Attempt: 1               (1-indexed; bumps on retry)
X-Postscale-Signature: t=…,v1=…      (verification: see below)

Verifying Webhooks

Every request signed by Postscale carries an X-Postscale-Signature header of the form t=<unix>,v1=<hex_hmac_sha256>. Verify it on every request to ensure the delivery came from Postscale and was not tampered with or replayed.

The official Node.js, Python, Ruby, PHP, and Go SDKs include verifiers for this signature format. The full algorithm, t= / v1= details, dual-signature handling during a rotation grace window, and SDK examples live in the main Webhooks doc: that page is shared across inbound and outbound webhooks because the verification protocol is identical.

Threading

Use the In-Reply-To and References headers to match replies to original messages and maintain conversation threads.

Attachments

Each attachment exposes an authenticated Postscale download url. Fetch it with your normal API credentials, then copy the file into your own storage if your workflow needs retention outside Postscale's retention window. Where application-side attachment encryption is enabled, this API path also handles decryption after authorization.