Managing Inbound Emails with Message Routing on AhaSend

Message routing is an essential mechanism for efficiently managing and directing inbound email traffic within your applications. By leveraging message routing, businesses can automatically parse and direct incoming emails to appropriate endpoints based on predefined rules or criteria. This functionality is particularly valuable for organizations looking to automate responses, categorize incoming messages, or integrate email content directly into databases, customer relationship management (CRM) systems, ticketing systems, or other application-specific workflows. By setting up message routing, developers can ensure that each email is promptly processed and acted upon, thereby enhancing responsiveness and operational efficiency.

How do Message Routes work in AhaSend?

At AhaSend, a Message Route is a URL you set up to integrate with our systems. This setup allows you to receive real-time notifications for inbound emails directed to specific addresses within your AhaSend domains on the specified URL in a HTTP POST request.

You can designate specific email addresses to route to this URL. The recipient email address field supports wildcards, allowing you to use entries like * to route all emails sent to a particular domain, or ticket-* to route only those emails sent to addresses beginning with ticket-.

To use Message Routing, it's essential that the domains you choose have their MX records pointed to AhaSend. This configuration ensures that AhaSend captures the emails sent to your addresses, as without the correct MX record, AhaSend cannot receive these emails.

Create your Message Route

1. Go to the Message Routing page in your account.
2. Click on the +Add Route button.
3. In the Endoint URL field enter the URL where you want to receive the message routing events.
4. In the Recipient email address field, enter the email address you want to route, and select the domain from the dropdown menu. This field supports wildcards, enabling broad or targeted routing options. For instance, entering * will route all emails received for the selected domain to your endpoint URL. Alternatively, you can specify addresses a single email address like info, or use patterns such as ticket-* to route only a subset of inbound emails.
5. Use the Attachments field to choose whether you want to receive attachments as part of the Message Routing request at your endpoint. Please note that enabling this option can significantly increase the payload size.
6. The Strip replies field allows you to choose whether to receive the last reply in an email thread separately in the payload. When enabled, the system attempts to isolate replies and signatures from the plain-text message body and sends them separately from the main body.
7. Click on the +Create Route button. This will create the Route and take you to the Message Routing details page.

Test your Message Route

After creating your Message Route, test it by clicking the "Send Test Event" button on the Message Route details page. This will send a sample Message Routing payload to your endpoint within seconds. Use RequestBin to quickly generate a URL for testing the Message Routing endpoints.

Securing your Message Routes

Message Routing events, just like webhooks, are just HTTP requests from an unknown source, so verifying the authenticity of webhooks is a requirement for any secure message routing implementation.

AhaSend follows the Standard Webhooks specification for handling security of Message Routing payloads by providing you with a Route Secret as a pre-shared key, and signing the routing payload using HMAC with the Route Secret. You can use this secret to verify the Message Routing request.

With each routing request, you will receive the following three headers:

• webhook-id: You can use the value of this header as a unique identifier for the routing event. This unique identifier is associated with a specific event trigger and remains consistent across multiple retries of a failed routing request. It is commonly used as an idempotency key, allowing the recipient to process a specific event just once, regardless of multiple transmissions due to malicious intent, errors, or network issues.
• webhook-signature: The signature of the routing payload. You can use the Route Secret for verifying this signature.
• webhook-timestamp: Integer unix timestamp (seconds since epoch) of the time when the routing event was sent.

To learn more about verifying the route signature please refer to the Verifying Webhook Authenticity section of the Standard Webhooks specification.

We recommend using the official Standard Webhooks libraries for verifying signatures. You can perform the verification by initializing the webhook object provided by the library with the Route Secret shown in the Route details page, and passing the raw JSON payload and the HTTP headers to the Verify (or VerifyWebhook) method of the webhook object. If the verification fails, you will receive an error (or an exception is thrown).

import (
    standardwebhooks "github.com/standard-webhooks/standard-webhooks/libraries/go"
)
wh, err := standardwebhooks.NewWebhookRaw(routeSecret)
err = wh.Verify(routingRequestPayload, routingRequestHeaders)

$wh = new \StandardWebhooks\Webhook::fromRaw($routeSecret);
$wh->verify($routingRequestPayload, $routingRequestHeaders);

Message Route payload structure

AhaSend uses the full payload structure as recommended by the Standard Webhooks specification. An example payload for a message routing event looks like this:

{
    "type": "message.routing",
    "timestamp": "2024-05-07T10:41:45.026792973+02:00",
    "data": {
        "id": "SAMPLE-ID",
        "from": "Someone <[email protected]>",
        "reply_to": "",
        "to": "[email protected]",
        "subject": "Re: Test message from AhaSend",
        "message_id": "<[email protected]>",
        "size": 17422,
        "spam_score": 0,
        "bounce": false,
        "cc": "",
        "date": "Sun, 5 May 2024 20:47:51 +0200",
        "in_reply_to": "<[email protected]>",
        "references": "<[email protected]>",
        "auto_submitted": "",
        "html_body": "<div dir=\"ltr\">This is a sample email to test message routing.<div><div><div dir=\"ltr\" class=\"gmail_signature\" data-smartmail=\"gmail_signature\"><div dir=\"ltr\"><div dir=\"ltr\"><div dir=\"ltr\"><div dir=\"ltr\"><div dir=\"ltr\"><div dir=\"ltr\"><div dir=\"ltr\"><div style=\"color:rgb(34,34,34);font-family:arial,sans-serif;background-color:rgb(255,255,255)\"><br><div style=\"color:rgb(33,33,33);font-family:&quot;Helvetica Neue&quot;,Helvetica,Arial,sans-serif;line-height:20px\"></div></div></div></div></div></div></div></div></div></div></div><br></div></div><br><div class=\"gmail_quote\"><div dir=\"ltr\" class=\"gmail_attr\">On Sun, May 5, 2024 at 7:57 PM &lt;<a href=\"mailto:[email protected]\">[email protected]</a>&gt; wrote:<br></div><blockquote class=\"gmail_quote\" style=\"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex\">This is a test message sent via AhaSend. <br>\r\n</blockquote></div>\r\n",
        "plain_body": "This is a sample email to test message routing.\r\n\r\n\r\n\r\nOn Sun, May 5, 2024 at 7:57 PM <[email protected]> wrote:\r\n\r\n> This is a test message sent via AhaSend.\r\n>\r\n",
        "reply_from_plain_body": "This is a sample email to test message routing.",
        "attachments": [
            {
                "filename": "logo.jpg",
                "content_type": "image/jpeg",
                "content_id": "f_lvtu5ouk0",
                "data": "base64 encoded attachment data"
            }
        ]
    }
}