summaryrefslogtreecommitdiff
path: root/doc/administration/integration/mailgun.md
blob: 6b0cb0466fc63b98e53750bd833f7ece8504cfd4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
---
stage: Plan
group: Project Management
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
type: reference, howto
---

# Mailgun and GitLab **(FREE SELF)**

When you use Mailgun to send emails for your GitLab instance and [Mailgun](https://www.mailgun.com/)
integration is enabled and configured in GitLab, you can receive their webhook for
tracking delivery failures. To set up the integration, you must:

1. [Configure your Mailgun domain](#configure-your-mailgun-domain).
1. [Enable Mailgun integration](#enable-mailgun-integration).

After completing the integration, Mailgun `temporary_failure` and `permanent_failure` webhooks are sent to your GitLab instance.

## Configure your Mailgun domain

> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/359113) the `/-/members/mailgun/permanent_failures` URL in GitLab 15.0.
> [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/359113) the URL to handle both temporary and permanent failures in GitLab 15.0.

Before you can enable Mailgun in GitLab, set up your own Mailgun endpoints to receive the webhooks.

Using the [Mailgun webhook guide](https://www.mailgun.com/blog/product/a-guide-to-using-mailguns-webhooks/):

1. Add a webhook with the **Event type** set to **Permanent Failure**.
1. Enter the URL of your instance and include the `/-/mailgun/webhooks` path.

   For example:

   ```plaintext
   https://myinstance.gitlab.com/-/mailgun/webhooks
   ```

1. Add another webhook with the **Event type** set to **Temporary Failure**.
1. Enter the URL of your instance and use the same `/-/mailgun/webhooks` path.

## Enable Mailgun integration

After configuring your Mailgun domain for the webhook endpoints,
you're ready to enable the Mailgun integration:

1. Sign in to GitLab as an [Administrator](../../user/permissions.md) user.
1. On the top bar, select **Menu >** **{admin}** **Admin**.
1. On the left sidebar, go to **Settings > General** and expand the **Mailgun** section.
1. Select the **Enable Mailgun** check box.
1. Enter the Mailgun HTTP webhook signing key as described in
   [the Mailgun documentation](https://documentation.mailgun.com/en/latest/user_manual.html#webhooks) and
   shown in the [API security](https://app.mailgun.com/app/account/security/api_keys) section for your Mailgun account.
1. Select **Save changes**.