### Install Utility Packages

Source: https://github.com/simple-login/app/blob/master/README.md

Installs 'dnsutils' for verifying DNS configurations. Run this command on your server.

```bash
sudo apt update && sudo apt install -y dnsutils
```

--------------------------------

### Configure Local Environment Variables

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Copies the example environment file to .env for local configuration. You will need to edit the DB_URI to match your PostgreSQL setup.

```bash
cp example.env .env
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Installs all project dependencies using uv. It's recommended to use a virtual environment.

```bash
uv sync
```

--------------------------------

### Install Docker using get.docker.com

Source: https://github.com/simple-login/app/blob/master/README.md

Installs Docker CE on your server using the official convenience script. Ensure you have `curl` installed.

```bash
curl -fsSL https://get.docker.com | sh
```

--------------------------------

### Install Project Dependencies with uv

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Install all project dependencies using uv. This command should be run after activating the virtual environment.

```bash
uv install
```

--------------------------------

### Install npm Packages for Frontend

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Navigates to the static directory and installs necessary npm packages for the frontend.

```bash
cd static && npm install
```

--------------------------------

### Initiate Extension Setup

Source: https://github.com/simple-login/app/blob/master/templates/onboarding/setup.html

This JavaScript code sends a message to the extension to perform setup. It is designed to be sent multiple times in case the extension's listener is not immediately ready.

```javascript
function sendSetupMessage(){
 const data = { tag: "PERFORM_EXTENSION_SETUP" };
 window.postMessage(data, "/");
}

let counterIterations = 5;
let extensionSetupIntervalId = setInterval(function() {
 counterIterations--;
 if (counterIterations === 0) {
  clearInterval(extensionSetupIntervalId);
  return;
 }
 sendSetupMessage()
}, 300);
// Send it many times, in case the extension had not registered the listener yet
```

--------------------------------

### Install uv using the official script

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Install the uv package manager by downloading and running the official installation script. This method is recommended to ensure uv uses Python 3.12.

```bash
curl -sSL https://install.python-uv.org | python3 -
```

--------------------------------

### Get Alias Creation Options (GET /api/v5/alias/options)

Source: https://context7.com/simple-login/app/llms.txt

Returns available suffixes, a prefix suggestion, and an alias recommendation. Use this before creating an alias to obtain a valid `signed_suffix`.

```bash
# Without hostname
curl -s "https://app.simplelogin.io/api/v5/alias/options" \
  -H "Authentication: SL-abc123xyz"
```

```bash
# With hostname for smart suggestions
curl -s "https://app.simplelogin.io/api/v5/alias/options?hostname=www.amazon.com" \
  -H "Authentication: SL-abc123xyz"
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Installs pre-commit to run linting and static analysis checks automatically. Run this in your development environment.

```bash
uv run pre-commit install
```

--------------------------------

### Install postfix-pcre

Source: https://github.com/simple-login/app/blob/master/docs/enforce-spf.md

Install the postfix-pcre package to enable PCRE-based content filtering for Postfix.

```bash
apt install -y postfix-pcre
```

--------------------------------

### Install Postfix and Postfix-Pgsql

Source: https://github.com/simple-login/app/blob/master/README.md

Installs the Postfix Mail Transfer Agent and the PostgreSQL backend for Postfix configuration. Requires root privileges.

```bash
sudo apt-get install -y postfix postfix-pgsql -y
```

--------------------------------

### Repeatedly Send Extension Setup Message

Source: https://github.com/simple-login/app/blob/master/templates/onboarding/setup_done.html

Use this JavaScript code to repeatedly send a setup message to the extension. It ensures the extension registers the listener by sending the message multiple times with a delay. The process stops after a set number of iterations.

```javascript
let counterIterations = 5; let extensionSetupIntervalId = setInterval(function() { counterIterations--; if (counterIterations === 0) { clearInterval(extensionSetupIntervalId); return; } const data = { tag: "PERFORM_EXTENSION_SETUP" }; window.postMessage(data, "/"); }, 300); // Send it many times, in case the extension had not registered the listener yet
```

--------------------------------

### Initialize SimpleLogin Intro JS

Source: https://github.com/simple-login/app/blob/master/templates/footer.html

Starts the intro.js tour for the SimpleLogin application. Ensure intro.js is loaded before calling this function.

```javascript
function startIntro() { introJs().setOption('showProgress', true).start(); introJs().start(); }
```

--------------------------------

### Install SASL Package for Postfix

Source: https://github.com/simple-login/app/blob/master/docs/ses.md

Install the necessary SASL package for Postfix to handle authentication. This is typically required on Ubuntu systems.

```bash
sudo apt install libsasl2-modules
```

--------------------------------

### Run Server and Apply Migrations

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Applies database migrations, populates dummy data, and starts the SimpleLogin server. Access the application at http://localhost:7777.

```bash
alembic upgrade head && flask dummy-data && python3 server.py
```

