Skip to main content

​
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='[email protected]'
)

​
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='[email protected]',
    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)

Build docs developers (and LLMs) love

Get started for freeTalk to us