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.
Start with the troubleshooting checklist. For a new setup, choose the recipe for all incoming mail or one address.
Setup
- Add an inbound domain in Domains. For Free accounts, use a subdomain such as
inbound.example.com. - Configure that domain or subdomain's MX records to point to Postscale.
- 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). - Copy the signing secret (
whsec_…) shown in the dialog. It is only displayed once; save it in your secrets manager. - 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.
- 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.
Open Domains → your domain → Rules → Add Rule. Enter these values:
| Field | Set to |
|---|---|
| Name | All incoming mail to webhook |
| Scope | All routed aliases and catch-all recipients |
| When | All of these conditions match |
| Condition field | Sender (From) |
| Comparator | Matches (Regex) |
| Value | .* |
| Action | Webhook |
| Webhook | Your 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.
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.
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?
Open Domains → your domain → Aliases → Add Alias. To receive
support@inbound.example.com, select the inbound.example.com domain and use:
| Field | Set to |
|---|---|
| Address | support (the part before @) |
| Action | Webhook |
| Webhook | Your 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
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 see | What to do |
|---|---|
| No webhook delivery record | Check the alias or rule using the steps below. |
| A queued delivery with zero attempts | Routing already happened. Inspect the delivery's status; creating another route is not the fix. |
| A failed delivery | Inspect its HTTP status and error, correct the reported issue, then retry the failed delivery. |
| A succeeded delivery | Postscale 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.
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
| How the address receives mail | Required configuration |
|---|---|
| An exact or wildcard alias | Set action to Webhook or Both (Forward + Webhook) and select the endpoint. |
| Domain catch-all without an alias | Add the domain-wide webhook rule. |
Confirm that both the route and the selected endpoint are active, and that the
endpoint subscribes to email.received.
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.
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
| Term | Meaning |
|---|---|
| Stored email | Sender, 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 delivered | Inbound processing completed. This does not confirm an HTTP request to your webhook. |
Webhook status succeeded | The 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.
Use the In-Reply-To and References headers to match replies to
original messages and maintain conversation threads.
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.