--------------------------------

### Install macOS Dependencies

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Installs necessary packages on macOS using brew, including pkg-config, libffi, openssl, and postgresql@13.

```bash
brew install pkg-config libffi openssl postgresql@13
```

--------------------------------

### Install GPG Tool on macOS

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Installs the gnupg tool on macOS using brew, which might be required for certain operations.

```bash
brew install gnupg
```

--------------------------------

### Show Intro JS Conditionally

Source: https://github.com/simple-login/app/blob/master/templates/dashboard/index.html

Conditionally starts the introJs() tour based on window width. Ensure intro.js is included and configured.

```javascript
if (window.innerWidth >= 1024) {
  introJs().start();
}
```

--------------------------------

### Install Python 3.10 on Mac

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Install Python 3.10 using Homebrew on a Mac silicon. Note that Python 3.12 may not work reliably.

```bash
brew install python3.10
```

--------------------------------

### Example CAA DNS Record Response

Source: https://github.com/simple-login/app/blob/master/docs/ssl.md

This is an example of the expected output when querying for a CAA record, confirming that only Let's Encrypt is authorized to issue certificates.

```dns
mydomain.com.	3600	IN	CAA	0 issue "letsencrypt.org"
```

--------------------------------

### Install RE2 and Pybind11 Dependencies

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Installs RE2 and Pybind11 dependencies on macOS using brew, which may be needed if encountering pyre2 package errors.

```bash
brew install -s re2 pybind11
```

--------------------------------

### Initialize QR Code Generator (JavaScript)

Source: https://github.com/simple-login/app/blob/master/templates/dashboard/mfa_setup.html

Initializes a QRious instance to display a QR code for MFA setup. Ensure the QRious library is loaded before this script.

```javascript
(function () { var qr = new QRious({ element: document.getElementById('qr'), value: '{{otp_uri}}' }); })();
```

--------------------------------

### SimpleLogin Docker Environment Variables

Source: https://github.com/simple-login/app/blob/master/README.md

Example .env file for configuring SimpleLogin Docker containers. Key parameters include URL, email domain, support email, and DKIM path.

```.env
# WebApp URL
URL=http://app.mydomain.com

# domain used to create alias
EMAIL_DOMAIN=mydomain.com

# transactional email is sent from this email address
SUPPORT_EMAIL=support@mydomain.com

# custom domain needs to point to these MX servers
EMAIL_SERVERS_WITH_PRIORITY=[(10, "app.mydomain.com.")]

# By default, new aliases must end with ".{random_word}". This is to avoid a person taking all "nice" aliases.
# this option doesn't make sense in self-hosted. Set this variable to disable this option.
DISABLE_ALIAS_SUFFIX=1

# the DKIM private key used to compute DKIM-Signature
DKIM_PRIVATE_KEY_PATH=/dkim.key
```

--------------------------------

### Run All Tests

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Executes all project tests. Requires Redis to be installed and running on port 6379.

```bash
sh scripts/run-test.sh
```

--------------------------------

### Run PostgreSQL Docker Container

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Starts a PostgreSQL 13 Docker container with specified user, password, and database name, exposing port 5432.

```bash
docker run -e POSTGRES_PASSWORD=mypassword -e POSTGRES_USER=myuser -e POSTGRES_DB=simplelogin -p 15432:5432 postgres:13
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Activate the project's virtual environment. This ensures that the correct Python interpreter and installed packages are used.

```bash
source .venv/bin/activate
```

--------------------------------

### Get alias creation options

Source: https://context7.com/simple-login/app/llms.txt

Retrieves available suffixes, a prefix suggestion, and an alias recommendation for alias creation. This should be called before creating an alias to obtain a valid `signed_suffix`.

```APIDOC
## GET /api/v5/alias/options — Get alias creation options

### Description
Returns available suffixes, a prefix suggestion based on the current hostname, and an existing alias recommendation. Use this before calling the alias creation endpoints to obtain a valid `signed_suffix`.

### Method
GET

### Endpoint
https://app.simplelogin.io/api/v5/alias/options

### Parameters
#### Query Parameters
- **hostname** (string) - Optional - The hostname to use for smart suggestions.

### Response
#### Success Response (200)
- **can_create** (boolean) - Indicates if a new alias can be created.
- **prefix_suggestion** (string) - A suggested prefix for the alias.
- **recommendation** (object) - An alias recommendation.
  - **alias** (string) - The recommended alias.
  - **hostname** (string) - The hostname associated with the recommendation.
- **suffixes** (array) - A list of available suffixes.
  - **suffix** (string) - The alias suffix.
  - **signed_suffix** (string) - The signed suffix required for alias creation.
  - **is_custom** (boolean) - Whether the suffix is custom.
  - **is_premium** (boolean) - Whether the suffix requires a premium plan.
