Email processing

EmailConnect transforms incoming emails into structured webhook payloads. This guide explains the processing pipeline from email receipt to webhook delivery.

Processing pipeline

1. Email reception

When an email arrives at your configured domain:

SMTP connection - Sender's mail server connects to mx1.emailconnect.eu
Spam check - If enabled, email is scanned for spam
Rule evaluation - Alias rules are checked (Advanced feature)
Acceptance - Email is accepted for processing

2. Parsing and extraction

EmailConnect extracts structured data from the raw email:

Headers:

From, To, CC, BCC addresses
Subject line
Date and timestamps
Message-ID and references
Custom headers (X-headers)

Body content:

HTML version (if available)
Plain text version (if available)
Both versions (configurable)

Attachments:

File names and MIME types
File sizes
Content (Base64 or S3 URL)

Envelope data (optional):

MAIL FROM address
RCPT TO addresses
Sending server information

3. Webhook delivery

The structured payload is delivered to your configured endpoint:

Payload construction - JSON payload is built
Signing - Request is signed for verification
Delivery - POST request sent to your webhook URL
Retry handling - Failed deliveries are retried

Webhook payload structure

Looking for the full field-by-field reference? See What's in your webhook payload for every field, enrichment feature, and plan availability.

Basic payload

{
  "id": "msg_abc123",
  "timestamp": "2024-01-15T10:30:00Z",
  "from": {
    "address": "sender@example.com",
    "name": "John Doe"
  },
  "to": [
    {
      "address": "support@yourdomain.com",
      "name": "Support"
    }
  ],
  "subject": "Question about my order",
  "text": "Plain text content here...",
  "html": "<p>HTML content here...</p>",
  "attachments": []
}

Full payload with all options

{
  "id": "msg_abc123",
  "timestamp": "2024-01-15T10:30:00Z",
  "from": {
    "address": "sender@example.com",
    "name": "John Doe"
  },
  "to": [
    {
      "address": "support@yourdomain.com",
      "name": "Support"
    }
  ],
  "cc": [],
  "bcc": [],
  "replyTo": {
    "address": "reply@example.com",
    "name": "John Doe"
  },
  "subject": "Question about my order",
  "text": "Plain text content...",
  "html": "<p>HTML content...</p>",
  "headers": {
    "message-id": "<abc123@mail.example.com>",
    "x-custom-header": "value"
  },
  "attachments": [
    {
      "filename": "document.pdf",
      "contentType": "application/pdf",
      "size": 125840,
      "content": "base64-encoded-content..."
    }
  ],
  "envelope": {
    "mailFrom": "bounces@example.com",
    "rcptTo": ["support@yourdomain.com"],
    "remoteAddress": "192.168.1.50",
    "clientHostname": "mail.example.com"
  },
  "spamScore": 0.2,
  "alias": {
    "id": "alias_xyz",
    "address": "support@yourdomain.com"
  }
}

Additional enrichment fields (not shown above): Payloads also include links (extracted URLs), classification (email type, confidence, signals), markdown (HTML converted to Markdown), and integrity (SHA-256 hashes). Availability varies by plan. See the full payload reference for details.

Delivery and retries

Successful delivery

A delivery is considered successful when your endpoint returns:

HTTP 200-299 status code
Response within timeout period (30 seconds)

Retry policy

If delivery fails, EmailConnect retries with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	12 hours

After 6 failed attempts, the email is marked as failed and no further retries occur.

Failure reasons

Common delivery failures:

Endpoint not reachable (network error)
Endpoint returns 4xx/5xx error
Timeout (response takes > 30 seconds)
SSL/TLS certificate errors
Payload too large for endpoint

Webhook security

Request signing

Every webhook request includes a signature header for verification:

X-EmailConnect-Signature: sha256=abc123...

Verification (Node.js):

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expected}` === signature;
}

Verification (Python):

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return f"sha256={expected}" == signature

Timestamp validation

Prevent replay attacks by checking the timestamp:

const timestamp = new Date(payload.timestamp);
const now = new Date();
const maxAge = 5 * 60 * 1000; // 5 minutes

if (now - timestamp > maxAge) {
  throw new Error('Request too old');
}

Processing order

Emails are processed in order of receipt. However, webhook delivery may complete out of order due to:

Retry delays for failed deliveries
Processing time variations
Network latency differences

If order matters for your application, use the timestamp field to sort emails chronologically.

Rate limits

Plan	Emails per minute	Concurrent webhooks
Basic	10	2
Advanced	100	10
Enterprise	Custom	Custom

Emails exceeding rate limits are queued and processed when capacity is available.

Monitoring and debugging

Email logs

View processed emails in your dashboard:

Delivery status (success/failed/pending)
Response codes from your endpoint
Retry history
Full payload preview

Webhook testing

Use webhook.site or similar services to:

Inspect payload structure
Debug parsing issues
Test before production deployment

See Webhook testing for detailed setup instructions.