{"id":13565347,"url":"https://github.com/gessnerfl/fake-smtp-server","last_synced_at":"2026-04-11T22:12:25.683Z","repository":{"id":20889784,"uuid":"91195201","full_name":"gessnerfl/fake-smtp-server","owner":"gessnerfl","description":"A simple SMTP Server for Testing purposes. Emails are stored in an in-memory database and rendered in a Web UI","archived":false,"fork":false,"pushed_at":"2024-11-16T21:08:37.000Z","size":2045,"stargazers_count":437,"open_issues_count":14,"forks_count":90,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-11-16T21:28:06.265Z","etag":null,"topics":["fake-smtp-server","smtp-server","spring-boot"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gessnerfl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-13T18:33:35.000Z","updated_at":"2024-11-16T20:41:29.000Z","dependencies_parsed_at":"2023-12-29T19:29:47.427Z","dependency_job_id":"8cd57192-3f01-4b14-b551-21a5f0fe9b22","html_url":"https://github.com/gessnerfl/fake-smtp-server","commit_stats":null,"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gessnerfl%2Ffake-smtp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gessnerfl%2Ffake-smtp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gessnerfl%2Ffake-smtp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gessnerfl%2Ffake-smtp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gessnerfl","download_url":"https://codeload.github.com/gessnerfl/fake-smtp-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247090096,"owners_count":20881916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fake-smtp-server","smtp-server","spring-boot"],"created_at":"2024-08-01T13:01:45.095Z","updated_at":"2026-04-11T22:12:25.676Z","avatar_url":"https://github.com/gessnerfl.png","language":"Java","funding_links":[],"categories":["Java","Development Tools"],"sub_categories":["Test Tools"],"readme":"# Fake SMTP Server\n[![Build Status](https://github.com/gessnerfl/fake-smtp-server/workflows/CI%2FCD/badge.svg)](https://github.com/gessnerfl/fake-smtp-server/workflows/CI%2FCD/badge.svg)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=de.gessnerfl.fake-smtp-server\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=de.gessnerfl.fake-smtp-server)\n\n*Simple SMTP Server which stores all received emails in an in-memory database and renders the emails in a web interface*\n\n## Introduction\n\nThe Fake SMTP Server is a simple SMTP server which is designed for development purposes. The server collects all\nreceived emails, stores the emails in an in-memory database and provides access to the emails via a web interface.\n\nThere is no POP3 or IMAP interface included by intention. The basic idea of this software is that it is used during \ndevelopment to configure the server as target mail server. Instead of sending the emails to a real SMTP server which \nwould forward the mails to the target recipient or return with mail undelivery for test email addresses (e.g. \n@example.com) the server just accepts all mails, stores them in the database so that they can be rendered in the UI. \nThis allows you to use any test mail address and check the sent email in the web application of the Fake SMTP Server.\n\nThe server store a configurable maximum number of emails.\nIf the maximum number of emails is exceeded old emails will be deleted to avoid that the system consumes too much memory.\n\nThe server is also provided as docker image on docker hub [gessnerfl/fake-smtp-server](https://hub.docker.com/r/gessnerfl/fake-smtp-server/).\nTo change configuration parameters the corresponding configuration values have to be specified as environment variables for the docker container.\nFor details check the Spring Boot (http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-external-config)\nand docker documentation (https://docs.docker.com/engine/reference/run/#env-environment-variables).\n\n# Running Fake SMTP Server locally\n\n\u003e [!NOTE]  \n\u003e Starting with version 2.2.0 Java 21 is required to run Fake SMTP Server. \n\n\u003e [!NOTE]  \n\u003e Starting with version 2.0.0 Java 17 is required to run Fake SMTP Server.\n\n## Run from released JAR files\n\n1. Download the latest `fake-smtp-server-\u003cversion\u003e.jar` from \n[https://github.com/gessnerfl/fake-smtp-server/releases/latest](https://github.com/gessnerfl/fake-smtp-server/releases/latest)\n2. Copy the file into the desired target folder\n3. Execute the following command from the folder where the JAR file is located:\n   \n```\njava -jar fake-smtp-server-\u003cversion\u003e.jar\n```\n\n## Run from sources\n\nIn order to run this application locally from sources, execute:\n\n    ./gradlew bootRun\n\nAfterwards, the web interface is be availabe under http://localhost:8080.\n\n# Configuration\n\nAs the application is based on Spring Boot the same rules applies to the configuration as described in the Spring Boot \nDocumentation (http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-external-config).\n\nThe configuration file application.yaml can be placed next to the application jar, in a sub-directory config or \nin any other location when specifying the location with the parameter `-Dspring.config.location=\u003cpath to config file\u003e`.\n\nAll configuration parameters can also be passed as environment variables using uppercase characters and underscores as \nseparators such as `SERVER_PORT` or `MANAGEMENT_SERVER_PORT`.\n\nThe following paragraphs describe the application specific resp. pre-defined configuration parameters.\n\n## Fake SMTP Server\nThe following snippet shows the configuration of a fake smtp server with its default values.\n\n```yaml\nfakesmtp:\n  #The SMTP Server Port used by the Fake SMTP Server\n  port: 8025\n\n  #The binding address of the Fake SMTP Server; Bound to all interfaces by default / no value\n  bindAddress: 127.0.0.1\n\n  #List of recipient addresses which should be blocked/rejected\n  blockedRecipientAddresses:\n    - blocked@example.com\n    - foo@eample.com\n\n  #List of sender email addresses to ignore, as a comma-separated list of regex expressions.\n  filteredEmailRegexList: john@doe\\\\.com,.*@google\\\\.com ; empty by default\n\n  #Optional configuration option to specify the maximum allowed message size. The size can be \n  #defined using Spring Boot DataSize value type - https://docs.spring.io/spring-boot/docs/2.1.9.RELEASE/reference/html/boot-features-external-config.html#boot-features-external-config-conversion-datasize.\n  #Default: no limit\n  maxMessageSize: 10MB\n\n  #Configure if TLS is required to connect to the SMTP server. Defaults to false. See TLS section below\n  requireTLS: false\n\n  #When set to true emails will be forwarded to a configured target email system. Therefore\n  #the spring boot mail system needs to be configured. See also \n  # https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-email\n  forwardEmails: false\n```\n    \n### Authentication\nOptionally authentication can be turned on. Configuring authentication does not mean the authentication is enforced. It\njust allows you to test PLAIN and LOGIN SMTP Authentication against the server instance.\n\n```yaml\nfakesmtp:\n  authentication:\n    #Username of the client to be authenticated\n    username: myuser\n    #Password of the client to be authenticated\n    password: mysecretpassword \n```\n\n\n### TLS\nOptionally TLS can be activated. To configure TLS support, a trust store needs to be provided \ncontaining the TLS certificate used by the FakeSMTP Server.\n\n```yaml\nfakesmtp:\n  # true when TLS is mandatory otherwise TLS is optional\n  requireTLS: true\n  #configuration of the truststore to enable support for TLS.\n  tlsKeystore:\n    location: /path/to/truststore.p12\n    password: changeit\n    type: PKCS12 # or JKS\n```\n           \n### Data Retention Settings\n\n#### Emails\n\nTo keep memory resources under control, there is a parallel process that deletes the oldest emails considering the maximum number of emails to retain and the time span to periodically recheck this maximum number of emails, controlling also the initial time to wait to start this parallel process. The default values are:\n\n- maxNumberEmails: 100\n- fixedDelay: 300000 # 5 minutes\n- initialDelay: 60000 # 1 minute\n\n```yaml\nfakesmtp:\n  persistence:\n    maxNumberEmails:\n      emails:\n        #max numbers of most recent emails to retain and not deleted by the parallel process\n        maxNumberEmails: 10\n        # configuration settings of the background process (timer) responsible to delete the oldest emails\n        emailDataRetentionTimer:\n          #each 5 minutes from 'initialDelay' (see below), the parallel process will check if the deletion is necessary\n          fixedDelay: 300000\n          #each 'initialDelay' (see above)  after 2 minutes from the start, the parallel process will start checking if the deletion is necessary\n          initialDelay: 120000\n```\n\n## Web UI\nThe following snippet shows the pre-defined web application configuration\n\n```yaml\n#Port of the web interface\nserver:\n  port: 8080\n\n#Port of the http management api\nmanagement:\n  server:\n    port: 8081 \n```\n\n### Web UI Authentication\n\nYou can optionally enable Basic Authentication for the web interface and REST API. When authentication is enabled, users will need to log in to access the web interface and API endpoints.\n\nTo enable authentication, set the username and password in the application.yml file:\n\n```yaml\nfakesmtp:\n  webapp:\n    authentication:\n      # Username for web UI and API authentication\n      username: admin\n      # Password for web UI and API authentication\n      password: password\n```\n\nYou can also set these values using environment variables:\n\n```\nFAKESMTP_WEBAPP_AUTH_USERNAME=admin\nFAKESMTP_WEBAPP_AUTH_PASSWORD=password\n```\n\nIf both username and password are not set, authentication will be disabled and the web interface and API endpoints will be accessible without authentication.\n\nWhen authentication is enabled:\n- The web interface will show a custom login form\n- API endpoints will require Basic Authentication\n- A logout button will be available in the navigation bar\n- The following endpoints are protected and require authentication:\n  - Main web UI routes (`/`, `/emails/**`)\n  - API endpoints (`/api/**`) except for `/api/meta-data`\n- The following endpoints remain public and do not require authentication:\n  - `/api/meta-data` (provides application metadata including authentication status)\n  - Swagger UI (`/swagger-ui.html`, `/swagger-ui/**`, `/v3/api-docs/**`)\n  - Actuator endpoints (`/actuator/**`)\n  - H2 console (`/h2-console/**`)\n  - Static resources (`/static/**`, `/css/**`, `/js/**`, `/images/**`, `/webjars/**`, `/favicon.ico`)\n\n\u003e [!NOTE]  \n\u003e The Web UI authentication is separate from the SMTP server authentication. The SMTP server authentication is configured under `fakesmtp.authentication` and is used for authenticating SMTP clients, while the Web UI authentication is configured under `fakesmtp.webapp.authentication` and is used for authenticating users accessing the web interface and API endpoints.\n    \n\n## Real-Time Email Notifications\n\nThe Fake SMTP Server supports real-time email notifications using Server-Sent Events (SSE). This feature eliminates the need for polling and provides instant updates when new emails are received.\n\n### How It Works\n\n1. The web interface automatically establishes an SSE connection to the server\n2. When a new email is received by the SMTP server, an event is sent to all connected clients\n3. The web interface updates the email list in real-time without refreshing the page\n\n### Benefits\n\n- **Instant Updates**: See new emails as soon as they arrive\n- **Reduced Server Load**: Eliminates the need for frequent polling\n- **Improved User Experience**: No delay in seeing new emails\n- **Efficient Resource Usage**: SSE is more efficient than WebSockets for one-way communication\n\n### Authentication Considerations\n\nWhen Web UI Authentication is enabled, the SSE connection is only established after successful login. This ensures that only authenticated users receive real-time notifications.\n\n## REST API\n\nDocumentation of exposed services is available at:\n    \n    localhost:8080/swagger-ui.html\n\n## Developpment Environment\n\nThis requires to have docker installed.\nIf you need to implement a new feature, you will probably need an correct JDK version setup in an environement.\n\n```sh\nsh/dev\n```\n\nThen, in the dev container started by the command above, you can use various commands. \nThe following commands should be the most common ones:\n```bash\nsh gradlew test\nsh gradlew test --tests '*EmailRepositoryIntegration*' --info\nsh gradlew build\n```\n\nRun UI \u0026 Backend tests\n```bash\nsh/test\n```\n\nBuild UI \u0026 Backend\n```bash\nsh/build\n```\n\nRun app (UI \u0026 Backend)\n```bash\nsh/run\n```\n\n### Build \u0026 Push a new development docker image\n\nTo update/change the development image, update the `dev.Dockerfile`, dont forget to change the version in the `dev-image-tag` file and edit the registery if needed.\n```bash\nsh/push-dev-image\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgessnerfl%2Ffake-smtp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgessnerfl%2Ffake-smtp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgessnerfl%2Ffake-smtp-server/lists"}