# Outgoing Email (SMTP)

> The mail server API Maker sends through. The root user sets up the server of the installation for sign-in codes, account notes, certificate alerts and its reports, and decides which admins may send through it. An admin sends the mails of its account through the root user's server, or through a server of its own. Test any server in one click.

Source: https://docs.apimaker.dev/v4/docs/features/outgoing-email.html

Outgoing Email is the mail server API Maker sends through. It has its own page, for the root user and for every admin.

> **In short**
>
> - The root user sets up the server of the installation. Sign-in codes, account notes, certificate alerts and the reports of the root user go out through it.
> - The root user decides which admins may send through its server : every admin, the admins it chooses, or nobody.
> - An admin sends the mails of its account through the server of the root user, or through a server of its own.
> - **Send a test mail** tries any server, saved or not, and shows what the server said.
> - Passwords never go back to a browser. The server of an admin is sealed on the server and never goes into git or an export.

| | |
|---|---|
| Where | The root user : `Settings → Outgoing Email (SMTP)`, or the tile on its dashboard. An admin : `Dashboard → Operations → Outgoing Email (SMTP)`. |
| Who | The root user and admins. A developer's mails go through the server its admin chose. |
| Default | Every admin may send through the server of the root user, until the root user says otherwise. |
| Password | Encrypted on the server. It is never sent back to a browser. |

## Which mail goes through which server