```

--------------------------------

### Run Webapp Container with Docker

Source: https://github.com/simple-login/app/blob/master/README.md

Start the SimpleLogin web application container in detached mode. This command maps ports and ensures the container restarts automatically.

```bash
docker run -d \
    --name sl-app \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -p 127.0.0.1:7777:7777 \
    --restart always \
    --network="sl-network" \
    simplelogin/app:3.4.0
```

--------------------------------

### Get User Aliases

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves a list of user aliases, supporting pagination and filtering by pinned, enabled, or disabled status. Use GET for requests with query parameters or POST if GET requests with bodies are not supported.

```json
{
  "aliases": [
    {
      "creation_date": "2020-04-06 17:57:14+00:00",
      "creation_timestamp": 1586195834,
      "email": "prefix1.cat@sl.lan",
      "name": "A Name",
      "enabled": true,
      "id": 3,
      "mailbox": {
        "email": "a@b.c",
        "id": 1
      },
      "mailboxes": [
        {
          "email": "m1@cd.ef",
          "id": 2
        },
        {
          "email": "john@wick.com",
          "id": 1
        }
      ],
      "latest_activity": {
        "action": "forward",
        "contact": {
          "email": "c1@example.com",
          "name": null,
          "reverse_alias": "\"c1 at example.com\" <re1@SL>"
        },
        "timestamp": 1586195834
      },
      "nb_block": 0,
      "nb_forward": 1,
      "nb_reply": 0,
      "note": null,
      "pinned": true
    }
  ]
}
```

--------------------------------

### Initialize Application Data with Docker

Source: https://github.com/simple-login/app/blob/master/README.md

Populate the database with initial data using the provided Python script inside a Docker container. Mount volumes for configuration and keys.

```bash
docker run --rm \
    --name sl-init \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    --network="sl-network" \
    simplelogin/app:3.4.0 python init_app.py
```

--------------------------------

### Create Docker Buildx Environment

Source: https://github.com/simple-login/app/blob/master/docs/build-image.md

Run this command once to set up a new buildx environment or context. It ensures you have a builder instance ready for multi-platform builds.

```bash
docker buildx create --use
```

--------------------------------

### Create PGP and Database Directories

Source: https://github.com/simple-login/app/blob/master/docs/upgrade.md

Create necessary directories for PGP keys and database storage when upgrading to SimpleLogin 2.1.0 from 2.0.0 if PGP support is to be used.

```bash
mkdir sl
mkdir sl/pgp # to store PGP key
mkdir sl/db # to store database
```

--------------------------------

### Create SimpleLogin Data Directories

Source: https://github.com/simple-login/app/blob/master/README.md

Creates necessary directories to store SimpleLogin data, including PGP keys, database files, and quarantine emails. These should be created in a designated 'sl' directory.

```bash
mkdir sl
mkdir sl/pgp # to store PGP key
mkdir sl/db # to store database
mkdir sl/upload # to store quarantine emails
```

--------------------------------

### Configure Postfix Client Headers

Source: https://github.com/simple-login/app/blob/master/docs/enforce-spf.md

Create a Postfix client_headers file to prepend the X-SimpleLogin-Client-IP header with the client's IP address. This is crucial for SPF enforcement.

```regex
/^([0-9a-f:.]+)$/ prepend X-SimpleLogin-Client-IP: $1
```

--------------------------------

### Start Mailcatcher for Email Testing

Source: https://github.com/simple-login/app/blob/master/CONTRIBUTING.md

Start Mailcatcher, a simple MTA, to receive and inspect test emails. This is the first step in setting up email handler testing.

```bash
mailcatcher
```

--------------------------------

### Login with MFA Enabled (Step 1)

Source: https://context7.com/simple-login/app/llms.txt

Initiates login for users with Multi-Factor Authentication enabled. This call returns an 'mfa_key' which is required for the subsequent MFA completion step.

```bash
curl -s -X POST https://app.simplelogin.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "s3cr3t!", "device": "my-laptop"}'
# Response 200:
# { "mfa_enabled": true, "mfa_key": "<signed-user-id>", "api_key": null }
```

--------------------------------

### Login with Email and Password (No MFA)

Source: https://context7.com/simple-login/app/llms.txt

Use this endpoint to authenticate a user and obtain an API key for subsequent requests. Ensure the 'Content-Type' header is set to 'application/json'.

```bash
curl -s -X POST https://app.simplelogin.io/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "password": "s3cr3t!", "device": "my-laptop"}'
# Response 200:
# {
#   "name": "Alice",
#   "email": "alice@example.com",
#   "mfa_enabled": false,
#   "mfa_key": null,
#   "api_key": "SL-abc123xyz..."
# }
```

--------------------------------

### Run Database Migration with Docker

Source: https://github.com/simple-login/app/blob/master/README.md

Prepare the database by running the migration script within a Docker container. Ensure necessary volumes are mounted.

```bash
docker run --rm \
    --name sl-migration \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -v $(pwd)/simplelogin.env:/code/.env \
    --network="sl-network" \
    simplelogin/app:3.4.0 flask db upgrade
