Routes
Routes control how Omnivery handles inbound email for your domain. Where suppressions and allowlists govern who you can send to, routes govern what happens to mail arriving at your domain.
Inbound mail is only delivered if a route matches it. Routes are not a filter applied on top of normal delivery — they are the delivery mechanism. If you have no routes configured, or no rule matches an incoming message, the message is not accepted and the sender receives a bounce. Mail is not silently lost, but it does not reach you either.
How inbound mail reaches Omnivery
Omnivery receives inbound mail on port 25, the standard port for server-to-server mail transfer. Mail arrives at Omnivery when your domain's MX records point to our inbound servers.
If you need help with MX configuration for a domain, contact support before changing your records — inbound mail delivery depends on them, and a misconfiguration will bounce mail rather than route it.
For an explanation of why inbound mail uses port 25 while outbound submission uses port 587, see the SMTP ports guide.
What routes do and do not handle
Routes apply to normal inbound mail addressed to your domain — replies to your messages, mail sent to addresses on your sending domain, and anything else a third party sends you.
System messages are excluded. Bounce notifications, feedback loop reports and other server-to-server messages intended for your domain are handled by the platform itself and are never passed through your routes. This is deliberate: bounce processing feeds your suppression lists, and diverting or discarding those messages would break it.
You will find bounce and complaint data in Suppressions, not in your routed mail.
Setting up a route
Routes are configured per domain. Make sure the correct domain is selected in the domain selection menu at the top of the interface, then open Routes.
A route has two parts: the rules that decide which messages it applies to, and the action taken on messages that match.
Rules
Each rule matches on one of three properties of the incoming message:
| Condition | What it matches |
|---|---|
mail_from |
The sender address of the incoming message |
mail_to |
The recipient address the message was sent to |
subject |
The subject line of the incoming message |
Each condition is matched against a pattern, expressed as a regular expression. This allows anything from an exact address match to broad pattern matching across an address space.
Some practical patterns:
| Goal | Condition | Pattern |
|---|---|---|
| One exact address | mail_to |
^support@example\.com$ |
| Everything at a subdomain | mail_to |
@replies\.example\.com$ |
| All mail from one domain | mail_from |
@partner\.example\.net$ |
| Subjects containing a ticket reference | subject |
\[TICKET-[0-9]+\] |
| Automated out-of-office replies | subject |
^(Out of Office|Automatic reply) |
Remember to escape dots in domain names. An unescaped . matches any character, so support@example.com will also match support@exampleXcom.
Actions
Two actions are available:
Forward — redirects the matching message to a destination address you specify. Use this to deliver inbound mail to a real mailbox, a shared inbox, or a ticketing system's intake address. Forward does not end evaluation: later rules are still checked, and any that also match will also fire.
Stop — discards the matching message and ends evaluation. No rule below a matched stop is considered. Stop serves two purposes: dropping mail you have deliberately decided not to receive, such as automated replies, and terminating evaluation so that broader rules further down the list do not also fire. Test patterns carefully before applying stop to a broad rule.
Rule order, multiple matches, and the default action
Three behaviours determine what happens to an inbound message. All three matter, and the second one surprises people.
Rules are evaluated in order
Routes are processed from the top of the list downward. Order is part of the configuration, not an incidental detail.
Every matching rule applies
Evaluation does not stop at the first match. If three rules match an incoming message, all three actions are carried out — a message matching two forward rules is delivered to both destinations.
This is useful when you want it. It is a problem when you do not.
The common mistake: adding a specific rule for support@example.com above a broad rule for @example.com, and expecting the broad rule not to fire. It does. The message is forwarded twice, to both destinations.
A stop action aborts evaluation
The stop action is the circuit breaker. When a message matches a rule with a stop action, evaluation ends immediately and no later rule is considered — including rules that would otherwise have matched.
This is how you get exclusive routing. Place a stop after the rules that should be final for a given class of mail, and nothing further down the list will also fire.
Putting it together
| Position | Condition | Pattern | Action | Effect |
|---|---|---|---|---|
| 1 | subject |
^(Out of Office|Automatic reply) |
Stop | Auto-replies dropped, nothing below runs |
| 2 | mail_to |
^support@example\.com$ |
Forward to helpdesk | Support mail reaches the helpdesk |
| 3 | mail_to |
^support@example\.com$ |
Stop | Prevents rule 4 also firing |
| 4 | mail_to |
@example\.com$ |
Forward to catch-all | Everything else reaches a monitored mailbox |
Without rule 3, support mail would be delivered to both the helpdesk and the catch-all.
Mail matching nothing is bounced
Mail that matches no rule is rejected, and the sender receives a bounce. There is no default delivery. The same applies to a domain with no routes configured at all — every inbound message bounces.
This inverts the usual expectation. Routes do not filter mail that would otherwise be delivered; they are the only reason mail is delivered at all.
The behaviour is safe in that nothing disappears without anyone knowing — the sender is told their message was not accepted. But you will not see the message, and you will not know it was attempted unless the sender tells you. A partner emailing an address you forgot to route will conclude the address does not work.
Adding a catch-all
If you would rather receive unanticipated mail than bounce it, add a final rule that matches everything and forwards it to a monitored address, as in rule 4 above.
Place it at the bottom of the list. Because every matching rule applies, remember that it will fire for anything not already terminated by a stop action — which is exactly what you want from a catch-all, provided your specific rules end with stops.
A catch-all is worth adding when you first configure routes, at least until real traffic confirms your specific rules cover everything you receive. It turns "this address bounces" into "this arrives somewhere a human will see it".
Whether you keep it is a judgement call. Bouncing unmatched mail is a legitimate choice — it tells senders clearly that an address is not in use, and it keeps unwanted mail out entirely. A catch-all is the better default while you are still learning what your domain actually receives.
Common uses
Catching replies to transactional mail. Applications that send from a no-reply address still receive replies. A route on mail_to matching that address can forward them to a monitored mailbox instead of letting them disappear.
Routing by function. Forward support@, billing@ and sales@ on a sending domain to different destinations without running a mailbox server for the domain.
Filtering automated noise. Out-of-office replies and automated acknowledgements can be discarded with a stop action on a subject pattern, so they do not reach a human inbox.
Delivering one message to several destinations. Because every matching rule applies, two forward rules matching the same address will deliver to both. Use this to send a copy to an archive mailbox or a monitoring address alongside normal delivery.
Accepting mail you did not anticipate. A catch-all forward at the bottom of the list means unexpected mail reaches someone rather than bouncing back to the sender.
Consolidating a sending subdomain. If you send from mail.example.com, a single route matching that domain can forward anything sent back to it to your main support address.
Testing routes
Send a test message that matches your pattern and confirm it arrives at the destination before relying on the route in production.
Test more than the happy path:
- A message matching your intended rule — confirm it arrives at the right destination
- A message matching nothing — confirm you receive the bounce, and decide whether that is the outcome you want for that address
- A message matching two rules — confirm it is delivered once, not twice, unless duplicate delivery is what you intended
Unmatched mail produces a bounce, so it is visible if you look for it. Duplicate delivery is the quieter failure: the message arrives, so nothing looks broken, and the second copy is easy to miss until someone notices a shared inbox filling up. If you expect exclusive routing, confirm a stop action is terminating evaluation where you think it is.
If a route does not behave as expected, check the pattern first — an unescaped character or a missing anchor is the most common cause. Then check the position of the rule in the list.
Inbound parsing
Routes forward or discard inbound messages. They do not parse a message and deliver its contents to your application as structured data.
Inbound parsing — where an incoming message is decomposed into sender, recipient, subject, body, headers and attachments, then delivered to your backend as an HTTP POST — is on our backlog. It is not currently available.
Note that Omnivery's webhooks are a different feature: they report events on messages you have sent, such as deliveries, bounces, opens and clicks. They do not deliver inbound mail.
If inbound parsing would be useful to you, tell us. We build against real customer demand, and this feature has not yet been requested by a customer — so if you need it, saying so genuinely affects where it sits on the roadmap.