simplelogincmd.rest.simplelogin.SimpleLogin

class SimpleLogin(client_cls: type = <class 'simplelogincmd.rest.client.Client'>)

Bases: object

SimpleLogin client

Constructor

Parameters:

client_cls (Type) – The type of simplelogincmd.rest.client.Client to use for handling requests, defaults to Client

Methods

create_contact	Create a new contact for the given alias
create_custom_alias	Create a new custom alias
create_mailbox	Create a new mailbox
create_random_alias	Create a new random alias
delete_alias	Delete an alias
delete_contact	Delete a contact
delete_mailbox	Delete a mailbox
get_alias	Get one of a user's aliases
get_alias_activities	Get a single page of an alias's activity records
get_alias_contacts	Get a single page of an alias's contacts
get_alias_options	Get options for a new custom alias
get_aliases	Get a page of the user's aliases
get_all_alias_activities	Get all the activity records for the given alias
get_all_alias_contacts	Get all of an alias's contacts
get_all_aliases	Get a list of all the user's aliases
get_mailboxes	Get all the user's mailboxes
is_authenticated	Whether the client is fully authenticated
is_mfa_waiting	Whether the client is waiting to be authenticated via MFA
login	Attempt to log in to SimpleLogin
logout	Log out of SimpleLogin
mfa	Attempt to authenticate via MFA
toggle_alias	Toggle an alias's enabled state
toggle_contact	Block or unblock a contact
update_alias	Modify an alias's properties
update_mailbox	Modify a mailbox's properties

Attributes

api_key	The api_key that verifies the user's identity to the API
mfa_key	The MFA key which SimpleLogin sends to verify an MFA request

property api_key: str | None

The api_key that verifies the user’s identity to the API

Returns:

The client’s API key, or None if the client is not yet authenticated. Almost all requests will fail without authentication

Return type:

str | None

create_contact(alias_id: int, contact: str) → tuple[bool, Contact | str]

Create a new contact for the given alias

See the Simplelogin documentation for an explanation of the parameters.

Returns:

Whether the creation succeeded, and the new contact or an error message, as appropriate

Return type:

tuple[bool, Contact | str]

Raises:

UnauthenticatedError – If self is not authenticated

create_custom_alias(*, alias_prefix: str, signed_suffix: str, mailbox_ids: list[int], note: str | None = None, name: str | None = None, hostname: str | None = None) → tuple[bool, Alias | str]

Create a new custom alias

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the creation succeeded, and the new alias or an error message, as appropriate

Return type:

tuple[bool, Alias | str]

Raises:

UnauthenticatedError – If self is not authenticated

create_mailbox(email: str) → tuple[bool, Mailbox | str]

Create a new mailbox

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether creation succeeded, and either an error message or the new mailbox, as appropriate

Return type:

tuple[bool, Mailbox | str]

Raises:

UnauthenticatedError – If self is not authenticated

create_random_alias(hostname: str | None = None, mode: str | None = None, note: str | None = None) → tuple[bool, Alias | str]

Create a new random alias

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the creation succeeded, and the new alias or an error message, as appropriate

Return type:

tuple[bool, Alias | str]

Raises:

UnauthenticatedError – If self is not authenticated

delete_alias(alias_id: int) → tuple[bool, str | None]

Delete an alias

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the deletion succeeded, and an optional error message

Return type:

tuple[bool, str | None]

Raises:

UnauthenticatedError – If self is not authenticated

delete_contact(contact_id: int) → tuple[bool, str | None]

Delete a contact

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the deletion succeeded, and an optional error message

Return type:

tuple[bool, str | None]

delete_mailbox(mailbox_id: int, transfer_aliases_to: int = -1) → tuple[bool, str | None]

Delete a mailbox

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the deletion succeeded, and an optional error message

Return type:

tuple[bool, str | None]

Raises:

UnauthenticatedError – If self is not authenticated

get_alias(alias_id: int) → tuple[bool, Alias | str]

Get one of a user’s aliases

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the operation succeeded, and either the alias or an error message, as appropriate

Return type:

tuple[bool, Alias | str]

Raises:

UnauthenticatedError – If self is not authenticated

get_alias_activities(alias_id: int, page_id: int = 0) → list[Activity]

Get a single page of an alias’s activity records

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

A list, which might be empty, of activities

Return type:

list[Activity]

Raises:

UnauthenticatedError – If self is not authenticated

get_alias_contacts(alias_id: int, page_id: int = 0) → list[Contact]

Get a single page of an alias’s contacts

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

A list, which might be empty, of contacts