```

--------------------------------

### Get Usage Statistics (GET /api/stats)

Source: https://context7.com/simple-login/app/llms.txt

Retrieves usage statistics for the current user, including counts of aliases, forwarded emails, blocked emails, and replied-to emails.

```bash
curl -s https://app.simplelogin.io/api/stats \
  -H "Authentication: SL-abc123xyz"
```

--------------------------------

### Get User Aliases

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves a list of user aliases. Supports filtering by pinned, disabled, or enabled status. Can also be invoked using POST if GET with a body is not supported.

```APIDOC
## GET /api/v2/aliases

### Description
Get user aliases. Supports pagination and filtering.

### Method
GET or POST

### Endpoint
/api/v2/aliases

### Parameters
#### Query Parameters
- **page_id** (integer) - Required - Used for pagination. Returns a maximum of 20 aliases per page. Starts at 0.
- **pinned** (boolean) - Optional - If set, only pinned aliases are returned.
- **disabled** (boolean) - Optional - If set, only disabled aliases are returned.
- **enabled** (boolean) - Optional - If set, only enabled aliases are returned. Note: `pinned`, `disabled`, and `enabled` are mutually exclusive.

#### Request Body
- **query** (object) - Optional - Used for filtering when GET request body is not supported. (See Query Parameters for fields)

### Response
#### Success Response (200)
- **aliases** (array) - A list of alias objects. Each alias contains fields like `id`, `email`, `name`, `enabled`, `creation_timestamp`, `note`, `nb_block`, `nb_forward`, `nb_reply`, `support_pgp`, `disable_pgp`, `mailbox`, `mailboxes`, `latest_activity`, and `pinned`.

#### Response Example
```json
{
  "aliases": [
    {
      "creation_date": "2020-04-06 17:57:14+00:00",
      "creation_timestamp": 1586195834,
      "email": "prefix1.cat@sl.lan",
      "name": "A Name",
      "enabled": true,
      "id": 3,
      "mailbox": {
        "email": "a@b.c",
        "id": 1
      },
      "mailboxes": [
        {
          "email": "m1@cd.ef",
          "id": 2
        },
        {
          "email": "john@wick.com",
          "id": 1
        }
      ],
      "latest_activity": {
        "action": "forward",
        "contact": {
          "email": "c1@example.com",
          "name": null,
          "reverse_alias": "\"c1 at example.com\" <re1@SL>"
        },
        "timestamp": 1586195834
      },
      "nb_block": 0,
      "nb_forward": 1,
      "nb_reply": 0,
      "note": null,
      "pinned": true
    }
  ]
}
```
```

--------------------------------

### Test Email Sending with swaks

Source: https://github.com/simple-login/app/blob/master/docs/troubleshooting.md

Use `swaks` to test if Postfix can send emails to your specified mailbox. Install `swaks` using `sudo apt install swaks` on Debian-based systems.

```bash
swaks --to your-mailbox@mail.com
```

--------------------------------

### Postfix Configuration

Source: https://github.com/simple-login/app/blob/master/README.md

This is the content for `/etc/postfix/main.cf`. Ensure `mydomain.com` is replaced with your actual domain. This configuration is adapted for SimpleLogin.

```postfix
# POSTFIX config file, adapted for SimpleLogin
smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no

# appending .domain is the MUA's job.
append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h

readme_directory = no

# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 2 on
# fresh installs.
compatibility_level = 2

# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
smtp_tls_security_level = may
smtpd_tls_security_level = may

```

--------------------------------

### Get Alias Info

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves detailed information for a specific alias using its ID.

```APIDOC
## GET /api/aliases/:alias_id

### Description
Get alias info by its ID.

### Method
GET

### Endpoint
/api/aliases/:alias_id

### Parameters
#### Path Parameters
- **alias_id** (integer) - Required - The ID of the alias to retrieve.

### Response
#### Success Response (200)
- Alias info in the same format as returned by `/api/v2/aliases`.

#### Response Example
```json
{
  "creation_date": "2020-04-06 17:57:14+00:00",
  "creation_timestamp": 1586195834,
  "email": "prefix1.cat@sl.lan",
  "name": "A Name",
  "enabled": true,
  "id": 3,
  "mailbox": {
    "email": "a@b.c",
    "id": 1
  },
  "mailboxes": [
    {
      "email": "m1@cd.ef",
      "id": 2
    },
    {
      "email": "john@wick.com",
      "id": 1
    }
  ],
  "latest_activity": {
    "action": "forward",
    "contact": {
      "email": "c1@example.com",
      "name": null,
      "reverse_alias": "\"c1 at example.com\" <re1@SL>"
    },
    "timestamp": 1586195834
  },
  "nb_block": 0,
  "nb_forward": 1,
  "nb_reply": 0,
  "note": null,
  "pinned": true
}
```
```

--------------------------------

### Get Alias

Source: https://context7.com/simple-login/app/llms.txt

Retrieves the full details for a single alias using its numeric ID.

```APIDOC
## GET /api/aliases/:alias_id — Get a single alias

