social/mail_tracking_mailgun/README.rst

=========================
Mail tracking for Mailgun
=========================

.. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fsocial-lightgray.png?logo=github
    :target: https://github.com/OCA/social/tree/12.0/mail_tracking_mailgun
    :alt: OCA/social
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/social-12-0/social-12-0-mail_tracking_mailgun
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runbot-Try%20me-875A7B.png
    :target: https://runbot.odoo-community.org/runbot/205/12.0
    :alt: Try me on Runbot

|badge1| |badge2| |badge3| |badge4| |badge5| 

This module integrates mail_tracking events with Mailgun webhooks.

Mailgun (https://www.mailgun.com/) is a service that provides an e-mail
sending infrastructure through an SMTP server or via API. You can also
query that API for seeing statistics of your sent e-mails, or provide
hooks that processes the status changes in real time, which is the
function used here.

**Table of contents**

.. contents::
   :local:

Configuration
=============

You must configure Mailgun webhooks in order to receive mail events:

1. Got a Mailgun account and validate your sending domain.
2. Go to Webhook tab and configure the below URL for each event:

.. code:: html

   https://<your_domain>/mail/tracking/all/<your_database>

Replace '<your_domain>' with your Odoo install domain name
and '<your_database>' with your database name.

In order to validate Mailgun webhooks you have to configure the following system
parameters:

- `mailgun.apikey`: You can find Mailgun api_key in your validated sending
  domain.
- `mailgun.api_url`: It should be fine as it is, but it could change in the
  future.
- `mailgun.domain`: In case your sending domain is different from the one
  configured in `mail.catchall.domain`.
- `mailgun.validation_key`: If you want to be able to check mail address
  validity you must config this parameter with your account Public Validation
  Key.

You can also config partner email autocheck with this system parameter:

- `mailgun.auto_check_partner_email`: Set it to True.

Usage
=====

In your mail tracking status screens (explained on module *mail_tracking*), you
will see a more accurate information, like the 'Received' or 'Bounced' status,
which are not usually detected by normal SMTP servers.

It's also possible to make some checks to the partner's email addresses against
the Mailgun API:

- Check if the partner's email is in Mailgun's bounced list.
- Check the validity of the partner's mailbox.
- Force the partner's email into Mailgun's bounced list or delete from it.

It's also possible to manually check a message mailgun tracking when the webhook
couldn't be captured. For that, go to that message tracking form, press the
button *Check Mailgun*. It's important to note that tracking events have quite a
short lifespan, so after 24h they won't be recoverable.

Known issues / Roadmap
======================

* There's no support for more than one Mailgun mail server.

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/social/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us smashing it by providing a detailed and welcomed
`feedback <https://github.com/OCA/social/issues/new?body=module:%20mail_tracking_mailgun%0Aversion:%2012.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
~~~~~~~

* Tecnativa

Contributors
~~~~~~~~~~~~

* `Tecnativa <https://www.tecnativa.com>`_:

  * Antonio Espinosa
  * Carlos Dauden
  * Pedro M. Baeza
  * David Vidal
  * Rafael Blasco
  * Ernesto Tejeda

Other credits
~~~~~~~~~~~~~

Images
------

* Mailgun logo: `SVG Icon <http://seeklogo.com/mailgun-logo-273630.html>`_.

Maintainers
~~~~~~~~~~~

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

This module is part of the `OCA/social <https://github.com/OCA/social/tree/12.0/mail_tracking_mailgun>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.