Breadcrumbs

Secure Email Gateway Configuration API

Retarus Secure Email Gateway configuration API lets administrators manage directory administration with API-based user provisioning and key security lists programmatically so that Secure Email Gateway settings can be integrated into existing automation workflows.

The new configuration API provides REST endpoints for managing directory administration and allowlist and blocklist entries used by the Secure Email Gateway’s protection engines. It is designed to complement configuration through the myEAS portal and will be continuously expanded to cover additional Secure Email Gateway configuration areas over time.

API capabilities

With the initial release, the API supports user creating, updating, and deleting allowlist and blocklist entries that influence multiple protection layers. This has been extended with user provision. You can centrally manage list entries for:

API-based user provisioning

This feature is available as part of the Retarus Secure Email Gateway Configuration API. The documentation focuses on the administrative setup and the recommended implementation order. The documentation will be updated continuously as the feature set and API coverage are expanded.

This manual describes how to use API-based provisioning for domains, users, aliases, relays and address rewriting in Retarus Secure Email Gateway. The Configuration API complements administration in myEAS and is intended for repeatable and automatable configuration tasks.

Purpose

API-based provisioning is intended for customers who want to manage directory data and routing-related assignments without using the classic DirSync process. The Secure Email Gateway documentation already separates directory management, advanced routing and portal administration into distinct administrator topics, which also fits this API-based model.

Use API-based provisioning in the following cases:

  • Automated user lifecycle management.

  • Alias-based recipient mapping.

  • User-level or domain-level relay and rewrite exceptions.

  • Migration from file-based synchronization to API-based provisioning.

Before you start

API-based provisioning should only be used after the basic Secure Email Gateway service setup is complete. Domain onboarding, mail flow design and service activation should already be defined before directory objects and routing settings are maintained through the API.

Before implementation, define the following:

  • The authoritative source for domains and users.

  • The synchronization model, for example initial full sync and later delta updates.

  • The ownership of aliases, relays and rewrite rules.

  • The retry and rollback handling for failed updates.

Configuration areas

The following API areas are relevant for administration:

Use the following order for implementation:

  1. Create or maintain domains.

  2. Create or maintain users.

  3. Add aliases where required.

  4. Create relay objects where required.

  5. Assign relay or rewrite rules on domain or user level.

Always create domains before users. This avoids dependency issues during provisioning and matches the expected object order for administration.

Use case 1: Provision and manage users

Use this workflow when Secure Email Gateway should reflect the valid recipient population of one or more managed domains. The goal is to create, update and remove users consistently through automation instead of maintaining them manually.

Recommended process:

  1. Ensure that the required domain exists.

  2. Create the user entry.

  3. Update the user entry when the source system changes.

  4. Remove obsolete users according to the customer’s retention policy.

Administrative guidance:

  • Use one source of truth for user lifecycle data.

  • Keep identifiers stable.

  • Log failed updates for retry handling.

Use case 2: Primary user and alias mapping

Use this workflow when additional recipient addresses should resolve to one primary user. This is useful for role addresses, legacy addresses and migration scenarios.

Recommended process:

  1. Provision the primary user.

  2. Create the alias assignment.

  3. Validate that the alias does not conflict with an existing user.

  4. Remove obsolete aliases before deleting the primary user, unless a replacement mapping exists.

Administrative guidance:

  • Use aliases only for additional accepted recipient addresses.

  • Do not replace real user lifecycle management with alias objects.

  • Review long-lived aliases regularly.

Use case 3: Rewriting and relaying

Use this workflow when mail for a user or a complete domain must be relayed or rewritten according to a defined delivery design. The related Secure Email Gateway documentation already positions advanced routing and rewriting as an administrator topic for hybrid or migration scenarios.

Recommended process:

  1. Create the required relay object.

  2. Decide whether the assignment belongs on domain level or user level.

  3. Configure the relay or rewrite assignment.

  4. Test the behavior with representative recipient addresses before applying bulk changes.

Administrative guidance:

  • Prefer domain-level assignments when the rule applies to most recipients in a domain.

  • Use user-level assignments only for justified exceptions.

  • Keep exception rules easy to trace and document their ownership.

Authentication and access

Use the Retarus developer portal as the authoritative source for authentication details, credentials and endpoint definitions. The public Configuration API documentation points administrators to the developer portal for the OpenAPI specification, schemas and examples.

Publicly relevant access topics:

  • Request API credentials from customer support.

  • API credentials are described in the developer portal.

  • Dedicated accounts with granular permissions can be used for automation scenarios.

  • The exact token handling must follow the current API documentation.

  • Customer source IPs may need to be allowlisted depending on the gateway configuration.

Migration from DirSync

The Retarus DirSync documentation describes the legacy synchronization model as a separate service for transferring directory data into Retarus systems. API-based provisioning should therefore be treated as a separate provisioning path.

Recommended migration approach:

  1. Align migration plan with account management to avoid implications on billing.

  2. Provide the complete directory via the API.

  3. Validate the API-based data set.

  4. Stop using the legacy synchronization model for the same object scope.

  5. Remove obsolete operational dependencies after the migration has been confirmed.

Do not use multiple provisioning methods for the same object scope unless the setup has been explicitly validated for the customer environment. A single authoritative provisioning path avoids conflicts and unexpected overwrites.

Operations

Integrate API-based provisioning into an existing administrative change process instead of using isolated scripts. A staged approach reduces risk: first domains, then users, then aliases and optional routing assignments.

Recommended operating model:

  • Start with a full synchronization.

  • Use delta updates afterwards.

  • Validate object dependencies before assignments are created.

  • Test bulk changes in a controlled rollout window.

  • Monitor failed or partial updates and define a retry strategy.

This enables use cases such as:

  • Automating list maintenance from SIEM/SOAR, ticketing, or CI/CD pipelines.

  • Synchronizing central security policies across multiple customers, domains, profiles, or users.

More information

The Retarus developer portal provides comprehensive documentation for the Secure Email Gateway Configuration API. This includes the full OpenAPI specification with detailed descriptions of all available operations, parameters, request and response schemas, and examples.