### Description
Returns full detail for one alias by its numeric ID.

### Method
GET

### Endpoint
/api/aliases/{alias_id}

#### Path Parameters
- **alias_id** (integer) - Required - The ID of the alias to retrieve.

### Request Example
```bash
curl -s "https://app.simplelogin.io/api/aliases/99" \
  -H "Authentication: SL-abc123xyz"
```

### Response
#### Success Response (200)
Returns a single alias object with the same schema as the list response.

#### Error Response (403)
- **error** (string) - "Forbidden" if the alias is not found or not owned by the user.
```json
{ "error": "Forbidden" }
```
```

--------------------------------

### Build and Push Multi-Architecture Image

Source: https://github.com/simple-login/app/blob/master/docs/build-image.md

Builds and pushes Docker images for specified platforms (e.g., linux/amd64, linux/arm64) to a registry. Replace `simplelogin/name:tag` with your image's name and tag.

```bash
docker buildx build --platform linux/amd64,linux/arm64 --push -t simplelogin/name:tag
```

--------------------------------

### Get Reservation Messages

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves messages associated with a specific reservation, indicating if the reservation has ended.

```APIDOC
## GET /api/phone/reservations/:reservation_id

### Description
Get messages received during a reservation.

### Method
GET

### Endpoint
/api/phone/reservations/:reservation_id

### Parameters
#### Header Parameters
- **Authentication** (string) - Required - The api key
#### Path Parameters
- **reservation_id** (string) - Required - The ID of the reservation

### Response
#### Success Response (200)
- **ended** (boolean) - Indicates if the reservation has ended.
- **messages** (array) - A list of messages for this reservation.
  - **body** (string) - The content of the message.
  - **created_at** (string) - The timestamp when the message was created.
  - **from_number** (string) - The phone number from which the message was sent.
  - **id** (integer) - The unique identifier for the message.

### Response Example
```json
{
  "ended": false,
  "messages": [
    {
      "body": "body",
      "created_at": "just now",
      "from_number": "from_number",
      "id": 7
    }
  ]
}
```
```

--------------------------------

### Create New API Key (POST /api/api_key)

Source: https://context7.com/simple-login/app/llms.txt

Creates a new API key. The key is named after the provided device string.

```bash
curl -s -X POST https://app.simplelogin.io/api/api_key \
  -H "Authentication: SL-abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{"device": "firefox-extension"}'
```

--------------------------------

### Get User Mailboxes

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves a list of the user's mailboxes, including unverified ones.

```APIDOC
## GET /api/v2/mailboxes

### Description
Get user's mailboxes, including unverified ones.

### Method
GET

### Endpoint
/api/v2/mailboxes

### Parameters
#### Headers
- **Authentication** (string) - Required - Contains the api key.

### Response
#### Success Response (200)
- **mailboxes** (array) - A list of mailboxes.
  - **email** (string) - The email address of the mailbox.
  - **id** (integer) - The unique identifier of the mailbox.
  - **default** (boolean) - Indicates if this is the default mailbox.
  - **creation_timestamp** (integer) - The timestamp when the mailbox was created.
  - **nb_alias** (integer) - The number of aliases associated with this mailbox.
  - **verified** (boolean) - Indicates if the mailbox is verified.

### Response Example
```json
{
  "mailboxes": [
    {
      "email": "a@b.c",
      "id": 1,
      "default": true,
      "creation_timestamp": 1590918512,
      "nb_alias": 10,
      "verified": true
    }
  ]
}
```
```

--------------------------------

### Register New Account

Source: https://context7.com/simple-login/app/llms.txt

Creates a new user account. A 6-digit activation code will be sent to the provided email address. Note the potential error responses for password length and registration status.

```bash
curl -s -X POST https://app.simplelogin.io/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "bob@example.com", "password": "mypassword123"}'
# Response 200:
# { "msg": "User needs to confirm their account" }

# Password too short:
# Response 400: { "error": "password too short" }

# Registration closed:
# Response 400: { "error": "registration is closed" }
```

--------------------------------

### Get Contacts for Alias

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves a list of contacts associated with a specific alias. Supports pagination.

```APIDOC
## GET /api/aliases/:alias_id/contacts

### Description
Get contacts for a given alias.

### Method
GET

### Endpoint
/api/aliases/:alias_id/contacts

### Parameters
#### Path Parameters
- **alias_id** (string) - Required - The alias id.

#### Query Parameters
- **page_id** (integer) - Required - Used for pagination. Starts at 0. Returns a maximum of 20 contacts per page.

