{"id":13580318,"url":"https://github.com/tweedegolf/mailcrab","last_synced_at":"2025-05-16T04:03:37.255Z","repository":{"id":71446800,"uuid":"555433240","full_name":"tweedegolf/mailcrab","owner":"tweedegolf","description":"Email test server for development, written in Rust","archived":false,"fork":false,"pushed_at":"2025-05-15T10:13:39.000Z","size":1019,"stargazers_count":862,"open_issues_count":2,"forks_count":27,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-16T04:02:52.733Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/tweedegolf.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,"zenodo":null}},"created_at":"2022-10-21T15:11:00.000Z","updated_at":"2025-05-15T10:13:18.000Z","dependencies_parsed_at":"2023-05-20T06:30:14.879Z","dependency_job_id":"5791a9f3-3e5d-4eef-927c-a572b7e13e35","html_url":"https://github.com/tweedegolf/mailcrab","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tweedegolf%2Fmailcrab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tweedegolf%2Fmailcrab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tweedegolf%2Fmailcrab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tweedegolf%2Fmailcrab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tweedegolf","download_url":"https://codeload.github.com/tweedegolf/mailcrab/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464891,"owners_count":22075570,"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":[],"created_at":"2024-08-01T15:01:49.797Z","updated_at":"2025-05-16T04:03:37.207Z","avatar_url":"https://github.com/tweedegolf.png","language":"Rust","funding_links":[],"categories":["Rust","Libraries","Sending"],"sub_categories":["Email","SMTP Testing"],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/tweedegolf/mailcrab/main/frontend/img/mailcrab.svg\" width=\"400\" alt=\"MailCrab logo\" /\u003e\n\n# MailCrab\n\nEmail test server for development, written in Rust.\n\nInspired by [MailHog](https://github.com/mailhog/MailHog) and [MailCatcher](https://mailcatcher.me/).\n\nMailCrab was created as an exercise in Rust, trying out [Axum](https://github.com/tokio-rs/axum) and functional components with [Yew](https://yew.rs/), but most of all because it is really enjoyable to write Rust code.\n\n## TLDR\n\n```sh\ndocker run --rm -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest\n```\n\n## Features\n\n- Accept-all SMTP server\n- Web interface to view and inspect all incoming email\n- View formatted mail, download attachments, view headers or the complete raw mail contents\n- Single binary\n- Runs on all `amd64` and `arm64` platforms using docker\n- Just a 7.77 MB docker image\n\n![MailCrab screenshot](https://raw.githubusercontent.com/tweedegolf/mailcrab/main/frontend/img/screen.png)\n\n## Related projects\n\n- [CrabAlert](https://github.com/klr/crabalert) is a macOS status bar application that notifies you of incoming messages in MailCrab\n\n## Technical overview\n\nBoth the backend server and the frontend are written in Rust. The backend receives email over an unencrypted connection on a configurable port. All email is stored in memory while the application is running. An API exposes all received email:\n\n- `GET  /api/messages` return all message metadata\n- `GET  /api/message/[id]` returns a complete message, given its `id`\n- `POST /api/delete/[id]` deletes a message, given its `id`\n- `POST /api/delete-all` deletes all messages\n- `GET  /api/version` returns version information about the executable\n- `GET  /ws` send email metadata to each connected client when a new email is received\n\nThe frontend initially performs a call to `/api/messages` to receive all existing email metadata and then subscribes for new messages using the websocket connection. When opening a message, the `/api/message/[id]` endpoint is used to retrieve the complete message body and raw email.\n\nThe backend also accepts a few commands over the websocket, to mark a message as opened, to delete a single message or delete all messages.\n\n## Installation and usage\n\nYou can run MailCrab using docker. Start MailCrab using the following command:\n\n```sh\ndocker run --rm -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest\n```\n\nOpen a browser and navigate to [http://localhost:1080](http://localhost:1080) to view the web interface.\n\nThere are also (single) binary builds available, see https://github.com/tweedegolf/mailcrab/releases\n\n### Ports\n\nThe default SMTP port is 1025, the default HTTP port is 1080. You can configure the SMTP and HTTP port using environment variables (`SMTP_PORT` and `HTTP_PORT`), or by exposing them on different ports using docker:\n\n```sh\ndocker run --rm -p 3000:1080 -p 2525:1025 marlonb/mailcrab:latest\n```\n  \n## Host\n\nYou can specify the host address MailCrab will listen on for HTTP request using\nthe `HTTP_HOST` environment variable. In the docker image the default\naddress is `0.0.0.0`, when running MailCrab directly using cargo or a binary, the default is `127.0.0.1`.\n\n### TLS\n\nYou can enable TLS and authentication by setting the environment variable `ENABLE_TLS_AUTH=true`. MailCrab will generate a key-pair and print the self-signed certificate. Any username/password combination is accepted. For example:\n\n```sh\ndocker run --rm --env ENABLE_TLS_AUTH=true -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest\n```\n\nIt is also possible to provide your own certificate by mounting a key and a certificate to `/app/key.pem` and `/app/cert.pem`:\n\n```sh\ndocker run --rm --env ENABLE_TLS_AUTH=true -v key.pem:/app/key.pem:ro -v cert.pem:/app/cert.pem:ro -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest\n```\n\n### Path prefix\n\nYou can configure a prefix path for the web interface by setting and environment variable named `MAILCRAB_PREFIX`, for example:\n\n```sh\ndocker run --rm --env MAILCRAB_PREFIX=emails -p 1080:1080 -p 1025:1025 marlonb/mailcrab:latest\n```\n\nThe web interface will also be served at [http://localhost:1080/emails/](http://localhost:1080/emails/)\n\n### Reverse proxy\n\nSee [the reverse proxy guide](./reverse_proxy.md).\n\n### Retention period\n\nBy default messages will be stored in memory until MailCrab is restarted. This might cause an OOM when MailCrab lives\nlong enough and receives enough messages.\n\nBy setting `MAILCRAB_RETENTION_PERIOD` to a number of seconds, messages older than the provided duration will\nbe cleared.\n\n### Performance\n\nMailCrab is fast, although there is a bottleneck in the throughput of the websocket connection\n(between the server and the browser). If there are many messages sent at once (more than 100 per second)\na client can lag behind and messages can get lost. When dealing with many messages at once,\nincreasing the internal queue size can help to prevent losing messages.\nUse the `QUEUE_CAPACITY` environment variable to set the queue size. De default\nis 32, which means that MailCrab can handle 32 messages if the are all sent at the same time.\n\n### docker compose\n\nUsage in a `docker-compose.yml` file:\n\n```yml\nversion: '3.8'\nservices:\n  mailcrab:\n    image: marlonb/mailcrab:latest\n    #        environment:\n    #            ENABLE_TLS_AUTH: true # optionally enable TLS for the SMTP server\n    #            MAILCRAB_PREFIX: emails # optionally prefix the webinterface with a path\n    #        volumes:\n    #           key.pem:/app/key.pem:ro # optionally provide your own keypair for TLS, else a pair will be generated\n    #           cert.pem:/app/cert.pem:ro\n    ports:\n      - '1080:1080'\n      - '1025:1025'\n    networks: [default]\n```\n\n## Kubernetes deployment\n\nTo deploy MailCrab to a Kubernetes cluster, you can use [Helm Chart](./charts/mailcrab/) by cloning this repository and running:\n\n```sh\nhelm install mailcrab ./charts/mailcrab -f values.yaml\n```\n\nFor more information on configuring the Helm Chart, see the chart [README](./charts/mailcrab/README.md).\n\n## Sample messages\n\nThe `samples` directory contains a couple of test messages. These can be sent using by running:\n\n```sh\ncd backend/\ncargo test send_sample_messages -- --ignored\n```\n\nAlternatively you can send messages using curl:\n\n```sh\ncurl smtp://127.0.0.1:1025 --mail-from myself@example.com --mail-rcpt receiver@example.com --upload-file samples/normal.email\n# with tls\ncurl -k --ssl-reqd smtps://127.0.0.1:1025 --mail-from myself@example.com --mail-rcpt receiver@example.com --upload-file samples/normal.email --user 'user:pass'\n```\n\n## Development\n\nInstall [Rust](https://www.rust-lang.org/learn/get-started) and [Trunk](https://trunkrs.dev/)\n\n```sh\n# Add wasm as target if it it not present after following the install instructions for Trunk\nrustup target add wasm32-unknown-unknown\n\n# clone the code\ngit clone git@github.com:tweedegolf/mailcrab.git\n\n# start the backend\ncd backend\ncargo run\n\n# serve the frontend (in a new terminal window)\ncd ../frontend\ntrunk serve\n\n# optionally send test messages in an interval\ncd ../backend\ncargo test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftweedegolf%2Fmailcrab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftweedegolf%2Fmailcrab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftweedegolf%2Fmailcrab/lists"}