Mailer settings - configuration guide

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

At a glance

• One configuration per tenant.
• PUT /v1/settings/mailer replaces the whole configuration.
• PATCH /v1/settings/mailer updates a subset of fields.
• Supported providers: BREVO and SMTP (SMTP currently supports BASIC_AUTH).

🟦 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"
  }
}

✅ 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.

🧯 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.