#### Headers
- **Authentication** (string) - Required - Contains the api key.

### Response
#### Success Response (200)
- **contacts** (array) - A list of contacts.
  - **id** (integer) - The contact's unique identifier.
  - **contact** (string) - The contact's email address or identifier.
  - **creation_date** (string) - The date and time the contact was created.
  - **creation_timestamp** (integer) - The timestamp when the contact was created.
  - **last_email_sent_date** (string) - The date and time of the last email sent to this contact (can be null).
  - **last_email_sent_timestamp** (integer) - The timestamp of the last email sent to this contact (can be null).
  - **reverse_alias** (string) - The reverse alias associated with the contact.
  - **reverse_alias_address** (string) - The reverse alias email address (optional).
  - **block_forward** (boolean) - Indicates if forwarding is blocked for this contact.

### Response Example
```json
{
  "contacts": [
    {
      "id": 1,
      "contact": "marketing@example.com",
      "creation_date": "2020-02-21 11:35:00+00:00",
      "creation_timestamp": 1582284900,
      "last_email_sent_date": null,
      "last_email_sent_timestamp": null,
      "reverse_alias": "marketing at example.com <reply+bzvpazcdedcgcpztehxzgjgzmxskqa@sl.co>",
      "block_forward": false
    }
  ]
}
```
```

--------------------------------

### Get Alias Activities

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves a list of activities associated with a specific alias, with pagination support.

```APIDOC
## GET /api/aliases/:alias_id/activities

### Description
Get activities for a given alias.

### Method
GET

### Endpoint
/api/aliases/:alias_id/activities

### Parameters
#### Path Parameters
- **alias_id** (integer) - Required - The ID of the alias.
#### Query Parameters
- **page_id** (integer) - Required - Used for pagination. Returns a maximum of 20 activities per page. Starts at 0.

### Response
#### Success Response (200)
- **activities** (array) - A list of activity objects. Each activity includes `action`, `from`, `timestamp`, `to`, `reverse_alias`, and `reverse_alias_address`.

#### Response Example
```json
{
  "activities": [
    {
      "action": "reply",
      "from": "yes_meo_chat@sl.lan",
      "timestamp": 1580903760,
      "to": "marketing@example.com",
      "reverse_alias": "\"marketing at example.com\" <reply@a.b>",
      "reverse_alias_address": "reply@a.b"
    }
  ]
}
```
```

--------------------------------

### Test Postfix Connectivity from Docker Container

Source: https://github.com/simple-login/app/blob/master/docs/troubleshooting.md

Connect to the `sl-app` container and use `telnet` to test connectivity to Postfix on the host. If `telnet 10.0.0.1 25` fails, try `telnet 172.17.0.1 25` and consider setting `POSTFIX_SERVER=172.17.0.1` in your `~/simplelogin.env` file.

```bash
docker exec -it sl-app bash
```

```bash
apt update
apt install telnet -y
telnet 10.0.0.1 25
```

--------------------------------

### GET /api/user/cookie_token

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Generates a one-time use token that can be exchanged for a valid cookie in the web application.

```APIDOC
## GET /api/user/cookie_token

### Description
Generates a single-use token that can be used by the web application to obtain a valid session cookie for the user.

### Method
GET

### Endpoint
/api/user/cookie_token

### Parameters
#### Headers
- **Authentication** (string) - Required - The API Key obtained after login.

### Response
#### Success Response (200)
- **token** (string) - The generated one-time use token.

#### Example Response
```json
{"token": "token value"}
```

#### Error Response (403)
- **error** (string) - A message indicating the reason for the error, e.g., "Some error".

#### Error Response (401)
Returned if the provided API Key is incorrect or invalid.
```

--------------------------------

### Register New User

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Register a new user with their email and password. A successful request prompts the user to check their email for an activation code.

```json
{
  "email": "newuser@example.com",
  "password": "securepassword"
}
```

--------------------------------

### GET /api/stats

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves statistics about the user's account, such as the number of aliases and forwarded emails.

```APIDOC
## GET /api/stats

### Description
Retrieves statistical data related to the user's account, including the count of aliases, blocked emails, forwarded emails, and replied emails.

### Method
GET

### Endpoint
/api/stats

### Parameters
#### Headers
- **Authentication** (string) - Required - The API Key obtained after login.

### Response
#### Success Response (200)
- **nb_alias** (integer) - The total number of aliases created.
- **nb_block** (integer) - The number of blocked emails.
- **nb_forward** (integer) - The number of emails forwarded.
- **nb_reply** (integer) - The number of emails replied to.

#### Example Response
```json
{"nb_alias": 1, "nb_block": 0, "nb_forward": 0, "nb_reply": 0}
```