| Mail | Server |
|---|---|
| Sign-in codes by email, and notes about an account (recovery codes, a new authenticator app) | The server of the root user, always. A person can always sign in, whatever an admin did to its own server. |
| Alerts about the certificates of the [built-in web server](https://docs.apimaker.dev/v4/docs/features/built-in-web-server.html) | The server of the root user. |
| The reports of [Health Check AI Reporting](https://docs.apimaker.dev/v4/docs/features/ai-reporting.html) of the root user | The server of the root user. |
| The reports of an admin, and **Send again** of a run | The server the admin chose : the root user's, when the root user lets it, or its own. |

## Set up the server of the root user

1. Open `Settings → Outgoing Email (SMTP)`.
2. Write the **Host** of your mail server, and choose its **Security**. The port follows.
3. Write the **Username** and the **Password**, if your server asks for a sign-in.
4. Write the address the mails come **From**, and a name.
5. Press **Save**.
6. Press **Send a test mail**.

| Setting | What it does |
|---|---|
| Send mail through this server | Off : no mail goes out. Sign-in codes by email need it. |
| Host | The name of the server, like `smtp.example.com`. |
| Security | **STARTTLS** (port 587) is the usual one. **TLS / SSL** (port 465) is secured from the first byte. **None** (port 25) is only for a relay you trust, on your own network. |
| Port | Follows the security you choose. A port you write yourself stays. |
| Certificate | Checked : the certificate of the server must be signed by a public authority. Turn the check off only for your own relay with a self-signed certificate. |
| Username | Empty for a relay which takes mail without a sign-in. |
| Password | Kept once saved. **Change** writes a new one. **Change** with an empty field removes it. |
| From | The address the mails come from, and the name people see. |
| Wait at most | How long each step of a mail may take before the server is given up : 5 to 120 seconds. |

### The usual mail services

| Service | Host | Security | Sign-in |
|---|---|---|---|
| Gmail, Google Workspace | `smtp.gmail.com` | STARTTLS, 587 | The address, and an app password (turn on 2-Step Verification first). |
| Microsoft 365, Outlook | `smtp.office365.com` | STARTTLS, 587 | The address and its password. SMTP sign-in must be allowed for the mailbox. |
| Amazon SES | `email-smtp.<region>.amazonaws.com` | STARTTLS, 587 | The SMTP credentials of SES, not your AWS keys. |
| SendGrid | `smtp.sendgrid.net` | STARTTLS, 587 | The username `apikey`, and an API key as the password. |
| Mailgun | `smtp.mailgun.org` | STARTTLS, 587 | The SMTP credentials of your domain. |

> **Tip : Port 25 is often closed**
>
> Many cloud providers block port 25 going out. Use 587 or 465 when a test says the server can not be reached.

## Let admins use the server of the root user

Under **Admins**, choose who may send through your server :

- **Every admin** : the default. Admins have nothing to set up.
- **Chosen admins** : only the admins you pick.
- **Nobody** : admins send through their own server.

The table under it shows what each admin sends through now : your server, its own server, or nothing.

The root user's server always sends the sign-in codes, whatever you choose here.

## An admin : choose the server

An admin chooses where the mails of its account go out :

- **The server of the root user** : nothing to set up. The page shows the address the mails come from. It can be chosen when the root user lets the admin use it.
- **My own mail server** : write it on the same page, then press **Save**. Saving it also chooses it.

An admin never sees the server of the root user, its username or its password : only the address the mails come from. **Remove** forgets the own server of the admin and its password.

## Send a test mail

Write an address, then press **Send a test mail**.

- A form with changes is tested as it is written, saved or not. Nothing is kept.
- Otherwise, the test goes through the server in use. The page keeps its result : `Last test 5 min ago : delivered to …`.
- When the server says no, **What the server said** shows the whole dialogue, with the password hidden. An admin who tests the server of the root user gets the result only.

The test mail says which server sent it, and which mails now go through it.

## When a mail can not go out

Nothing stops. A report still runs and is kept in its History, and the run says why its mail did not go :

| The run says | What to do |
|---|---|
| No mail server is set up yet | The root user sets up its server. |
| The root user does not let you send through its mail server | Set up your own server, or ask the root user. |
| The root user has no mail server yet | Set up your own server, or ask the root user. |
| Your mail server is not set up | Finish your own server : its host and the address the mails come from. |

What a server says most often :

| The server says | Why |
|---|---|
| `does not advertise STARTTLS` | The port is not a STARTTLS port. Choose **TLS / SSL** for 465, or **None** for a relay. |
| `SMTP server replied 535` | The username or the password is wrong. Gmail and Outlook need an app password. |
| `Unable to reach host:port` | The port is closed on the way, or the host is wrong. |
| `invalid peer certificate` | The certificate is not signed by a public authority. Turn the check off only for your own relay. |

## Where it is kept

| What | Where |
|---|---|
| The server of the root user | The settings of the root user (`am_root_user_settings`), its password encrypted with `passDBEncryptDecrypt`. |
| The servers of admins, and who may use the server of the root user | `am_mail_servers` of the main database. Each document is sealed whole with AES-256-GCM. Only its owner and its date are in the clear. |

The servers of admins are never part of a commit or a pull of [git](https://docs.apimaker.dev/v4/docs/Git/git.html), nor of an export of the settings.

## The API of the page

The page calls `POST /api/sites/mail/:apiPath/<name>`. The root user asks under `root`, an admin under its own path. A developer is refused.

| Name | What it does |
|---|---|
| `settings` | The server, and who may use it (the root user) or what the admin sends through (an admin). |
| `update-server` | Saves the server : `{ server, password?, clearPassword?, useIt? }`. |
| `remove-server` | An admin forgets its own server. |
| `update-sharing` | The root user : `{ sharing: { mode: 'ALL' \| 'CHOSEN' \| 'NONE', admins: [ids] } }`. |
| `update-choice` | An admin : `{ useRoot: true \| false }`. |
| `test-server` | A test mail : `{ to, server?, password? }`. Without `server`, through the server in use. |

## Related

- [Health Check AI Reporting](https://docs.apimaker.dev/v4/docs/features/ai-reporting.html) : reports by mail, written by AI.
- [Security features](https://docs.apimaker.dev/v4/docs/features/security-features.html) : two-step sign-in with codes by email.
- [AI Integration](https://docs.apimaker.dev/v4/docs/features/ai-integration.html) : the keys of the AI providers, shared the same way.