Mailer settings - configuration guide

A single guide to configure the mailer used for BREVO or SMTP providers

At a glance

• One configuration per tenant.
• GET /v1/settings/mailer (getMailerSetting) returns the current configuration, including authType. Secrets are never returned.
• PUT /v1/settings/mailer (updateMailerSetting) replaces the whole configuration.
• PATCH /v1/settings/mailer (patchMailerSetting) updates a subset of fields. An omitted SMTP password is preserved.
• Supported providers: BREVO and SMTP. For SMTP, the authentication type is returned in read as BASIC_AUTH or NONE; use BASIC_AUTH when the server expects credentials.

🟩 Read the current configuration

GET /v1/settings/mailer (getMailerSetting) returns the current mailer configuration, including the authentication type (configuration.authType) for SMTP.

Response — SMTP provider

{
  "sender": "[email protected]",
  "senderName": "Support Team",
  "configuration": {
    "provider": "SMTP",
    "host": "smtp.example.com",
    "port": 587,
    "username": "smtp-user",
    "authType": "BASIC_AUTH"
  }
}

configuration.authType is returned with one of the following values:

📘

Note: Secrets are write-only: the SMTP password and the Brevo apiKey are never returned in read. Reading the configuration back after an update will not expose them. This is why an edit screen must treat an empty password input as "keep the current value" rather than "clear the password".

🟦 BREVO configuration

Minimum fields

• sender - From email
• senderName - From display name
• configuration.provider = BREVO
• configuration.apiKey - your Brevo API key

(Note: the current PUT contract also expects a root-level apiKey. Mirror the same value there.)

Request - PUT (full)

PUT /v1/settings/mailer
Content-Type: application/json

{
  "sender": "[email protected]",
  "senderName": "Djust Commerce",
  "apiKey": "YOUR_BREVO_API_KEY",
  "configuration": {
    "provider": "BREVO",
    "apiKey": "YOUR_BREVO_API_KEY"
  }
}

Request - PATCH (rotate key only)

PATCH /v1/settings/mailer
Content-Type: application/json

{
  "configuration": {
    "provider": "BREVO",
    "apiKey": "NEW_BREVO_API_KEY"
  }
}

🟧 SMTP configuration

Minimum fields

• sender - From email
• senderName - From display name
• configuration.provider = SMTP
• configuration.host - Your SMTP server host
• configuration.port - Your SMTP server port
• configuration.username - Your SMTP server login username
• configuration.password - Your SMTP server login password
• configuration.authType = BASIC_AUTH (currently supported mode)

Note: the PUT contract still requires a root-level apiKey, which is not used by SMTP. Provide a harmless placeholder.

Request - PUT (full)

PUT /v1/settings/mailer
Content-Type: application/json

{
  "sender": "[email protected]",
  "senderName": "Support Team",
  "apiKey": "ignored-for-smtp",
  "configuration": {
    "provider": "SMTP",
    "host": "smtp.example.com",
    "port": 587,
    "username": "smtp-user",
    "password": "smtp-password",
    "authType": "BASIC_AUTH"
  }
}

Request - PATCH (rotate password)

PATCH /v1/settings/mailer
Content-Type: application/json

{
  "configuration": {
    "provider": "SMTP",
    "password": "new-smtp-password"
  }
}

✅

Tip: The stored SMTP password is preserved when configuration.password is omitted from a PATCH request. You only need to send it to change it — updating other fields (host, port, username…) carries no risk of erasing the secret.

Request — PATCH (change the host, keep the password)

PATCH /v1/settings/mailer
Content-Type: application/json

{
  "configuration": {
    "provider": "SMTP",
    "host": "smtp2.example.com",
    "port": 587
  }
}

flowchart LR
  %% Styles (Readme)
  classDef create   fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef read     fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#1e1b4b;
  classDef update   fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#0c4a6e;
  classDef decision fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef place    fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d;
  classDef sys      fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  A[🧾 PATCH /v1/settings/mailer<br>SMTP configuration] --> B{configuration.password<br>sent in the payload}
  B -->|Yes| C[🔑 Password replaced<br>by the new value]
  B -->|No| D[🔒 Stored password<br>kept unchanged]
  C --> E[✅ Other SMTP fields updated]
  D --> E

  class A sys
  class B decision
  class C update
  class D read
  class E place
  style A rx:8,ry:8
  style C rx:8,ry:8
  style D rx:8,ry:8
  style E rx:8,ry:8

✅ Validation checklist

• sender is a valid email and senderName is meaningful.
• BREVO: configuration.apiKey present (and mirrored to root apiKey for PUT).
• SMTP: host, port, username, password, authType=BASIC_AUTH.
• Use PATCH to rotate secrets without resending the full object.
• To update SMTP fields without changing the password, simply omit configuration.password — the stored value is kept.

🧯 Troubleshooting

If Djust configures this for you: share the sender, senderName, and either your Brevo API key or SMTP details (host, port, username, password, auth type). Remember: one mailer config per tenant.