#### Error Response (401)
Returned if the provided API Key is incorrect or invalid.
```

--------------------------------

### Get User Settings

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves the current user settings, including alias generation preferences and domain settings.

```json
{
  "alias_generator": "word",
  "notification": true,
  "random_alias_default_domain": "sl.lan",
  "sender_format": "AT",
  "random_alias_suffix": "random_string"
}
```

--------------------------------

### Run SimpleLogin Webapp Container

Source: https://github.com/simple-login/app/blob/master/docs/upgrade.md

Command to run the SimpleLogin webapp container using Docker. Ensure all necessary volumes and network configurations are correctly set.

```bash
sudo docker run -d \
    --name sl-app \
    -v $(pwd)/sl:/sl \
    -v $(pwd)/sl/upload:/code/static/upload \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/dkim.pub.key:/dkim.pub.key \
    -p 127.0.0.1:7777:7777 \
    --restart always \
    --network="sl-network" \
    simplelogin/app:3.4.0
```

--------------------------------

### Get User Alias Options

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves user alias information and suggestions, used for the first extension screen.

```APIDOC
## GET /api/v5/alias/options

### Description
User alias info and suggestion. Used by the first extension screen when user opens the extension.

### Method
GET

### Endpoint
/api/v5/alias/options

### Parameters
#### Headers
- **Authentication** (string) - Required - API key for authentication
#### Query Parameters
- **hostname** (string) - Optional - The hostname to get alias suggestions for.

### Response
#### Success Response (200)
- **can_create** (boolean) - Whether user can create new alias
- **suffixes** (list) - List of alias suffixes that user can use. Each item is a dictionary with `suffix`, `signed-suffix`, `is_custom`, `is_premium` as keys.
- **prefix_suggestion** (string) - Suggestion for the `alias prefix`. Usually this is the website name extracted from `hostname`.
- **recommendation** (object) - Optional field. If an alias is already used for this website, the recommendation will be returned. Contains `alias` and `hostname` subfields.

#### Response Example
```json
{
  "can_create": true,
  "prefix_suggestion": "test",
  "suffixes": [
    {
      "signed_suffix": ".cat@d1.test.X6_7OQ.0e9NbZHE_bQvuAapT6NdBml9m6Q",
      "suffix": ".cat@d1.test",
      "is_custom": true,
      "is_premium": false
    },
    {
      "signed_suffix": ".chat@d2.test.X6_7OQ.TTgCrfqPj7UmlY723YsDTHhkess",
      "suffix": ".chat@d2.test",
      "is_custom": false,
      "is_premium": false
    },
    {
      "signed_suffix": ".yeah@sl.lan.X6_7OQ.i8XL4xsMsn7dxDEWU8eF-Zap0qo",
      "suffix": ".yeah@sl.lan",
      "is_custom": true,
      "is_premium": false
    }
  ]
}
```
```

--------------------------------

### Log Out Web Session (GET /api/logout)

Source: https://context7.com/simple-login/app/llms.txt

Removes the web session cookie. This is useful when using cookie-based authentication from a browser.

```bash
curl -s https://app.simplelogin.io/api/logout \
  -H "Authentication: SL-abc123xyz"
```

--------------------------------

### Login with Email and Password

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Use this endpoint to log in with email and password. It returns user details and an API key if MFA is not enabled. If MFA is enabled, it returns an MFA key for the next step. FIDO-enabled users will receive a 403 error.

```json
{
  "email": "user@example.com",
  "password": "yourpassword",
  "device": "My Device Name"
}
```

--------------------------------

### Configure GnuPG Home Directory

Source: https://github.com/simple-login/app/blob/master/docs/upgrade.md

Add this line to your simplelogin.env file to specify the location for storing PGP keys when upgrading to SimpleLogin 2.1.0.

```env
GNUPGHOME=/sl/pgp # where to store PGP keys
```

--------------------------------

### API Error Response Example

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Illustrates the structure of an error response from the API, typically returned with a 4xx status code.

```json
{
  "error": "Error message"
}
```

--------------------------------

### Make User Account Premium

Source: https://github.com/simple-login/app/blob/master/README.md

Update the 'users' table in the PostgreSQL database to set the 'lifetime' column to TRUE for a user account to become premium.

```bash
docker exec -it sl-db psql -U myuser simplelogin
UPDATE users SET lifetime = TRUE;
exit
```

--------------------------------

### Get Alias Info

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves detailed information for a specific alias using its ID. The output format is consistent with the list of aliases.

```json
{
  "creation_date": "2020-04-06 17:57:14+00:00",
  "creation_timestamp": 1586195834,
  "email": "prefix1.cat@sl.lan",
  "name": "A Name",
  "enabled": true,
  "id": 3,
  "mailbox": {
    "email": "a@b.c",
    "id": 1
  },
  "mailboxes": [
    {
      "email": "m1@cd.ef",
      "id": 2
    },
    {
      "email": "john@wick.com",
      "id": 1
    }
  ],
  "latest_activity": {
    "action": "forward",
    "contact": {
      "email": "c1@example.com",
      "name": null,
      "reverse_alias": "\"c1 at example.com\" <re1@SL>"
    },
    "timestamp": 1586195834
  },
  "nb_block": 0,
  "nb_forward": 1,
  "nb_reply": 0,
  "note": null,
  "pinned": true
}
```

--------------------------------

### GET /api/user_info

Source: https://github.com/simple-login/app/blob/master/docs/api.md

Retrieves the current user's information, including name and premium status, using the provided API Key.

```APIDOC
## GET /api/user_info

