0
0
Fork 0
mirror of https://github.com/go-gitea/gitea synced 2024-11-15 14:31:41 +01:00
gitea/docs/content/doc/usage/incoming-email.en-us.md
KN4CK3R fc037b4b82
Add support for incoming emails (#22056)
closes #13585
fixes #9067
fixes #2386
ref #6226
ref #6219
fixes #745

This PR adds support to process incoming emails to perform actions.
Currently I added handling of replies and unsubscribing from
issues/pulls. In contrast to #13585 the IMAP IDLE command is used
instead of polling which results (in my opinion 😉) in cleaner code.

Procedure:
- When sending an issue/pull reply email, a token is generated which is
present in the Reply-To and References header.
- IMAP IDLE waits until a new email arrives
- The token tells which action should be performed

A possible signature and/or reply gets stripped from the content.

I added a new service to the drone pipeline to test the receiving of
incoming mails. If we keep this in, we may test our outgoing emails too
in future.

Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
2023-01-14 23:57:10 +08:00

1.9 KiB

date title slug draft toc menu
2022-12-01T00:00:00+00:00 Incoming Email incoming-email false false
sidebar
parent name weight identifier
usage Incoming Email 13 incoming-email

Incoming Email

Gitea supports the execution of several actions through incoming mails. This page describes how to set this up.

Table of Contents

{{< toc >}}

Requirements

Handling incoming email messages requires an IMAP-enabled email account. The recommended strategy is to use email sub-addressing but a catch-all mailbox does work too. The receiving email address contains a user/action specific token which tells Gitea which action should be performed. This token is expected in the To and Delivered-To header fields.

Gitea tries to detect automatic responses to skip and the email server should be configured to reduce the incoming noise too (spam, newsletter).

Configuration

To activate the handling of incoming email messages you have to configure the email.incoming section in the configuration file.

The REPLY_TO_ADDRESS contains the address an email client will respond to. This address needs to contain the %{token} placeholder which will be replaced with a token describing the user/action. This placeholder must only appear once in the address and must be in the user part of the address (before the @).

An example using email sub-addressing may look like this: incoming+%{token}@example.com

If a catch-all mailbox is used, the placeholder may be used anywhere in the user part of the address: incoming+%{token}@example.com, incoming_%{token}@example.com, %{token}@example.com

Security

Be careful when choosing the domain used for receiving incoming email. It's recommended receiving incoming email on a subdomain, such as incoming.example.com to prevent potential security problems with other services running on example.com.