@bernierllc/inbound-email-parse

Inbound email receiving, parsing, and routing service that provides webhook endpoints for all major email providers, MIME parsing with attachment handling, and rule-based routing to downstream systems.

Installation

npm install @bernierllc/inbound-email-parse

Usage

import { InboundEmailParser } from '@bernierllc/inbound-email-parse';

const parser = new InboundEmailParser({
  providers: [
    {
      provider: 'sendgrid',
      enabled: true,
      signingSecret: process.env.SENDGRID_SIGNING_SECRET
    }
  ],
  defaultRoutingRules: [
    {
      id: 'route-to-support',
      name: 'Route support emails',
      priority: 100,
      enabled: true,
      conditions: [
        { type: 'to', field: 'address', operator: 'contains', value: 'support@' }
      ],
      actions: [
        {
          type: 'route',
          destination: {
            type: 'neverhub',
            config: { eventType: 'support.email.received' }
          }
        }
      ]
    }
  ]
});

await parser.initialize();

// Process inbound email from webhook
const result = await parser.processInbound('sendgrid', webhookPayload, signature);

if (result.success) {
  console.log(`Processed email: ${result.emailId}`);
  console.log(`Routed to ${result.routed.length} destinations`);
}

Features

• Multi-Provider Support: SendGrid, Postmark, Mailgun, AWS SES, and generic MIME
• Webhook Signature Validation: Secure webhook receiving with signature verification
• MIME Parsing: Full email parsing including headers, body, and attachments
• Attachment Processing: Handle attachments with size limits, type validation, and checksums
• Rule-Based Routing: Flexible routing engine with conditions and actions
• Multi-Destination: Route single email to multiple systems simultaneously
• NeverHub Integration: Publish events and subscribe to routing updates
• Cross-Suite Compatibility: Used by Email Suite, Chat Suite, Content Management Suite, and Task Suite

Provider Capability Support

This section documents how inbound email parsing behaves across email providers, based on the canonical CAPABILITY_MATRIX in @bernierllc/email-manager.

Capability Levels by Provider

| Provider | Capability Level | Notes | |----------|-----------------|-------| | SendGrid | enhanced | Provider-level Inbound Parse webhook + platform normalization and routing | | Mailgun | enhanced | Provider-level Routes for inbound email + platform normalization and routing | | Postmark | enhanced | Provider-level Inbound webhook + platform normalization and routing | | SES | enhanced | Provider-level receiving rules via SNS + Lambda + platform normalization and routing | | SMTP | unsupported | SMTP does not provide inbound email parsing |

How It Works

• Enhanced (SendGrid, Mailgun, Postmark): The email provider receives inbound emails on your behalf and forwards the parsed content (headers, body, attachments) to a webhook endpoint. This package receives those payloads, validates signatures, performs additional MIME parsing if needed, processes attachments (size validation, checksums), and routes emails through the rule-based routing engine.

• Enhanced with extra infrastructure (SES): SES can receive inbound emails via SES receiving rules, which trigger SNS notifications or Lambda functions. The raw email is delivered to S3 or forwarded to an endpoint. This package parses the SES-specific payload format and applies the same normalization and routing as other providers.

• Unsupported (SMTP): Plain SMTP is a sending protocol; it does not provide inbound email parsing or webhook forwarding. SMTP servers can receive email, but there is no standardized webhook mechanism to forward parsed content to an application.

Degradation Behavior

When used with an unsupported provider (SMTP):

• Strategy: No automatic fallback -- SMTP does not support inbound parsing
• Impact: Inbound email features are completely unavailable
• Workaround: SMTP users who need inbound email parsing should either:
  1. Use a provider with native inbound support (SendGrid, Mailgun, Postmark, SES)
  2. Set up a separate inbound email gateway (e.g., a Postmark inbound-only configuration) alongside the SMTP sending provider
  3. Use a dedicated inbound email service that provides webhook forwarding

Override Options

The inbound email parsing capability is not marked as overridable at the provider level since it depends on provider-specific webhook formats. However, you can customize the processing pipeline:

• Custom routing rules: Define rules that match on sender, recipient, subject, headers, or body content
• Custom actions: Route parsed emails to any destination (NeverHub events, HTTP endpoints, message queues)
• Custom attachment processing: Override size limits, allowed MIME types, and storage backends

const parser = new InboundEmailParser({
  providers: [{ provider: 'sendgrid', enabled: true }],
  defaultRoutingRules: [
    {
      id: 'custom-route',
      name: 'Route invoices to billing',
      priority: 100,
      enabled: true,
      conditions: [
        { type: 'subject', field: 'text', operator: 'contains', value: 'invoice' },
      ],
      actions: [
        { type: 'route', destination: { type: 'http', config: { url: 'https://billing.example.com/inbound' } } },
      ],
    },
  ],
});

SES-Specific Notes

SES inbound email requires additional AWS infrastructure:

• SES receiving rules must be configured for the target domain
• An SNS topic or Lambda function forwards the parsed email to this package's endpoint
• Raw emails may be stored in S3 for large message handling
• MX records for the domain must point to SES inbound SMTP endpoints

API Reference

[Complete API documentation will be generated with TypeDoc]

Configuration

See Configuration Guide for detailed configuration options.

Integration Status

• Logger: integrated - Comprehensive logging for all operations
• Docs-Suite: ready - TypeDoc format
• NeverHub: required - Event publishing and service discovery

License

Copyright (c) 2025 Bernier LLC. All rights reserved.