### Description
Retrieves the current user's profile information, such as name and premium status. This endpoint can also be used to validate the provided API Key.

### Method
GET

### Endpoint
/api/user_info

### Parameters
#### Headers
- **Authentication** (string) - Required - The API Key obtained after login.

### Response
#### Success Response (200)
- **name** (string) - User's name.
- **is_premium** (boolean) - Indicates if the user has a premium subscription.
- **email** (string) - User's email address.
- **in_trial** (boolean) - Indicates if the user is currently in a trial period.
- **trial_end_timestamp** (integer | null) - Unix timestamp for the end of the trial, or null if not in trial.
- **profile_picture_url** (string) - URL of the user's profile picture.
- **max_alias_free_plan** (integer) - Maximum number of aliases allowed on the free plan.

#### Example Response
```json
{
  "name": "John Wick",
  "is_premium": false,
  "email": "john@wick.com",
  "in_trial": true,
  "trial_end_timestamp": 1234567890,
  "profile_picture_url": "https://profile.png",
  "max_alias_free_plan": 5
}
```

#### Error Response (401)
Returned if the provided API Key is incorrect or invalid.
```

--------------------------------

### Configure Postfix for SSL/TLS

Source: https://github.com/simple-login/app/blob/master/docs/ssl.md

Update Postfix's main configuration file to use the newly obtained Let's Encrypt SSL certificate. Ensure you replace 'app.mydomain.com' with your actual domain.

```text
smtpd_tls_cert_file=/etc/letsencrypt/live/app.mydomain.com/fullchain.pem
smtpd_tls_key_file=/etc/letsencrypt/live/app.mydomain.com/privkey.pem
```

--------------------------------

### Get Alias Activity Log

Source: https://context7.com/simple-login/app/llms.txt

Retrieves a paginated log of email activities (forwarded, replied, blocked, bounced) for a specific alias.

```APIDOC
## GET /api/aliases/:alias_id/activities — Get alias email activity log

### Description
Returns a paginated log of forwarded, replied, blocked, and bounced emails for an alias.

### Method
GET

### Endpoint
/api/aliases/{alias_id}/activities

#### Path Parameters
- **alias_id** (integer) - Required - The ID of the alias to get activities for.

#### Query Parameters
- **page_id** (integer) - Required - The ID of the page to retrieve.

### Request Example
```bash
curl -s "https://app.simplelogin.io/api/aliases/99/activities?page_id=0" \
  -H "Authentication: SL-abc123xyz"
```

### Response
#### Success Response (200)
- **activities** (array) - A list of activity objects.
  - **from** (string) - Sender's email address.
  - **to** (string) - Recipient's alias email address.
  - **timestamp** (integer) - Unix timestamp of the activity.
  - **action** (string) - Type of action (e.g., 'forward', 'block').
  - **reverse_alias** (string) - The reverse alias address for replying.
  - **reverse_alias_address** (string) - The reverse alias email address.

#### Response Example
```json
{
  "activities": [
    {
      "from": "noreply@github.com",
      "to": "github-notifications.abc@simplelogin.co",
      "timestamp": 1718000000,
      "action": "forward",
      "reverse_alias": "\"GitHub\" <reply+abc@simplelogin.co>",
      "reverse_alias_address": "reply+abc@simplelogin.co"
    }
  ]
}
```
```

--------------------------------

### Get User Info with Access Token

Source: https://github.com/simple-login/app/blob/master/docs/oauth.md

After obtaining an access token, use this command to retrieve user information. The `Authorization` header must include the obtained `access token` in the Bearer format. `httpie` is used here.

```bash
http http://localhost:7777/oauth/user_info 'Authorization:Bearer {token}'
```

--------------------------------

### Get usage statistics

Source: https://context7.com/simple-login/app/llms.txt

Retrieves usage statistics for the current user, including counts of aliases, forwarded emails, replies, and blocks.

```APIDOC
## GET /api/stats — Get usage statistics

### Description
Returns counts of aliases, forwarded, blocked, and replied-to emails for the current user.

### Method
GET

### Endpoint
https://app.simplelogin.io/api/stats

### Response
#### Success Response (200)
- **nb_alias** (integer) - Number of aliases.
- **nb_forward** (integer) - Number of forwarded emails.
- **nb_reply** (integer) - Number of replied-to emails.
- **nb_block** (integer) - Number of blocked emails.
```