16.1.1.26. SMTP server endpoints

The SMTP-server REST API manages mail server definitions used by privacyIDEA to send email — for the Email, for SMS tokens with an SMTP-to-SMS gateway, for the password recovery flow, for event notifications, and for the user-self-registration flow. See SMTP server configuration for the conceptual chapter.

All endpoints require admin authentication. Read access is gated by the admin policy action smtpserver_read; create, update, delete and the test send are gated by smtpserver_write.

POST /smtpserver/(identifier)

Create or update an SMTP server definition. If a definition with the given identifier already exists it is updated; otherwise it is created.

Requires admin authentication and the policy action smtpserver_write.

Parameters:

  • identifier – path component, the unique name of the definition.

JSON Parameters:

  • server – hostname or IP of the mail server (required).

  • port – TCP port of the mail server, default 25.

  • username – SMTP auth user. Empty string disables auth.

  • password – SMTP auth password (stored encrypted).

  • sender – From: address used when sending mail through this server.

  • tls – True to use STARTTLS, False (default) for plain.

  • timeout – socket timeout in seconds, default 10.

  • enqueue_job – if True, mail is queued via the privacyIDEA job queue instead of being sent inline. Default False.

  • description – free-form description.

  • smime – if True, outgoing mail is S/MIME-signed using the configured key/certificate.

  • dont_send_on_error – if True and S/MIME signing fails, the mail is dropped instead of being sent unsigned.

  • private_key – PEM-encoded private key for S/MIME signing.

  • private_key_password – passphrase for the S/MIME private key.

  • certificate – PEM-encoded certificate for S/MIME signing.

Status Codes:
GET /smtpserver/

Return all SMTP server definitions known to this server.

The result is a dictionary keyed by identifier; each value contains server, port, username, password, sender, tls, timeout, enqueue_job, description, smime, dont_send_on_error, private_key, private_key_password and certificate.

Warning

The response currently returns the SMTP password decrypted, not redacted. Treat it accordingly.

Requires admin authentication and the policy action smtpserver_read.

Status Codes:

  • 200 OK – dict of definitions in result.value.

DELETE /smtpserver/(identifier)

Delete the SMTP server definition with the given identifier.

Requires admin authentication and the policy action smtpserver_write.

Parameters:

  • identifier – path component, the name of the definition.

Status Codes:

  • 200 OK – True if a definition was deleted, False otherwise.

POST /smtpserver/send_test_email

Send a real test email through the supplied SMTP configuration. The configuration does not need to be saved first — all connection parameters are taken from the request body, and a fixed test message is delivered to recipient.

Requires admin authentication and the policy action smtpserver_write.

JSON Parameters:

  • identifier – identifier under which the definition would be saved (used in the test message body and in the audit log).

  • recipient – email address to deliver the test message to (required).

  • server – hostname or IP of the mail server (required).

  • port – TCP port, default 25.

  • username – SMTP auth user.

  • password – SMTP auth password.

  • sender – From: address used for the test message.

  • tls – True to use STARTTLS, default False.

  • timeout – socket timeout in seconds, default 10.

  • enqueue_job – if True, the test mail is queued via the job queue instead of being sent inline. Default False.

  • smime – if True, the test message is S/MIME-signed.

  • dont_send_on_error – if True and S/MIME signing fails, the message is dropped instead of being sent unsigned.

  • private_key – PEM-encoded S/MIME private key.

  • private_key_password – passphrase for the S/MIME private key.

  • certificate – PEM-encoded S/MIME certificate.

Status Codes:

  • 200 OK – True if the message was delivered (or queued) successfully, False otherwise.