Django app for e-mail verification on sign up
Project description
email-verify 0.1.1
A Django app for adding user email verification at registration.
features
- Easy integration with any Django app
- Designed the Django way - offers granular customization alongside default behavior
- Works out-of-the-box with Django's SMTP backend. Can be customized to work with any backend.
getting started
setup
Install it with:
pip install email-verify
If you're using virtual environments, make sure to activate it before running this command
Add email_verify
to your INSTALLED_APPS
list, after your main app. Your INSTALLED_APPS should look similar to this:
# settings.py:
INSTALLED_APPS = [
'your_main_app',
'email_verify',
'django.contrib.admin',
# ...
]
Include the url conf of email-verify in your project's (not your app's) url configuration, after your other url confs.
# urls.py
urlpatterns = [
path('admin/', admin.site.urls),
path('', include('your/main/app.urls')),
# ...
path('where/you/want/', include('email_verify.urls')),
]
Once you add the app to your INSTALLED_APPS, you might notice you have a new migration available. email-verify establishes a one-to-one relation with the built-in User model (from django.contrib.auth.models).
You can apply migrations via:
python manage.py migrate
Setting up default send function:
email-verify is designed work out-of-the-box with Django's SMTP backend. If you want to keep to defaults, make sure to add the following configuration to your settings (assuming the hostname, host user and password are kept in environment variables):
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = os.environ.get('EMAIL_HOST')
EMAIL_PORT = 587 # or any other SMTP port your host is configured towards
EMAIL_HOST_USER = os.environ.get('EMAIL_HOST_USER')
EMAIL_HOST_PASSWORD = os.environ.get('EMAIL_HOST_PASSWORD')
EMAIL_USE_TLS = True # or False, depending on your host configuration
The above is the standard configuration for Django's SMTP backend.
Providing a custom send function:
If you don't want to use Django's default SMTP backend or have a specific function you'd rather use, provide the function in EMAIL_VERIFY_SEND_FUNC
in your settings.py
. The function provided should accept 2 arguments: user and verification_link. You can access user's e-mail through user.email
.
Below is an example for a custom emailing function. In this example, instead of actually sending an email, we print the token on the console (useful during dev):
# custom email function example:
# define a custom function
def custom_send_email(user,verification_link):
print(verification_link)
# settings.py
# set EMAIL_VERIFY_SEND_FUNC to your custom function
EMAIL_VERIFY_SEND_FUNC = custom_send_email
usage
email-verify creates a one-to-one relation with the built-in User model. Every time a new User is created and saved, email-verify will create a new EmailVerification record with is_verified set to false. On its own this has no effect on your project, except modifying your User model with an EmailVerification relation.
If you're using UserCreationForm
you can instead use EmailValidationUserCreation
for exposing email on sign-up. If EMAIL_VERIFY_ENFORCE_UNIQUE_EMAILS
is True
(default) a signal will trigger pre_save, and will throw a django.core.exceptions.ValidationError
. This will not be handled by the Form, as it only checks for email validity and non-emptiness.
If your SMTP configuration or custom emailing function is setup correctly, an email message will be delivered to the address used at registration as soon as a user registers. Lookout for custom EmailSendingException
on user.save(). No silent errors.
By default the following urlpattern will be used for the verification endpoint: verify_email/<str:token>/
If you want to use another endpoint for verification, be sure to set it up in your projects's url conf before including email_verify's url conf. Customized url pattern must have a <str:token>
.
The token is cryptographically signed using `itsdangerous` package. Message includes the user's id, current domain/host and a timestamp. The domain is not used for verification if `DEBUG=True` in `settings.py`, but in production, it checks against `ALLOWED_HOSTS` and will reject the token if the domain value is not found within the list. The timestamp is used to check against `EMAIL_VERIFY_EXPIRES_IN` (defaults to 3600 seconds) value to consider the token expired. If this value is not positive, the token won't expire.
custom redirections and template overriding
There are several ways you can customize email-verify
. You can bypass all view functionality by urlconf, as all logic is handled by signals during .save()
calls. You can provide redirect urls to EmailVerificationView
for success_url
and failure_url
, or you can overwrite the default templates at templates/email_verify/success.html
and templates/email_verify/failure.html
. For failure rendering, EmailVerificationView
will provide an error message in context: message
. For success rendering, it will provide a main_page
which can be provided via MAIN_PAGE
in settings.py (default '/'
) which will provide a link to your home page for the default success template.
cutom email subject, body and sender
Customize your subject field by providing EMAIL_VERIFY_SUBJECT_LINE
in settings.py
You can also customize the body of your email. Be sure to:
- Include the verification link via
$:_VERIFICATION_LINK
magic string somewhere - If you provide
EMAIL_VERIFY_HTML_MESSAGE
also provideEMAIL_VERIFY_TEXT_MESSAGE
as a fallback. You can change the sender email viaEMAIL_VERIFY_FROM_ADDRESS
Changelog
v0.1.2 (hotfix)
- Bugfix: e-mail uniqueness not enforced if email is empty
v0.1.1
- Introduced email uniqueness enforcing
- Decoupled emailing logic from Form and Views, email is sent via Signal receiver at time of creation
- Enhanced model:
-
- Removed
verified_by_admin
- Added
email_sent_status
,last_email_date
,verified_date
fields
- Removed
- Removed admin site registration
- Custom form no longer redirects
- Removed ***_TEMPLATE_NAME pattern
- Removed templates, urlconfs and views pertaining to email sending status
- Added
EmailSendingException
which can be used to handle email sending status by the user - Converted
email_verify:verify_email
to CBV. Uses success and failure redirections with failure message as query parameter. - Removed
is_valid
overwrite to useclean_email
, in-line with Django's built-in validation mechanisms.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for email_verify-0.1.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ae47ed2440235b75282563822c09bfb3168abe73c2ea510a977bfc93e3948536 |
|
MD5 | 0959392b18496aa95236848a9abd1897 |
|
BLAKE2b-256 | 5c40cd1b87b35f200b8dc4151d58b79c22e333d57f5f9356ed496ccb508ff977 |