Technical documentation and design available at:

SMTP configuration

retrieve a list of SMTP entries:

GET /smtp-configuration

To create a new SMTP entry:

POST /smtp-configuration

     "module": "SMTP_SERVER",
     "configName": "email",
     "code": "EMAIL_FROM"
     "description": "smtp from",
     "default": true,
     "enabled": true,
     "value": ""

To delete a SMTP entry:

DELETE /smtp-configuration/{smtpConfigurationId}

  • Entry ID can be looked up in the result of a GET call.

To update an existing entry:

PUT /smtp-configuration/{smtpConfigurationId}

     "module": "SMTP_SERVER",
     "configName": "email",
     "code": "EMAIL_FROM",
     "description": "smtp from",
     "default": true,
     "enabled": true,
     "value": ""

  • Entry ID can be looked up in the result of a GET call.


Minimum viable configuration for module  SMTP_SERVER  consists of 5 entries:


Custom headers

Custom headers are configured by creating entries in mod-configuration with following (required) properties

     "module": "SMTP_SERVER",
     "configName": "email.headers",
     "code": "HEADER_NAME_HERE",
     "value": "HEADER_VALUE_HERE"


Where HEADER_NAME_HERE should be replaced with the name of your custom header, e.g. X-SES-CONFIGURATION-SET, and HEADER_VALUE_HERE should be replaced with desired value.

Values of properties module and configName should NOT be changed, and are required in order to be discovered by mod-email and treated as custom header configurations.

You can configure as many custom headers as you want as long as they have different code values.

Troubleshooting problems 

Logical chain:

1)  Check notification system

2)  Check SMTP configuration (setup and working)

3)  Check email status (/emails):

GET /email
Available query parameters:

    • offset: (integer - default: 0 - minimum: 0 - maximum: 2147483647)
    • limit: (integer - default: 10 - minimum: 0 - maximum: 2147483647)
    • query: (string) Example: ?query=status=FAILURE
      more info about CQL:

Example request with parameters.

Fields to look at:

    • status (FAILURE when sending failed)
    • message (contains error message when sending failed)

Possible error messages:

    • Error in the 'mod-email' module, the module didn't send email | message: invalid email address

SMTP configuration issues:

    • Error looking up config at url=%s | Expected status code 200, got %s | error message: %s
    • The 'mod-config' module doesn't have a minimum config for SMTP server, the min config is: %s


4)  Check the list of scheduled notices:
GET /scheduled-notice-storage/scheduled-notices

Notices can be filtered by loan, recipient, triggering event, etc:
GET /scheduled-notice-storage/scheduled-notices?query=recipientUserId==429d212c-c646-4c75-ba3d-c16216491123


5)  More on scheduled notices API: here

  • Check logs in the following modules:
    mod-circulation, mod-email, mod-template-engine, mod-sender, mod-notify

    Okapi logs:
    vagrant ssh

    Specific module logs:
    vagrant ssh
    docker ps (to find container id)
    docker logs {container_id} (more on this command here)




  • No labels