Account Authentication

Authentication using REST API

Credentials

You must use username and password for each request. For this case, it is required to set the API username and password:

Authorization header base64 encoded: e.g. "Basic d2lraTpwZWRpYQ==" (<username>:<password>)
While the API is exposed only over HTTPS, the credentials are encrypted.

IP Allowlist (optional)

During the Onboarding phase, you can configure an additional layer of security by using IP-Allowlist to allow REST JobRequests only from defined source IPs:

IP Allowlist is optional;
By default, if no source IPs are defined, then there are no restrictions: all source IPs are allowed;
Credentials (see paragraph above) are still mandatory for each JobRequest;
Only IPv4 is supported;
All IPs have to be defined explicitly, we do not support IP-ranges (eg. 1.2.3.4/24);
A maximum of 50 IPs per IP version can be defined (50 for IPv6 and 50 for IPv4);
Source IP is provided as HTTP Header X-Real-IP: 11.22.33.44;
If the header X-Real-IP: 11.22.33.44 is not present, requests will be rejected.

Retarus recommends configuring IP Allowlisting as a complementary authentication mechanism to increase security.

Authentication using SMTP Adatper

Credentials

You are able to use username and password for each request. For this case, it is required to set the API username and password. Those credentials must be base64 encoded. There are two different authentication mechanisms supported: Plain and Login.

Authentication by Source IP

As an alternative to using credentials (username and password), authentication can be done using Source IPs for SMTP JobRequest. In this case, an Authorization header is required:

If the mail sender uses SMTP AUTH, Basic Auth is used with the provided credentials. For authentication via sender IP address a custom form of the Authorization header is used:
- Authorization: IPv4 <IP address in dotted notation>
Only IPv4 is supported

Authentication method using Credentials can still be used for the Account

Samples

Auth Plain

CODE

 ~> EHLO client.example.com
<~ 250-mail-de1.retarus.com
<~ 250-PIPELINING
<~ 250-SIZE 20000000
<~ 250-ETRN
<~ 250-AUTH PLAIN
<~ 250-AUTH=PLAIN
<~ 250-ENHANCEDSTATUSCODES
<~ 250-8BITMIME
<~ 250 DSN
~> AUTH PLAIN AHEhLXXXXZXIyAHpVcitRRRWw5XXX4
<~ 235 2.7.0 Authentication successful

Auth Login

CODE

 ~> EHLO client.example.com
<~ 250-mail-de.retarus.com
<~ 250-PIPELINING
<~ 250-SIZE 20000000
<~ 250-ETRN
<~ 250-AUTH PLAIN LOGIN
<~ 250-AUTH=PLAIN LOGIN
<~ 250-ENHANCEDSTATUSCODES
<~ 250-8BITMIME
<~ 250-DSN
<~ 250 CHUNKING
 
~> AUTH LOGIN
<~ 334 VXNlcm5hbWU6
~> eW91clVzZXJuYW1l
<~ 334 UGFzc3dvcmQ6
~> eW91clBhc3N3b3Jk
<~ 235 2.7.0 Authentication successful
 
~> AUTH LOGIN eW91clVzZXJuYW1l
<~ 334 UGFzc3dvcmQ6
~> eW91clBhc3N3b3Jk
<~ 235 2.7.0 Authentication successful