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.
Message routing requests are sent to the Endpoint URL using a POST request. Only responses with HTTP status codes between 200 and 299 are deemed successful. Failed requests are retried six times, up to 16 minutes and 21 seconds after the initial attempt. Receiving over 100 consecutive failures from the Message Route endpoint URL will result in the Route being disabled, and you will be notified via email about this change.
Create your Message Route
- Go to the Message Routing page in your account.
- Click on the +Add Route button.
- In the Endoint URL field enter the URL where you want to receive the message routing events.
- 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 likeinfo
, or use patterns such asticket-*
to route only a subset of inbound emails. - 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.
- 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.
- Click on the +Create Route button. This will create the Route and take you to the Message Routing details page.
![Create a message route](/sites/default/files/inline-images/routing.png)
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);
The Standard Webhooks Repository includes reference implemenation libraries for working with webhooks compliant the Standard Webhoooks Spec. AhaSend Webhooks are compliant with these specs, and we recommend using these reference libraries for using AhaSend Routes within your application code, or using them as the base or example for your custom implementation.
The reference implementation has libraries for the following languages:
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:"Helvetica Neue",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 <<a href=\"mailto:[email protected]\">[email protected]</a>> 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"
}
]
}
}
Every inbound email to AhaSend is scanned for spam. The spam_score
fields indicates the spammyness of the email. You should treat any email with a spam_score
of 5 to 10 with suspicion, and any email with spam score of over 10 as outright spam.