{"id":13452497,"url":"https://github.com/martin-helmich/kube-mail","last_synced_at":"2026-03-07T05:32:20.750Z","repository":{"id":34534406,"uuid":"138188593","full_name":"martin-helmich/kube-mail","owner":"martin-helmich","description":"Policy-based SMTP daemon for sending emails from Kubernetes (experimental)","archived":false,"fork":false,"pushed_at":"2024-02-29T13:09:34.000Z","size":1473,"stargazers_count":55,"open_issues_count":13,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-09-06T17:47:57.540Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/martin-helmich.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":"2018-06-21T15:24:44.000Z","updated_at":"2025-08-10T05:39:13.000Z","dependencies_parsed_at":"2024-07-31T07:14:33.380Z","dependency_job_id":"39b23294-9a9d-47e6-ab97-8178db180328","html_url":"https://github.com/martin-helmich/kube-mail","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/martin-helmich/kube-mail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-helmich%2Fkube-mail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-helmich%2Fkube-mail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-helmich%2Fkube-mail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-helmich%2Fkube-mail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martin-helmich","download_url":"https://codeload.github.com/martin-helmich/kube-mail/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martin-helmich%2Fkube-mail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30208731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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-07-31T07:01:25.821Z","updated_at":"2026-03-07T05:32:20.712Z","avatar_url":"https://github.com/martin-helmich.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# kube-mail -- SMTP server for Kubernetes\n\n[![Build Status](https://travis-ci.org/martin-helmich/kube-mail.svg?branch=master)](https://travis-ci.org/martin-helmich/kube-mail)\n[![Docker Repository on Quay](https://quay.io/repository/martinhelmich/kube-mail/status \"Docker Repository on Quay\")](https://quay.io/repository/martinhelmich/kube-mail)\n[![Dependabot Status](https://api.dependabot.com/badges/status?host=github\u0026repo=martin-helmich/kube-mail)](https://dependabot.com)\n\n\u003chr\u003e\n\n**:warning: CAUTION** This is entirely experimental and may eat your cluster.\n\n\u003chr\u003e\n\nkube-mail is a policy-based SMTP server designed for running in a Kubernetes cluster. It is configurable using Kubernetes Custom Resources and allows you to define policies for outgoing emails based on Pod labels (much like [NetworkPolicies](https://kubernetes.io/docs/concepts/services-networking/network-policies/)).\n\n## Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Installation](#installation)\n- [Basic architecture](#basic-architecture)\n- [Custom Resources](#custom-resources)\n  - [`SMTPServer` resources](#smtpserver-resources)\n  - [`EmailPolicy` resources](#emailpolicy-resources)\n- [How-Tos](#how-tos)\n  - [Forward all emails from a Pod into a mail catcher](#forward-all-emails-from-a-pod-into-a-mail-catcher)\n- [Sending mails from within a Pod](#sending-mails-from-within-a-pod)\n  - [PHP and ssmtp](#php-and-ssmtp)\n- [Pending features](#pending-features)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## License\n\nThis project is licensed under the Apache-2.0 license.\n\nCopyright 2023 Martin Helmich, Mittwald CM Service GmbH \u0026 Co. KG and [other contributors](https://github.com/martin-helmich/kube-mail/graphs/contributors).\n\n## Installation\n\nThe helm chart of this controller can be found under [./deploy/helm-chart/kube-mail](./deploy/helm-chart/kube-mail).\n\nAlternatively, you can use the [Mittwald Kubernetes Helm Charts](https://github.com/mittwald/helm-charts) repository:\n```shell script\nhelm repo add mittwald https://helm.mittwald.de\nhelm repo update\nhelm install kube-mail mittwald/kube-mail --namespace kube-system\n```\n\n## Basic architecture\n\nWhen installed, kube-mail acts as an SMTP server that Pods in your cluster can use to send outgoing mails. This server works without any of the typical SMTP authentication mechanisms; instead, the kube-mail SMTP server authenticates a Pod by its IP address and then tries to find a `EmailPolicy` resource that matches the source Pod (by label).\n\nIf an `EmailPolicy` has been found for a Pod, kube-mail will forward the email that should be sent to the upstream SMTP server configured in the `EmailPolicy`. If no `EmailPolicy` matches, kube-mail will reject the email.\n\nWithin your Pod, simply use `kube-mail.\u003cnamespace\u003e.svc` as SMTP server without any authentication. kube-mail will do the rest.\n\n## Custom Resources\n\nThis controller adds two Custom Resources to your Kubernetes cluster: A `SMTPServer` and a `EmailPolicy` resource, both from the `kube-mail.helmich.me/v1alpha1` API group.\n\n### `SMTPServer` resources\n\nAn `SMTPServer` resource describes an SMTP server that should be used for outgoing mails. It is defined like follows:\n\n```yaml\napiVersion: kube-mail.helmich.me/v1alpha1\nkind: SMTPServer\nmetadata:\n  name: default\nspec:\n  server: smtp.yourserver.example\n  port: 465\n  tls: true\n  authType: PLAIN\n```\n\nConcerning the individual properties:\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003e.spec.server\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eThe host name of your upstream SMTP server. This may be either an external service, or a cluster-internal service (for example, specified by its \u003ccode\u003e.svc.cluster.local\u003c/code\u003e address)\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003e.spec.port\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eThe port that the upstream SMTP server is listening on. If omitted, 587 is assumed as default.\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003e.spec.tls\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eDefines if the upstream server uses TLS.\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003e.spec.authType\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eThe SMTP authentation type. Supported values are \u003ccode\u003ePLAIN\u003c/code\u003e, \u003ccode\u003eLOGIN\u003c/code\u003e, \u003ccode\u003eCRAM-MD5\u003c/code\u003e and \u003ccode\u003eSCRAM-SHA-1\u003c/code\u003e.\u003c/dd\u003e\n\u003c/dl\u003e\n\n### `EmailPolicy` resources\n\nAn `EmailPolicy` defines what kube-mail should do with mails received from a certain pod. An email policy will forward the received email to one of the SMTP servers configured using the `SMTPServer` resources.\n\nA forwarding email policy is defined like follows:\n\n```yaml\napiVersion: kube-mail.helmich.me/v1alpha1\nkind: EmailPolicy\nmetadata:\n  name: my-policy\nspec:\n  podSelector:\n    matchLabels:\n      app.kubernetes.io/name: my-name\n  ratelimiting:\n    maximum: 100\n    period: hour\n  sink:\n    smtp:\n      server:\n        name: default\n        namespace: default\n      credentials:\n        name: default-credentials\n        namespace: default\n``` \n\nConcerning the individual properties:\n\n\u003cdl\u003e\n  \u003cdt\u003e\u003ccode\u003e.spec.podSelector\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eThis is a selector for the Pods this EmailPolicy should apply to. When a SMTP connection is opened to kube-mail, it will identity the source Pod by its Pod IP address and then test if the source Pod matches this label selector.\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003e.spec.ratelimiting\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003eRate limiting may be configured per Policy. Allowed periods are \u003ccode\u003e\"hour\"\u003c/code\u003e and \u003ccode\u003e\"minute\"\u003c/code\u003e. Messages are counted \u003cem\u003eper policy\u003c/em\u003e, not per Pod.\u003c/dd\u003e\n  \u003cdt\u003e\u003ccode\u003e.spec.sink\u003c/code\u003e\u003c/dt\u003e\n  \u003cdd\u003e\n    \u003ccode\u003esink\u003c/code\u003e describes where kube-mail should deliver received emails. This may either be an SMTP server (described by a \u003ccode\u003eSMTPServer\u003c/code\u003e resource) or kube-mail's internal database.\n    \u003cdl\u003e\n      \u003cdt\u003e\u003ccode\u003e.spec.sink.smtp.server\u003c/code\u003e\u003c/dt\u003e\n      \u003cdd\u003e\u003ccode\u003eserver\u003c/code\u003e is a reference to a \u003ccode\u003eSMTPServer\u003c/code\u003e resource. It may be placed in a different namespace.\u003c/dd\u003e\n      \u003cdt\u003e\u003ccode\u003e.spec.sink.smtp.credentials\u003c/code\u003e\u003c/dt\u003e\n      \u003cdd\u003e\u003ccode\u003ecredentials\u003c/code\u003e is a reference to a \u003ccode\u003eSecret\u003c/code\u003e resource with a \u003ccode\u003e\"username\"\u003c/code\u003e and \u003ccode\u003e\"password\"\u003c/code\u003e key. It may be placed in a different namespace. \u003cb\u003eNOTE\u003c/b\u003e: If omitted, kube-mail will attempt an unauthenticated connection to the SMTP server.\u003c/dd\u003e\n    \u003c/dl\u003e\n  \u003c/dd\u003e\n\u003c/dl\u003e\n\n## How-Tos\n\n### Forward all emails from a Pod into a mail catcher\n\nForwarding all outgoing emails into a mail catcher (like [MailHog](https://github.com/mailhog/MailHog)) is a common use case in development environments, where an application should not be allowed to actually send emails out into the world. To configure kube-mail to forward all emails into a mail catcher, proceed as follows.\n\n1. Make sure that kube-mail is up and running in a namespace of your choice (for this example, we'll assume that kube-mail is running in the `kube-system` namespace).\n\n1. Install the mail catcher of your choice. MailHog, for example, has a [Helm chart](https://github.com/codecentric/helm-charts/tree/master/charts/mailhog) that makes it easy to install:\n\n    ```\n    $ helm repo add codecentric https://codecentric.github.io/helm-charts\n    $ helm install \\\n        --namespace kube-system \\\n        --name mailhog \\\n        codecentric/mailhog\n    ```\n\n1. Configure an `SMTPServer` resource pointing to your MailHog service:\n\n    ```yaml\n    apiVersion: kube-mail.helmich.me/v1alpha1\n    kind: SMTPServer\n    metadata:\n      name: mailhog\n      namespace: kube-system\n    spec:\n      server: mailhog.kubemail-system.svc.cluster.local\n      port: 1025\n      tls: false\n    ```\n\n1. Configure an `EmailPolicy` to catch emails from a Pod and forward them to the configured `SMTPServer`. The policy resource needs to be in the same namespace as the Pod that's sending mails.\n\n    ```yaml\n    apiVersion: kube-mail.helmich.me/v1alpha1\n    kind: EmailPolicy\n    metadata:\n      name: pod-to-mailhog\n      namespace: default # needs to be same namespace as Pod\n    spec:\n      podSelector:\n        matchLabels:\n          app.kubernetes.io/name: my-name\n      sink:\n        smtp:\n          server: # server may be in a different namespace than policy\n            name: mailhog\n            namespace: kube-system\n    ```\n\n## Sending mails from within a Pod\n\n### PHP and ssmtp\n\nProvide `ssmtp` in your Pod; use the following configuration (`/etc/ssmtp/ssmtp.conf`):\n\n```\nmailhub=kube-mail.kube-system.svc.cluster.local\nhostname=foo\nFromLineOverride=yes\n```\n\nThen in the php.ini:\n\n```\nsendmail_path = /usr/sbin/ssmtp -t\n```\n\n## Pending features\n\n- [ ] Rate limiting\n- [ ] TLS for cluster-internal communication\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartin-helmich%2Fkube-mail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartin-helmich%2Fkube-mail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartin-helmich%2Fkube-mail/lists"}