# Email API keys

> Give an app its own key to send, read, or read and change the mail of one mailbox, without anyone's password.

Source: https://veldhost.eu/docs/email-api-keys

Last verified: 2026-11-16

An Email API key lets an app (a website, a shop, a booking system, a script) use one mailbox: send mail as it, read its mail, or read and change it. The app signs in with the mailbox address and the key instead of a person's password.

A key belongs to the account, not to the person who made it. It keeps working when that person leaves the team or resets their sign-in, and the account's security-key rule does not apply to it, because nobody signs in with it by hand.

## Before you start

- You are the account's **Owner**, an **Administrator** or a **Developer**, or you manage email on the site the mailbox belongs to.
- The mailbox exists. A dedicated one, such as `noreply@example.com` or `orders@example.com`, keeps the app's mail apart from people's and makes the sending limits easy to reason about ([Create a mailbox](https://veldhost.eu/docs/create-a-mailbox)).

## Create a key

1. Open [Email](https://manage.veldhost.eu/portal/mail), find the mailbox, open its row menu and choose **Email API keys…**.
2. Under **Create a key**, give it a **Name** after the app that will use it, for example "Shop order emails".
3. Choose what **The app may** do:
   - **Send mail** as the mailbox (and its aliases).
   - **Read mail**: list, search and download messages. It changes nothing, not even "read" marks.
   - **Change mail**: mark as read, flag, move, delete and save drafts. It includes reading.
4. Optional: in **Allowed from**, list your app's server addresses or ranges, one per line (for example `203.0.113.7` or `2001:db8::/48`). Leave it empty to allow any address. Up to 20 entries. If your server has both IPv4 and IPv6, list both.
5. Choose when it **Expires**: 30 days, 90 days and 1 year, or **Never**. A key that never expires must have **Allowed from** set.
6. Click **Create key** and confirm your password.

The key is shown once, with the connection settings and, for a key that sends, a ready-made `.env` snippet. Copy it into your app straight away: nobody can show it to you again, not even us. If you lose it, rotate or revoke it and make a new one.

## Connect your app

| Setting | Value |
|---|---|
| Username | the mailbox address |
| Password | the Email API key |
| Sending (SMTP) | smtp.veldhost.eu, port 2525, STARTTLS |
| Reading (IMAP) | imap.veldhost.eu, port 993, SSL/TLS |

Email API keys send on port 2525 only. People's passwords and app passwords keep using the usual ports, and do not work on 2525. Step-by-step examples: [Send email from your app](https://veldhost.eu/docs/send-email-from-your-app) and [Read email from your app](https://veldhost.eu/docs/read-email-from-your-app).

## Rotate, revoke and expiry

- **Rotate…** in a key's row menu makes a new key with the same access, allowed addresses and expiry. The old key keeps working for 24 hours, so you can update the app without downtime, and then stops.
- **Revoke** stops a key at once.
- The account's Owner and Administrators get an email 14 days before a key expires. An expired key stops working; rotate it before then to keep the app running.
- A mailbox holds up to 25 keys.

The list shows when each key was **Last used**, who made it, and a **Sending paused** badge while the account's monthly spend cap stops sending ([Email API pricing](https://veldhost.eu/docs/email-api-pricing)).

## From the API or an AI assistant

With an [API token](https://veldhost.eu/docs/api-authentication) or a connected AI assistant you can list a mailbox's keys and revoke one, for example when a key has leaked:

- `GET /mail/mailboxes/MAILBOX/api-keys` lists the keys (read scope): what each may do, its allowed addresses, expiry and last use. The key itself is never shown.
- `DELETE /mail/mailboxes/MAILBOX/api-keys/KEY_ID` revokes one at once (manage scope).

Creating a key stays in the portal, because its secret is shown once, to you, and never to an assistant. An assistant gives you the link to the right page instead.

> **Note:** A key is tied to the mailbox address. If you remove the mailbox, its keys stop. If the mailbox is renamed to another address, its keys stop too, and the Email API keys page says which ones: make new keys for the new address and update the app.

## Related

- [Send email from your app](https://veldhost.eu/docs/send-email-from-your-app)
- [Read email from your app](https://veldhost.eu/docs/read-email-from-your-app)
- [Email API pricing](https://veldhost.eu/docs/email-api-pricing)
- [Mailbox passwords, mail apps and Veldmail](https://veldhost.eu/docs/mailbox-passwords-and-devices)