# Email

Source: https://frameleaf.app/docs/admin/email/

Email keeps the people on your server in the loop. Frameleaf can send email when:

- you create an account for someone (a welcome email), or email them a link to choose their own password
- someone is added to a shared album, or photos are shared with them
- new photos or videos are added to a shared album
- someone signs in to an account from a device or network the server doesn't recognise
- you remind someone to link their Frameleaf account
- a restore drill of your backup has run (a monthly report to administrators)
- a client is invited to a gallery, or sends an enquiry through a Clients website
- you send or schedule an [email campaign](https://frameleaf.app/docs/using/clients-campaigns/) for your studio contacts
- you send a [contract](https://frameleaf.app/docs/using/clients-contracts/) to sign, and when it's signed
- you send an [invoice](https://frameleaf.app/docs/using/clients-invoices/), and its payment reminders

Your server sends through a connected Gmail or Microsoft account, or a mail server you choose. Email stays off until you set up delivery. Only an administrator can change these settings.

## Set up email delivery

Open **Settings**, then **Notifications**, then **Email delivery** on your local server. Under **Which email should Frameleaf send from?**, choose **Gmail**, **Microsoft**, **iCloud Mail**, **Yahoo Mail** or **Other**.

Gmail and Microsoft support OAuth sign-in: you approve sending on the provider's own page, without entering a mail password in Frameleaf. iCloud Mail, Yahoo Mail and **Other** use SMTP. Gmail also has an app-password option.

:::note[Cloud account required for email sign-in]
Before signing in with Google or Microsoft, [link your server to a Frameleaf account](https://frameleaf.app/docs/cloud/account/#link-a-server). A free account is enough. If the page shows **Link this server**, complete that step first, then return to **Email delivery**.

Frameleaf Cloud provides the public callback address and brokers OAuth sign-in and token renewal. Your server needs internet access to reach it and the email provider. You do not need to expose your local server publicly for this sign-in flow.
:::

## Gmail

OAuth sign-in requires your server to be linked to a free Frameleaf account. The app-password alternative below works without a Cloud link.

### Sign in with Google

1. In **Email delivery**, choose **Gmail**, then **Sign in with Google**. If Gmail is already set up with an app password, choose **Sign in with Google instead**.
2. On the Google page that opens, choose the Gmail or Google Workspace account to send from and allow Frameleaf to send email. If you leave sending permission unchecked, setup cannot finish.
3. Return to **Email delivery**. The page detects the completed sign-in and shows the connected address under **Signed in as**. Connecting the account saves the delivery method and turns on email sending immediately.
4. Under **Check it works**, select **Send a test email**. It goes to your own Frameleaf account's email address; check your inbox and junk folder.

There is no SMTP host, port or password to enter. Your local server sends directly through the Gmail API.

### Use an app password instead

This SMTP option does not need a Frameleaf Cloud account link.

1. Create a [Google app password](https://support.google.com/accounts/answer/185833). Google requires 2-Step Verification, and some accounts cannot create app passwords.
2. Choose **Gmail** in **Email delivery**, then **Use an app password instead** if the sign-in option is shown.
3. Enter your full **Email address** and save your changes. Under **SMTP password**, choose **Replace credential** and enter the app password.
4. Turn on **Send email from this server** and save again. **Send a test email** stays unavailable until the settings are saved, then select it.

The Gmail preset uses `smtp.gmail.com`, port `465`, with **Encrypt from the start** on. Leave **Send even if the security certificate can't be checked** off. Use an app password, not your normal Google password.

## Microsoft 365 and Outlook

OAuth sign-in requires your server to be linked to a free Frameleaf account.

1. In **Email delivery**, choose **Microsoft**, then **Sign in with Microsoft**.
2. On the Microsoft page that opens, choose your Outlook.com, Hotmail or Microsoft 365 account and approve the requested permissions. If your organisation requires administrator approval, ask your Microsoft 365 administrator to approve access.
3. Return to **Email delivery** and wait for **Signed in as** to show the connected address. Connecting saves the delivery method and turns on email sending immediately.
4. Select **Send a test email** under **Check it works**, then check your Frameleaf account's inbox and junk folder.

Your local server sends directly through Microsoft Graph. There is no SMTP host, port or password to enter, and you do not need to enable password-based SMTP for this method. Frameleaf's Microsoft option uses sign-in only.

## How connected accounts work

- The permission lets Frameleaf send email and identify the connected account; it does not grant access to read your mail.
- Your server stores the refresh token encrypted with its own secret file and keeps access tokens in memory. Your mail password is not stored. Frameleaf Cloud brokers token exchange and renewal; email messages go directly from your server to the provider.
- The sender address is the connected account's address. Under **Advanced**, you can change **Sender name** and **Send replies to**. A different sender address left over from an SMTP setup does not override the connected account.
- Signing in saves the connection immediately. Other edits, such as the sender name or reply-to address, still need to be saved through the settings draft.

### Sign in again or disconnect

If the provider withdraws access, **Email delivery** shows **Sign in again**, and administrators receive an in-app notice. Sign in again there to resume delivery. Invitations and album updates remain available in the app while email is stopped; do not assume missed emails were delivered.

If sign-in expires or is cancelled, start again. If Frameleaf Cloud cannot be reached, check the server's internet connection and choose **Try again**. A provider is offered only when the Cloud broker has it enabled.

Choose **Disconnect…** beside the connected address to remove the account from this server. Disconnecting turns email sending off until you set it up again. If Frameleaf cannot revoke access at the provider, follow the page's app-permissions link to remove it there too. Microsoft requires this separate removal. Disconnecting Google can also require another Frameleaf server using the same Google account to sign in again.

If your settings are managed by a [config file](https://frameleaf.app/docs/admin/config-file/), the delivery controls are read-only. Follow that configuration workflow instead of these web setup steps.

## iCloud Mail and Yahoo Mail

Both use SMTP with an app password made on the provider's site. The page links to the provider's instructions.

| Tile | Covers | Mail server the preset fills in |
| --- | --- | --- |
| **iCloud Mail** | icloud.com, me.com and mac.com | `smtp.mail.me.com`, port `587` |
| **Yahoo Mail** | yahoo.com and ymail.com | `smtp.mail.yahoo.com`, port `465`, **Encrypt from the start** on |

Enter your full **Email address**, save, replace the **SMTP password** credential with the app password, then turn on **Send email from this server**, save, and select **Send a test email**.

## Other mail servers (SMTP)

Choose **Other** to enter your own server details. Save first, then test:

1. Fill in the settings below and save your changes.
2. Under **SMTP password**, choose **Replace credential** and enter the password, if your mail server needs one.
3. Turn on **Send email from this server** and save.
4. Under **Check it works**, select **Send a test email**. The test uses what is saved, so the button stays unavailable while the mail server, account, port or encryption settings have unsaved changes.

| Setting | What it does |
| --- | --- |
| **Mail server** | Your provider's sending server, for example `smtp.example.com` |
| **Mail account name** | Usually your full email address |
| **SMTP password** | Choose **Replace credential** to enter it. Stored write-only; shows **Stored** or **Not set** |
| **Sender address** | An address this account is allowed to send from |
| **Encrypt from the start** | Usually on for port 465 and off for port 587 |
| **Port** (under **Advanced**) | Your provider's SMTP port; presets fill this in |
| **Send even if the security certificate can't be checked** (under **Advanced**) | Leave off for normal use |
| **Sender name** (under **Advanced**) | The name beside the sender address |
| **Send replies to** (under **Advanced**) | Where replies go; leave empty to use the sender address |

:::note[Changing mail server]
Saving a different host or account name clears the stored SMTP password, so it is never sent to the wrong server. Turn sending off, save the new server, replace the credential, then turn sending on again.
:::

## Links in emails

Emails link back to your server, to the album or to the sign-in page for a new account, using your **Public server URL**. If you haven't set one, a linked server uses the HTTPS address Frameleaf Cloud published for it.

The Public server URL is set in two places, and both change the same setting (`server.externalDomain`):

- **Settings**, then **Server & updates**, then **Server name & welcome**, under **Finding this server**. This works on every server, with or without Frameleaf Cloud.
- **Settings**, then **Frameleaf Cloud**, then **Remote access**, while **Let people reach this server away from home** is on. Choose **Your Frameleaf address** or **Your own domain** under **The address in links you share**, or type an address under **Use your own domain**, then **Another address**.

Without either address, emails are sent without links and ask the recipient to open Frameleaf on your server instead. A `{baseUrl}` tag in a custom template is left empty too, so links built from it won't work.

## Email templates

To change the wording of the emails, open **Settings**, then **Notifications**, then **Email delivery**, and under **The emails themselves** choose **Change the wording of emails**. Write in plain words, use **Insert** to add details that are filled in for each email, and preview each email with sample names. An empty email uses the default wording. The tags below are what the config file uses.

| Template | Tags you can use |
| --- | --- |
| **Welcome email** | `{username}`, `{password}`, `{displayName}`, `{baseUrl}` |
| **Album invitation email** | `{senderName}`, `{recipientName}`, `{albumId}`, `{albumName}`, `{baseUrl}` |
| **Album update email** | `{recipientName}`, `{albumId}`, `{albumName}`, `{baseUrl}` |

Below the emails are two more settings:

- **First line of an invitation**: the greeting at the top of an album invitation email. *[Person's name]* becomes the recipient's name. Leave it empty for the standard greeting.
- **Show the Frameleaf name and logo**: the header at the top of every email this server sends.

## What people can turn off

Each person chooses which emails they get in their own **Settings**, then **Notifications**, then **Emails you receive**:

- **Send me emails**: all email notifications on or off
- **When someone shares with you**: albums and photos shared with them
- **Album updates**: when a shared album has new photos or videos
- **Sign-ins from unfamiliar devices or networks**: when someone signs in to their library from a device or network this server doesn't recognise

See [Notifications](https://frameleaf.app/docs/using/notifications/) for how this looks to them.

## Welcome emails

When you [add a person](https://frameleaf.app/docs/admin/users/#add-a-person) with a temporary password, turn on **Email them their sign-in details**. The option only appears once email delivery is set up.
