From 1eb06af1adca2ae710a4c8c9ae47ab1c4ee5313a Mon Sep 17 00:00:00 2001 From: Robert Sesek Date: Sat, 8 Aug 2020 14:23:57 -0400 Subject: [PATCH] Update docs to cover contributing. --- README.md | 45 ++++++++++++++++++++++++++++----------------- docs/install.md | 4 ++-- 2 files changed, 30 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index d44f04a..46f6f1e 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,24 @@ # mailpopbox -Mailpopbox is a single-user mail server, providing SMTP and POP facilities. It acts as a catch-all, -wildcard email server for an entire domain name. Any message addressed to an account at the -configured domain will be deposited into a single mailbox, which can then be accessed using the POP3 -protocol. +Mailpopbox is a single-user mail server with SMTP and POP facilities. Its purpose is to provide +privacy through anonymity by acting as a catch-all, wildcard email server for an entire domain name. +Any message addressed to an account at the configured domain will be deposited into a single +mailbox, which can then be accessed using the POP3 protocol. The usage scenario is to configure your primary email provider (e.g., [Gmail](https://support.google.com/mail/answer/7104828)) or client to POP messages off the server. Any time you need to provide an email address, you can give out -*\*, allowing you to use site/service/person-specific email addresses. +`arbitrary-string@domain.com`, allowing you to use site/service/person-specific email addresses. Mail is collected into a single maildrop that can be POP'd out into your normal mailbox. +## Send-As SMTP + +Mailpopbox also provides a way to reply to messages from an arbitrary email address at the domain. +Since mailpopbox is designed as a catch-all mail server, it would be impractical to administer SMTP +accounts to enable replying from any address handled by the server. Instead, the SMTP authenticates +a single *mailbox* user, and if the message's Subject header has a special `[sendas:ADDRESS]` +string, the server will alter the From message header to be from ADDRESS@DOMAIN. + ## Installation Installation requires a server capable of binding on port 25 for SMTP and 995 for POP3. A TLS @@ -19,21 +27,24 @@ certificate is also required to have a secure connection for authenticating to t ## Building -To build mailpopbox for a Linux server, you need [Go](https://golang.org) and git: +Building mailpopbox only requires [Go](https://golang.org) and git. Clone the repository and type +`go build`. Cross-compilation is supported since the server is written in pure Go. - $ git clone https://src.bluestatic.org/mailpopbox.git - $ cd mailpopbox - $ GOOS=linux GOARCH=amd64 go build +## Contributing -The `GOOS` and `GOARCH` environment variables are only needed when cross-compiling (e.g. on a Mac). +[![CI](https://github.com/rsesek/mailpopbox/workflows/CI/badge.svg)](https://github.com/rsesek/mailpopbox/actions?query=workflow%3ACI) -## Send-As SMTP +The canonical home for the repository is on +[src.bluestatic.org](https://src.bluestatic.org/?p=mailpopbox.git), but it is also hosted on +[Github](https://github.com/rsesek/mailpopbox) to enable collaboration. -Mailpopbox also provides a way to reply to messages from an arbitrary email address at the domain. -Since mailpopbox is designed as a catch-all mail server, it would be impractical to administer SMTP -accounts to enable replying from any address handled by the server. Instead, the SMTP authenticates -a single *mailbox* user, and if the message's Subject header has a special `[sendas:ADDRESS]` -string, the server will alter the From message header to be from ADDRESS@DOMAIN. +Issues should be reported on the [Github issue tracker](https://github.com/rsesek/mailpopbox/issues). + +Contributions are welcome. Please: +- Ensure tests pass and that new changes have adequate code coverage (`make coverage`) +- Code is formatted with `go fmt` +- Commit history is clean (one logical change per commit) +- Commit message is well-formatted ## RFCs @@ -45,5 +56,5 @@ This server implements (partially) the following RFCs: - [SMTP Service Extension for Secure SMTP over Transport Layer Security, RFC 3207](https://tools.ietf.org/html/rfc3207) - [SMTP Service Extension for Authentication, RFC 2554](https://tools.ietf.org/html/rfc2554) - [The PLAIN Simple Authentication and Security Layer (SASL) Mechanism, RFC 4616](https://tools.ietf.org/html/rfc4616) -- [Simple Mail Transfer Protocol (SMTP) Service Extension for Delivery Status Notifications (DSNs)](https://tools.ietf.org/html/rfc3461) +- [Simple Mail Transfer Protocol (SMTP) Service Extension for Delivery Status Notifications (DSNs), RFC 3461](https://tools.ietf.org/html/rfc3461) - [POP3 Extension Mechanism, RFC 2449](https://tools.ietf.org/html/rfc2449) diff --git a/docs/install.md b/docs/install.md index 625608a..8967615 100644 --- a/docs/install.md +++ b/docs/install.md @@ -198,7 +198,7 @@ periodically via polling, so message delivery can seem slower than normal. - **Password:** The password you specified in `config.json` - Check **Secured connection using TLS** -Gmail will now let you send email as *mailbox@yourdomain.com*. But if you are replying to a message -sent to *random@yourdomain.com*, you do not want the recipient to see the "mailbox" username in your +Gmail will now let you send email as `mailbox@yourdomain.com`. But if you are replying to a message +sent to `random@yourdomain.com`, you do not want the recipient to see the "mailbox" username in your reply. If you append `[sendas:random]` to the Subject line of the message, the SMTP server will change the From address to `random@yourdomain.com` and remove the special tag from the Subject line. -- 2.22.5