Models

Django models for user authentication and email management

EmailAddress

Manages email addresses associated with user accounts, including verification status and primary email designation.

Fields

user · ForeignKey

Reference to the user model (settings.AUTH_USER_MODEL). On delete: CASCADE.

email · EmailField

The email address. Indexed for performance. Max length determined by ACCOUNT_EMAIL_MAX_LENGTH setting.

verified · BooleanField · default: "False"

Whether the email address has been verified.

primary · BooleanField · default: "False"

Whether this is the user’s primary email address. Only one email per user can be primary.

Methods

clean()

Normalizes the email address to lowercase before saving.

def clean(self):
    super().clean()
    self.email = self.email.lower()

can_set_verified()

Checks whether the email address can be marked as verified.

return · bool

Returns True if the email can be verified, False if there’s a conflict with UNIQUE_EMAIL setting.

email_address = EmailAddress.objects.get(pk=1)
if email_address.can_set_verified():
    email_address.set_verified()

set_verified(commit=True)

Marks the email address as verified.

commit · bool · default: "True"

Whether to save the change to the database immediately.

return · bool

Returns True if the email was successfully verified, False otherwise.

email_address.set_verified(commit=True)

set_as_primary(conditional=False)

Marks the email address as the user’s primary email.

conditional · bool · default: "False"

If True, only sets as primary if no other primary email exists.

return · bool

Returns True if successfully set as primary, False if conditional and another primary exists.

# Force set as primary
email_address.set_as_primary()

# Only set if no primary exists
email_address.set_as_primary(conditional=True)

send_confirmation(request=None, signup=False)

Creates and sends an email confirmation.

request · HttpRequest

The HTTP request object.

signup · bool · default: "False"

Whether this confirmation is for signup.

return · EmailConfirmation

Returns the created confirmation object.

confirmation = email_address.send_confirmation(request, signup=True)

remove()

Deletes the email address and updates the user’s email field if necessary.

email_address.remove()

Constraints

• unique_together: (user, email) - Each user can have each email address only once
• unique_primary_email: Only one primary email per user (enforced via UniqueConstraint)
• unique_verified_email: If UNIQUE_EMAIL is enabled, verified emails are unique across all users

---

EmailConfirmation

Represents an email confirmation request with a unique key.

Fields

email_address · ForeignKey

Reference to the EmailAddress being confirmed. On delete: CASCADE.

created · DateTimeField

When the confirmation was created. Defaults to current time.

sent · DateTimeField

When the confirmation email was sent.

key · CharField

Unique confirmation key (max length 64).

Class Methods

create(email_address)

Creates a new confirmation for an email address.

email_address · EmailAddress

The email address to create confirmation for.

return · EmailConfirmation

Returns the created confirmation object.

confirmation = EmailConfirmation.create(email_address)

from_key(key)

Retrieves a valid confirmation by its key.

key · str

The confirmation key.

return · EmailConfirmation | None

Returns the confirmation object if valid, None otherwise.

confirmation = EmailConfirmation.from_key("abc123")
if confirmation:
    confirmation.confirm(request)

Instance Methods

key_expired()

Checks if the confirmation key has expired.

return · bool

Returns True if expired, based on EMAIL_CONFIRMATION_EXPIRE_DAYS setting.

confirm(request)

Confirms the email address if the key hasn’t expired.

request · HttpRequest

The HTTP request object.

return · EmailAddress | None

Returns the confirmed EmailAddress, or None if expired.

email_address = confirmation.confirm(request)
if email_address:
    print(f"Confirmed: {email_address.email}")

send(request=None, signup=False)

Sends the confirmation email and updates the sent timestamp.

request · HttpRequest

The HTTP request object.

signup · bool · default: "False"

Whether this is for signup.

confirmation.send(request, signup=True)

---

EmailConfirmationHMAC

HMAC-based email confirmation (no database storage). Used when EMAIL_CONFIRMATION_HMAC is enabled.

Class Methods

create(email_address)

Creates an HMAC-based confirmation.

email_address · EmailAddress

The email address to confirm.

return · EmailConfirmationHMAC

Returns the confirmation object.

from_key(key)

Retrieves and validates an HMAC confirmation key.

key · str

The HMAC-signed key.

return · EmailConfirmationHMAC | None

Returns the confirmation if valid, None if expired or invalid.

Properties

key · str

The HMAC-signed confirmation key (read-only property).

Instance Methods

key_expired()

Always returns False as expiration is checked during signature validation.

confirm(request)

Confirms the email address.

request · HttpRequest

The HTTP request object.

return · EmailAddress | None

Returns the confirmed EmailAddress.

---

Login

Represents a user in the process of logging in. Used to track login state across requests.

Attributes

user · AbstractBaseUser | None

The user being logged in. Optional to prevent user enumeration.

email_verification · EmailVerificationMethod

Email verification method to use for this login.

redirect_url · str

URL to redirect to after login.

signal_kwargs · dict

Additional kwargs to pass to signals.

signup · bool · default: "False"

Whether this login is part of signup.

email · str

Email address used for login.

phone · str

Phone number used for login.

state · dict

Additional state dictionary.

initiated_at · float

Unix timestamp when login was initiated.

Constructor

login = Login(
    user=user,
    email_verification='optional',
    redirect_url='/dashboard/',
    signup=False,
    email='[e-mail]'
)

Methods

serialize()

Serializes the login state to a dictionary for session storage.

return · dict

Dictionary containing all login state.

login_data = login.serialize()
request.session['login_state'] = login_data

deserialize(data)

Class method to reconstruct a Login object from serialized data.

data · dict

Serialized login data.

return · Login

Reconstructed Login object.

login_data = request.session.get('login_state')
login = Login.deserialize(login_data)

---

Utility Functions

get_emailconfirmation_model()

Returns the appropriate email confirmation model class based on settings.

return · type

Returns EmailConfirmation, EmailConfirmationHMAC, or raises NotImplementedError for code-based verification.

from allauth.account.models import get_emailconfirmation_model

ConfirmationModel = get_emailconfirmation_model()
confirmation = ConfirmationModel.from_key(key)

Usage Examples

Managing Email Addresses

from allauth.account.models import EmailAddress

# Add a new email address
email = EmailAddress.objects.create(
    user=request.user,
    email='[e-mail]',
    verified=False
)

# Send confirmation
confirmation = email.send_confirmation(request)

# After user confirms
if email.can_set_verified():
    email.set_verified()
    email.set_as_primary()

Working with Confirmations

from allauth.account.models import EmailConfirmation, get_emailconfirmation_model

# Create confirmation
ConfirmationModel = get_emailconfirmation_model()
confirmation = ConfirmationModel.create(email_address)
confirmation.send(request, signup=True)

# Verify confirmation
confirmation = ConfirmationModel.from_key(key)
if confirmation and not confirmation.key_expired():
    email_address = confirmation.confirm(request)

Login State Management

from allauth.account.models import Login

# Create login state
login = Login(
    user=user,
    email=user.email,
    redirect_url='/dashboard/',
    signup=False
)

# Store in session
request.session['pending_login'] = login.serialize()

# Restore from session
login_data = request.session.get('pending_login')
if login_data:
    login = Login.deserialize(login_data)