Skip to main content
Skip table of contents

Annex: Actions

The following actions are available (details in the following chapters):

  • Add BCC Recipient

  • Address Rewrite: Sender or Recipient

  • Block Email: Quarantine (Inbound only), Delete (Inbound only), Discard

  • Relay To Host

In the following sections, all actions are listed with a description, JSON format and the allowed values.

  • Example text/values are written in italic.

  • Alternative keys/operators/values are separated by “|”.

Add BCC Recipient

With this action, up to five BCC (“Blind Carbon Copy”) recipient addresses may be added to an email. These additional recipients in the “BCC” header are invisible for other recipients of the email. BCC recipients may be used for compliance reasons.

JSON format (Inbound)

JSON
{
  "action": "BccRecipient",
  "values": [
    "address1@domain1.com",
    "address2@domain2.com"
  ]
}

JSON format (Outbound):

JSON
{
  "action": "BccRecipientOutbound",
  "values": [
    "address1@domain1.com",
    "address2@domain2.com"
  ]
}

Valid entries

  • Between one and five BCC addresses (values) may be configured.

  • See email address and domain validation patterns listed here: 7.2 Email address and domain
    validation regex patterns.

“Add BCC recipient” as action for Inbound emails in combination with Retarus Email Continuity

The “Add BCC recipient” action is automatically disabled if the Continuity switch-over (failover routing) has been activated for the main recipient. Also, failover routing isn’t working for the BCC recipient if it is not activated for the main recipient of an email.

Address Rewrite: Sender or Recipient Rewrite

General functionality

The Address Rewrite action is used to do automatic rewriting of sender or recipient email addresses or domains for Inbound or Outbound traffic. Consequently, the email is sent to another mailbox or appears to have been sent from another address. This feature is particularly useful for hybrid email environments or migration scenarios (M365 migration, company mergers or acquisitions, carve-outs etc.), where you would like to use dedicated addresses/domains for Outbound traffic in order to keep your reputation and make sure that Inbound emails still reach the recipient using a different, “internal” address.

By default, only the SMTP/Envelope addresses are rewritten, but it is also possible to include the corresponding MIME headers, displayed to the recipient of an email: MIME From, MIME To etc.

The following rewrites can be configured for In- and Outbound traffic; the most common use case is to rewrite the sender address for Outbound and the recipient address for Inbound traffic:

  • Sender Rewrite (address or domain):

    • SMTP/Envelope From

    • Optional header rewrite: MIME From, Reply-To, Sender, Return-Receipt-To, Disposition-Notification-To, Resent-From, Resent-Sender (Return-Path is not rewritten, as this could lead to SMTP-related problems)

  • Recipient Rewrite (address or domain):

    • SMTP/Envelope To

    • Optional header rewrite: MIME To, CC

Depending on the use case, address rewriting can be set up in two different ways:

  • Address rewriting via custom rules, created and managed via the myEAS portal (as any other actions described in this document). The first possibility is used if you have only few, static rewrites to manage (e.g. domain rewrite only), or if you would like to react instantly by creating a new rule.

  • Address rewriting via automated file sync in the backend. This possibility is used if you have large numbers of address rewrites to configure that change dynamically.

If for the same address and direction, an Address Rewrite by custom rule and by file sync are configured, the custom rule wins. The two different possibilities are described in detail in the following sections.

Address rewriting via custom rules (myEAS portal)

If you have only few static rewrites, you may set up a custom rule via the myEAS portal using the dedicated “Address Rewrite” action of the Predelivery Logic, just as described in this document for all other actions.

JSON format (Inbound)

JSON
{
  "action": "AddressRewrite",
  "reference": "Recipient" | "Sender",
  "scope": "Address" | "Domain",
  "value": "foo@bar.de" | "bar.de",
  "IncludeHeaders": "Yes" | "No" (default value: Yes)
}

JSON format (Outbound)

JSON
{
  "action": "AddressRewriteOutbound",
  "reference": "Recipient" | "Sender",
  "scope": "Address" | "Domain",
  "value": "foo@bar.de" | "bar.de",
  "IncludeHeaders": "Yes" | "No" (default value: Yes)
}

Valid entries

See email address and domain validation patterns listed here: Annex: Validation regex patterns and examples.ns

For Outbound Sender Rewrite and Inbound Recipient Rewrite, the target domain has to belong to your Retarus account (see details below).

Please note the following:

  • For large, dynamic lists of users and their rewrite target addresses, the automated file sync should be used. See Address Rewriting via file sync (backend).

  • If for the same address and direction, an Address Rewrite by custom rule and by file sync are configured, the custom rule wins.

  • Inbound Recipient Rewrite: Target domain has to belong to your Retarus account, forwarding Inbound emails to an external address isn’t possible. In order to avoid errors during processing (Inbound Recipient Rewrite with external/outbound target), an address/domain rewrite is only executed if the target domain belongs to your Retarus account.
    Therefore, for those rewrite configurations, you have to make sure that the rewrite target domain is registered at Retarus. This can be done by adding it via the EAS portal (see Email Security Admin Documentation). You don’t have to specify a relay host or any other information, if you don’t want Retarus to actually accept emails for this domain.

  • Inbound Recipient Rewrite: Original address might be visible in NDRs: Independently from the address rewrite feature, in rare cases, a customer MTA might reject an Inbound email coming in from Retarus. This isn’t very likely as Retarus already accepted the original email, but might be possible for example if the mailbox storage space is exceeded at the customer infrastructure. In this case, the original sender of the email receives a Non-Delivery Report (NDR) stating the reason of the rejection. If the recipient address had been rewritten by the Retarus Inbound Address Rewriting service, the rewritten address is displayed in the NDR visible to the sender instead of the address that he originally was writing to.

  • Outbound Sender Rewrite: Target domain has to belong to your Retarus account: In order to avoid spoofing (Outbound Sender Rewrite with foreign domain), an address/domain rewrite is only executed if the target domain belongs to your Retarus account. Therefore, for those rewrite configurations, you have to make sure that the rewrite target domain is registered at Retarus. This can be done by adding it via the EAS portal (see Email Security Admin Documentation). You don’t have to specify a relay host or any other information, if you don’t want Retarus to actually accept emails for this domain.

  • Outbound Sender Rewrite: Recipient addresses on To/CC are rewritten implicitly: When configuring an Outbound sender rewrite, you normally don’t think of the case that one of your users might put a colleague in the To or CC header of an Outbound email. These recipient addresses would normally not be rewritten when simply configuring an Outbound Sender Rewrite. Therefore, the original domain would be visible to the communication partner and he would reply to this address as well (which might not even be configured to accept external emails). In order to avoid this unwanted behavior, an implicit recipient rewrite has been implemented: If an Outbound sender rewrite is configured for the addresses in the To and CC headers, these addresses are rewritten as well (if the header rewrite is configured at all).

