Mail-Plus Webhook Integration: Technical Documentation

Introduction

This documentation provides a comprehensive guide for integrating Mail-Plus’s inbound mail solution with your systems using webhooks. It covers the setup process, data transmission details, security measures, and monitoring tools available to ensure smooth operation of your mail routing system.

Webhook Setup

To receive data from Mail-Plus, you need to set up a webhook endpoint on your server. This section outlines the steps to configure your webhook for optimal integration with our service.

Endpoint Configuration

  1. URL Specification: Provide the URL of your webhook endpoint in the Mail-Plus client area. This is where we’ll send POST requests containing email data.
  2. Data Selection: In the client area, specify which data elements you want to extract from incoming emails. Available options include:
  • Timestamp
  • Mail header
  • Mail body
  • Extracted subject
  • From address
  • To address
  • BCC address
  • SPF verification results
  • DKIM verification results
  • Spam assessment
  • IP address of the sending server
  1. HTTP Method: Mail-Plus exclusively uses POST requests to send data to your webhook. Ensure your endpoint is configured to handle POST requests.

Server Requirements

Your webhook server should be capable of:

  • Accepting HTTPS connections
  • Processing JSON payloads
  • Responding with appropriate HTTP status codes

Data Extraction and Transmission

When an email is received by Mail-Plus, we extract the specified data and transmit it to your webhook endpoint. This section details the format and content of these transmissions.

Data Format

Mail-Plus sends data to your webhook as a JSON object. The content type header is set to application/json to indicate this format.

Sample JSON Payload

{
  "timestamp": "2023-09-19T14:30:00Z",
  "header": {
    "Message-ID": "<[email protected]>",
    "Date": "Tue, 19 Sep 2023 14:30:00 +0000",
    "From": "[email protected]",
    "To": "[email protected]",
    "Subject": "Important Update"
  },
  "body": "This is the content of the email...",
  "subject": "Important Update",
  "from": "[email protected]",
  "to": "[email protected]",
  "bcc": "[email protected]",
  "spf": "pass",
  "dkim": "pass",
  "spam_score": 0.1,
  "ip_address": "192.0.2.1"
}

Note: The actual content and structure of the JSON payload will depend on the data elements you’ve selected for extraction in your webhook configuration.

Handling Large Payloads

For emails with large attachments or body content, consider implementing pagination or chunked transfer encoding in your webhook to handle potentially large JSON payloads.

Request Verification

To ensure the authenticity of incoming webhook calls, Mail-Plus provides several verification methods. Implementing one or more of these methods is crucial for maintaining the security of your mail processing system.

Reverse DNS Verification

  1. Perform a reverse DNS lookup on the IP address of the incoming request.
  2. The result should be a subdomain ending with mail-plus.com.
  3. Resolve this subdomain to verify it points back to the original IP address.

Example Python code for reverse DNS verification:

import socket

def verify_mail_plus_request(ip_address):
    try:
        hostname = socket.gethostbyaddr(ip_address)[0]
        if hostname.endswith('mail-plus.com'):
            resolved_ip = socket.gethostbyname(hostname)
            return ip_address == resolved_ip
    except socket.herror:
        return False
    return False

IP Whitelist

  1. Access the Mail-Plus client area to obtain the list of IP addresses used for outgoing webhook calls.
  2. Configure your firewall or application to only accept incoming webhook requests from these IP addresses.

Example Nginx configuration for IP whitelisting:

location /webhook {
    allow 192.0.2.1;
    allow 192.0.2.2;
    allow 192.0.2.3;
    deny all;

    proxy_pass http://backend;
}

Enhanced Security Options

For clients requiring additional security measures, Mail-Plus offers advanced options to further protect your webhook integrations.

VPN Connection

To enable calling non-public URLs and enhance overall security, you can connect your webhook server to our VPN. This method ensures that all traffic between Mail-Plus and your server is encrypted and travels through a private network.

To set up a VPN connection:

  1. Contact Mail-Plus support to request VPN access.
  2. We’ll provide you with VPN credentials and configuration files.
  3. Set up the VPN client on your webhook server using the provided information.
  4. Update your webhook URL in the Mail-Plus client area to use the private IP address assigned within the VPN.

Custom SSL Certificates

For scenarios where our servers cannot connect to your webhook without a specific certificate, you can provide an X.509 certificate to be used with your webhook.

To use a custom SSL certificate:

  1. In the Mail-Plus client area, navigate to the webhook configuration section.
  2. Choose one of the following options:
    a. Select an SSL certificate previously added to Key Master.
    b. Manually enter an SSL certificate in PEM format.
  3. Save the configuration.

When a custom certificate is provided, Mail-Plus builds a custom SSL context for requests made to your webhook. This bypasses any other JDK keystores and certificate authority chains for this specific request.

Logging and Monitoring

Mail-Plus provides tools for monitoring and troubleshooting your webhook integrations. This section covers the available options for accessing log files and exporting data.

Client Area Logs

You can view log files directly in the Mail-Plus client area. These logs provide information about webhook calls, including timestamps, response codes, and any errors encountered.

Exporter Application

For more detailed analysis or integration with your own monitoring tools, Mail-Plus offers an exporter application. This tool allows you to download log data and webhook call history.

To use the exporter:

  1. Download the exporter application from our secured Git repository.
  2. Run the exporter using the following command structure:
mp-export --uuid $uuid [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--limit N] [--page N]

Parameters:

  • uuid: The ID of the configured client webhook (required)
  • from: Start date for the export (optional)
  • to: End date for the export (optional)
  • limit: Maximum number of records to export (optional)
  • page: Page number for paginated results (optional)

Example usage:

mp-export --uuid 123e4567-e89b-12d3-a456-426614174000 --limit 100

This command exports the last 100 log entries for the specified webhook.

Certificate Management

Mail-Plus uses various certificates for signing data, encrypting communications, and securing API endpoints. You can access all the certificates used by Mail-Plus on our PKI (Public Key Infrastructure) page.

To download our certificates:

  1. Visit https://pki.mail-plus.com/
  2. Navigate to the appropriate section for the certificate you need (e.g., API Encryption, Data Signing)
  3. Download the certificate in the required format (typically PEM or DER)

It’s recommended to periodically check this page and update your local copies of our certificates to ensure continued secure communication.

Troubleshooting

This section provides guidance on common issues you might encounter when setting up or using Mail-Plus webhooks.

Common Issues and Solutions

  1. Webhook Not Receiving Data
  • Verify the webhook URL in your Mail-Plus configuration
  • Check your server’s firewall settings
  • Ensure your server can handle POST requests
  1. Invalid JSON Errors
  • Verify that your endpoint can handle large JSON payloads
  • Check for any character encoding issues in your processing logic
  1. Certificate Errors
  • Ensure you’re using the latest certificates from our PKI page
  • Verify that your server’s SSL/TLS configuration is up to date
  1. High Latency in Webhook Calls
  • Consider using our VPN option for improved performance
  • Check your server’s resources and network connection

Getting Support

If you encounter issues not covered in this documentation or need additional assistance, please contact Mail-Plus support. When reaching out, please provide:

  • Your webhook UUID
  • Relevant log entries or error messages
  • A description of the expected vs. actual behavior

By providing this information, you’ll help our support team assist you more efficiently.

This documentation aims to provide a comprehensive guide to integrating Mail-Plus webhooks into your systems. As our service evolves, we’ll update this documentation to reflect new features and best practices. Always refer to the latest version of this guide when implementing or troubleshooting your webhook integration.