Quick start guide#

First you’ll need to have Django and django-contact-form installed; for details on that, see the installation guide.

Once that’s done, you can start setting up django-contact-form. Add "django_contact_form" to your INSTALLED_APPS setting. Then, you can begin configuring.

URL configuration#

The quickest way to set up the views in django-contact-form is to use the provided URLconf, found at django_contact_form.urls. You can include it wherever you like in your site’s URL configuration; for example, to have it live at the URL /contact/:

from django.urls import include, path


urlpatterns = [
    # ... other URL patterns for your site ...
    path("contact/", include("django_contact_form.urls")),
]

If you’ll be using a custom form class, you’ll need to manually set up your URLs so you can tell django-contact-form about your form class. For example:

from django.urls import include, path
from django.views.generic import TemplateView

from django_contact_form.views import ContactFormView

from yourapp.forms import YourCustomFormClass


urlpatterns = [
    # ... other URL patterns for your site ...
    path("contact/",
        ContactFormView.as_view(
            form_class=YourCustomFormClass
        ),
        name="django_contact_form"),
    path("contact/sent/",
        TemplateView.as_view(
            template_name="django_contact_form/contact_form_sent.html"
        ),
        name="django_contact_form_sent"),
]

Important

Where to put custom forms and views

When writing a custom form class (or custom ContactFormView subclass), don’t put your custom code inside django-contact-form. Instead, put your custom code in the appropriate place (a forms.py or views.py file) in an application you’ve written.

Required templates#

The two views above will need several templates to be created.

django_contact_form/contact_form.html#

This is used to display the contact form. It has a RequestContext (so any context processors will be applied), and also provides the form instance as the context variable form.

django_contact_form/contact_form_sent.html#

This is used after a successful form submission, to let the user know their message has been sent. It has a RequestContext, but provides no additional context variables of its own.

django_contact_form/contact_form.txt#

Used to render the subject of the email. Will receive a RequestContext with the following additional variables:

body

The message the user supplied.

email

The email address the user supplied.

name

The name the user supplied.

site

The current site. Either a Site or RequestSite instance, depending on whether Django’s sites framework is installed).

django_contact_form/contact_form_subject.txt#

Used to render the subject of the email. Will receive a RequestContext with the following additional variables:

body

The message the user supplied.

email

The email address the user supplied.

name

The name the user supplied.

site

The current site. Either a Site or RequestSite instance, depending on whether Django’s sites framework is installed).

Warning

Subject must be a single line

In order to prevent header injection attacks, the subject must be only a single line of text, and Django’s email framework will reject any attempt to send an email with a multi-line subject. So it’s a good idea to ensure your contact_form_subject.txt template only produces a single line of output when rendered; as a precaution, however, django-contact-form will, by default, condense the output of this template to a single line.

Using a spam-filtering contact form#

Spam filtering is a common desire for contact forms, due to the large amount of spam they can attract. There is a spam-filtering contact form class included in django-contact-form: AkismetContactForm, which uses the Wordpress Akismet spam-detection service.

To use this form, you will need to do the following things:

  1. Install the Python akismet module to allow django-contact-form to communicate with the Akismet service. You can do this via pip install akismet, or as you install django-contact-form via pip install django-contact-form[akismet].

  2. Obtain an Akismet API key from <https://akismet.com/>, and associate it with the URL of your site.

  3. Supply the API key and URL for django-contact-form to use. You can either place them in the Django settings AKISMET_API_KEY and AKISMET_BLOG_URL, or in the environment variables PYTHON_AKISMET_API_KEY and PYTHON_AKISMET_BLOG_URL.

Then you can replace the suggested URLconf above with the following:

from django.urls import include, path


urlpatterns = [
    # ... other URL patterns for your site ...
    path("contact/", include("django_contact_form.akismet_urls")),
]