Inbound email intake

Porchlight can accept demand-led inbound email into the lead handoff queue. This is for forwarded website contact forms and direct buyer inquiries sent to a Porchlight-owned alias such as leads+customer@getporchlight.ai.

What this does

1. A mail provider receives email for the configured alias.
2. The provider sends a signed JSON webhook to /api/channels/email.
3. Porchlight verifies the signature, matches the recipient alias to an org, and rejects obvious non-lead messages such as autoresponders, bounces, newsletters, and no-reply sender mail.
4. Porchlight extracts sender, reply-to, subject, body, phone/email, source form fields, product or service intent, service area, timeline, budget hints, and source URL when present.
5. Porchlight creates or updates the contact, conversation, lead, handoff, and source metadata using source: email_forward.
6. Operators are notified through the normal new-lead email path when notification settings allow it.

Provider payload

Send JSON with these fields:

{
  "messageId": "provider-message-id",
  "from": { "email": "buyer@example.com", "name": "Jane Buyer" },
  "replyTo": { "email": "buyer@example.com", "name": "Jane Buyer" },
  "to": ["leads+hudson@getporchlight.ai"],
  "subject": "Sauna install estimate",
  "text": "Name: Jane Buyer\nPhone: 555-222-3333\nProject: outdoor sauna\nMessage: Looking for a site visit in Hudson.",
  "headers": {
    "message-id": "<provider-message-id>",
    "auto-submitted": "no"
  }
}

from, replyTo, and to may be strings or objects. text is preferred; html is accepted as a fallback.

Signature

Set PORCHLIGHT_INBOUND_EMAIL_WEBHOOK_SECRET in the deployment environment. Each request must include:

• x-porchlight-email-timestamp: Unix epoch milliseconds.
• x-porchlight-email-signature: sha256= plus the HMAC-SHA256 hex digest of {timestamp}.{rawBody} using the shared secret.

Requests outside the five-minute timestamp window or with an invalid signature are rejected.

Operator configuration

In Settings > Integrations, enable inbound email and set the literal Porchlight-owned alias for the org. V1 intentionally supports exact aliases first. Wildcard patterns are supported in code, but customer-domain aliases should wait until threading, deliverability, and ownership checks are proven.

Guardrails

• No automatic email replies are sent from this intake path.
• The route creates a pending handoff so a human reviews and responds.
• Provider authenticity is required before parsing.
• Obvious non-lead/system messages are rejected before records are created.
• Gmail/Outlook OAuth, full inbox sync, customer-domain aliases, sender identity, threading, and deliverability tuning are later scope.