Address rewriting via file sync (backend)

For dynamic lists of large numbers of users and their rewrite target addresses, address rewriting can also be used via automated file sync in the backend.

By default, only the SMTP/Envelope addresses are rewritten, but it is also possible to include the corresponding MIME headers, displayed to the recipient of an email: MIME From, MIME To etc.

Typical use cases include migration scenarios, company mergers, acquisitions or carve-outs, where you would like to use dedicated addresses for Outbound traffic in order to keep your reputation and make sure that Inbound emails still reach the recipient using a different, “internal” address.

The service rewrites email address or domains based on a mapping list provided by the customer (e.g. by sftp upload). An automatic synchronization in regular intervals can be implemented.

In this case, the Predelivery Logic rules via myEAS portal are not required and the address rewriting is not visible or manageable there. For Address Rewriting via file sync, there is no self-service possibility to activate or configure the service inside the myEAS portal.

If you would like to use address rewriting via file sync (or use it already), contact the Retarus Support, your Service Implementation Engineer, or Technical Consultant.

When activated, a mapping file has to be provided. If multiple rewrites (e.g. Outbound sender and Inbound recipient rewrite) shall be configured, one file is required for every combination of direction and entity. The filenames can be chosen freely, but ideally, they state the direction and entity to be applied, e.g. “outbound_sender_rewrite.map”.

The mapping files have to contain email addresses (domain only is not possible) and have the following structure (one rewrite per line; whitespaces are eliminated automatically when processing the file):
originaladdress@originaldomain.com:rewrittenaddress@rewrittendomain.com

Apart from the mapping files that are synchronized with Retarus by sftp upload, the information is required if headers shall be rewritten or only the envelope To/From.

For address rewriting via file sync, the same restrictions and notes as for the solution via custom rules apply. Therefore, please also check the notes in Address Rewriting via custom rules.

Block Email: Quarantine (Inbound only), Delete (Inbound only), Discard

With this action, an email may be blocked. There are three different ways available for configuration:

  • Quarantine: This action is available for Inbound traffic only. The email is put into the recipient’s user quarantine. It is listed in the user’s Email Security Report (digest) and in the online quarantine the same way as for example spam emails, but with a different classification (quarantine reason) called “Custom Rule” (Threat Level 2 of 5). Emails with this quarantine reason may be released by the recipient or the administrator and the sender address may be added to the user’s AntiSpam Block- or Allowlist.

  • Delete: This action is available for Inbound traffic only. The email is deleted, but mentioned in the user’s digest and in the online quarantine the same way as for example virus-infected emails, but with the classification (quarantine reason) “Custom Rule” (Threat Level 2 of 5). Like emails that have been rejected due to a virus finding, deleted emails may NOT be released by the recipient or the administrator (but the sender address may be added to the user’s AntiSpam Block- or Allowlist). No NDR is generated for the sender.

  • Discard: This action is available for In- and Outbound traffic. The email is discarded silently, so it is not mentioned in the digest nor in the online quarantine and it may NOT be released. No NDR is generated for the sender.

In the Inbound processing chain at Retarus There are several filters in front of the Policy Engine. In this case, this means that an email might be quarantined (e.g. due to a high spam rating) before it even reaches the Policy Engine. If an email has been quarantined (with a different quarantine reason) already, the quarantine/delete/discard action will not be applied.

JSON format (Inbound)

JSON
{
  "action": "BlockEmail",
  "type": "Quarantine" | "Delete" | "Discard"
}

JSON format (Outbound)

JSON
{
  "action": "BlockEmailOutbound",
  "type": "Discard"
}

Relay To Host

With this action, an email may be routed to a defined relay host.

For dynamic lists of large numbers of users and their relay targets, Retarus User-Based Routing (UBR) is better suited than the Predelivery Logic.

If you would like to use UBR (or use it already), contact the Retarus Support or your Service Implementation Engineer. The “Relay To Host” action will override the target host specified in the UBR transport table, which also leads to the email being delivered by another MTA with a different IP address. Messages will be sent out using enforced TLS.

JSON format (Inbound)

JSON
{
  "action": "RelayToHost",
  "value": "foo.bar:25"
}

JSON format (Outbound)

JSON
{
  "action": "RelayToHostOutbound",
  "value": "foo.bar:25"
}

Valid entries

Host names or IP v4 addresses, with optional port. Value matching for relay host addresses is NOT case-sensitive, so it doesn’t matter if you are using capital or small letters.

Details see relay host validation pattern listed here: Annex: Validation regex patterns and examples.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.