Return type:

list[Contact]

Raises:

UnauthenticatedError – If self is not authenticated

get_alias_options(hostname: str | None = None) → tuple[bool, dict | str]

Get options for a new custom alias

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the operation succeeded, and the alias options or an error message, as appropriate. See SimpleLogin’s documentation for an explanation of the fields returned

Return type:

tuple[bool, dict | str]

Raises:

UnauthenticatedError – If self is not authenticated

get_aliases(page_id: int = 0, query: str | None = None) → list[Alias]

Get a page of the user’s aliases

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

A list, which might be empty, of aliases

Return type:

list[Alias]

Raises:

UnauthenticatedError – If self is not authenticated

get_all_alias_activities(alias_id: int) → list[Activity]

Get all the activity records for the given alias

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

A list, which might be empty, of activities

Return type:

list[Activity]

Raises:

UnauthenticatedError – If self is not authenticated

get_all_alias_contacts(alias_id: int) → list[Contact]

Get all of an alias’s contacts

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

A list, which might be empty, of contacts

Return type:

list[Contact]

Raises:

UnauthenticatedError – If self is not authenticated

get_all_aliases(query: str | None = None) → list[Alias]

Get a list of all the user’s aliases

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

A list, which might be empty, of aliases

Return type:

list[Alias]

Raises:

UnauthenticatedError – If self is not authenticated

get_mailboxes() → list[Mailbox]

Get all the user’s mailboxes

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

A list, which might be empty, of mailboxes

Return type:

list[Mailbox]

Raises:

UnauthenticatedError – If self is not authenticated

is_authenticated() → bool

Whether the client is fully authenticated

If so, the client is ready to use almost all of SimpleLogin’s functionality

Return type:

bool

is_mfa_waiting() → bool

Whether the client is waiting to be authenticated via MFA

If so, then the client is unable to make most requests. Note, however, that if it is not waiting, it’s not necessarily fully authenticated–it may not have made any authentication attempt at all, or may have failed. Use is_authenticated() to ensure that the login process has completed fully.

Return type:

bool

login(email: str, password: str, device: str | None = None) → tuple[bool, str | None]

Attempt to log in to SimpleLogin

Note that even if this returns True, the client might still not be fully authenticated. Use is_mfa_waiting() and is_authenticated() to check its state, and mfa() to attempt MFA if necessary.

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the login was successful, and an optional error message suitable for displaying to users

Return type:

tuple[bool, str | None]

logout() → bool

Log out of SimpleLogin

Returns:

Whether logout was successful (this is tecnically always True, because UnauthenticatedError is raised if the client is not logged in)

Return type:

bool

Raises:

UnauthenticatedError – If self is not authenticated

mfa(mfa_token: str, mfa_key: str, device: str | None = None) → tuple[bool, str | None]

Attempt to authenticate via MFA

This should never be used before calling login(). If it returns true, you can be certain that the client is fully authenticated

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether MFA was successful, and an optional error message suitable for displaying to the user

Return type:

tuple[bool, str | None]

property mfa_key: str | None

The MFA key which SimpleLogin sends to verify an MFA request

Returns:

The MFA key if any has been set

Return type:

str | None

toggle_alias(alias_id: int) → tuple[bool, bool | str]

Toggle an alias’s enabled state

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the toggle succeeded, and the alias’s new state or an error message, as appropriate

Return type:

tuple[bool, bool | str]

Raises:

UnauthenticatedError – If self is not authenticated

toggle_contact(contact_id: int) → tuple[bool, bool | str]

Block or unblock a contact

See the Simplelogin documentation for an explanation of the parameters.

Returns:

Whether the toggle succeeded, and the contact’s new state or an error message, as appropriate

Return type:

tuple[bool, bool | str]

update_alias(*, alias_id: int, note: str | None = None, name: str | None = None, mailbox_ids: list[int] | None = None, disable_pgp: bool | None = None, pinned: bool | None = None) → tuple[bool, str | None]

Modify an alias’s properties

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the update succeeded, and an optional error message

Return type:

tuple[bool, str | None]

Raises:

UnauthenticatedError – If self is not authenticated

update_mailbox(mailbox_id: int, email: str | None = None, default: bool | None = None, cancel_email_change: bool | None = None) → tuple[bool, str | None]

Modify a mailbox’s properties

See SimpleLogin’s documentation for an explanation of the parameters.

Returns:

Whether the update succeeded, and an optional error message

Return type:

tuple[bool, str | None]

Raises:

UnauthenticatedError – If self is not authenticated