# Quick start Faivelo gives you professional email on your own domain — `you@yourcompany.com` — in about two minutes. Here's the whole journey, from creating an account to reading your first message. ## What you'll need - A domain you own (like `yourcompany.com`) - Access to that domain's DNS settings — or, even better, an API key from your registrar so Faivelo can configure DNS for you ## 1. Create your account Sign up at [faivelo.com/register](https://faivelo.com/register){rel=""nofollow""} with your email address and a password (minimum 8 characters). You're taken straight into a guided setup that walks you through three steps: connect your domain, verify your DNS, and create your first mailbox. You can leave at any point with **Set up later** — when you come back, you resume exactly where you left off. ## 2. Connect your domain Enter the domain you want to use for email. Faivelo looks up your domain's nameservers and detects who manages your DNS — Cloudflare, GoDaddy, Namecheap, Route 53, Hostinger, and others are recognized automatically. - **Provider detected?** You can paste an API key and Faivelo adds every DNS record for you. See [Automatic DNS setup](https://faivelo.com/docs/domains/automatic-dns-setup). - **Not detected, or no API key?** No problem — the next step shows you exactly which records to add by hand. Click **Add domain**. Faivelo provisions your domain on the mail server and generates your DNS records and signing keys in a few seconds. ## 3. Verify your DNS You'll see a list of DNS records (MX, SPF, DKIM, DMARC, and a few more) with a live status for each. If records were pushed automatically, verification usually completes within a couple of minutes. If you're adding them manually, click any name or value to copy it, then paste it into your DNS provider's dashboard — see [Manual DNS records](https://faivelo.com/docs/domains/manual-dns-records) for a walkthrough. Faivelo re-checks your records automatically every few seconds while you're on this page, so there's no need to refresh. There's also a **Check now** button if you're impatient. ::docs-aside{title="Propagation takes time" type="note"} DNS changes usually appear within a few minutes, but can occasionally take up to 48 hours. You can safely close the page and come back later. :: ## 4. Create your first mailbox Once your domain is verified, pick your email address — for example `you@yourcompany.com`. Set a password, or leave the field blank and Faivelo generates a secure one for you. ::docs-aside{title="Save your password" type="caution"} Your mailbox password is shown exactly once, on the confirmation screen — along with your username and the IMAP/SMTP server details for connecting mail apps. Copy it somewhere safe. If you lose it, you can reset it later from the mailbox settings. :: ## 5. Open your inbox That's it — your address is live and can send and receive email right away. Open [faivelo.com/mail](https://faivelo.com/mail){rel=""nofollow""} and sign in with your new mailbox credentials to start using webmail, or use the IMAP/SMTP details from the confirmation screen in Apple Mail, Outlook, Thunderbird, or your phone. ## Next steps - [Add another domain](https://faivelo.com/docs/domains/adding-a-domain) - [Create more mailboxes](https://faivelo.com/docs/mailboxes/creating-mailboxes) - [Troubleshoot DNS verification](https://faivelo.com/docs/domains/troubleshooting) # Set up from the terminal If you live in a terminal, you can set up email on your domain without touching the dashboard: ```bash npx faivelo init yourcompany.com ``` There is nothing to install. The command signs you in, adds the domain, gets the DNS records in place (automatically where your DNS host allows it), waits until they are live, and creates your first mailbox — then hands you the credentials once. ## What it does, step by step 1. **Sign in.** A pairing code appears in the terminal and your browser opens `faivelo.com/cli/authorize`. Sign in or create a free account, check the code matches, click **Approve**. The terminal notices on its own. Working over SSH? Add `--no-open` and open the printed link from any browser; the code is the same. 2. **Checks the domain.** Nameservers, who hosts the DNS, whether the domain already receives mail somewhere (it tells you before anything changes), and whether the domain is registered at all. 3. **Adds the domain** to your account and generates the records. 4. **Gets the records in**, choosing the easiest path your host supports: - **Connect in your browser** — Cloudflare, Vercel, Netlify, DigitalOcean, WordPress.com, Google Cloud DNS: one consent screen, no keys. - **Approve at your host** — hosts that support Domain Connect add the records for you. - **Paste an API key** — GoDaddy, Namecheap, Route 53, Hostinger, Porkbun, name.com, Gandi, IONOS and more. The terminal tells you exactly where the key page is and what format it expects. - **By hand** — full, copy-ready values shaped for your host's form (Squarespace, Shopify and Bluehost quirks included), while the terminal keeps checking every 10 seconds. 5. **Waits for DNS.** Live progress like `4/9 required records found`. Stop anytime with Ctrl+C; `npx faivelo status yourcompany.com` picks up where you left off. 6. **Creates your first mailbox** and prints the password, IMAP and SMTP settings once. Inside a project folder it offers to write `SMTP_*` and `IMAP_*` into `.env` (and warns if `.env` isn't gitignored). ## Commands | Command | What it does | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `npx faivelo init [domain]` | The full setup above. Safe to re-run: it resumes wherever the domain is. | | `npx faivelo status [domain]` | All your domains, or one domain's DNS checked live. | | `npx faivelo dns ` | The records to add, with full values. `--table` for a compact view, `--zone` for a BIND zone file you can import. | | `npx faivelo login` / `logout` / `whoami` | Manage the sign-in saved on this computer. | ## Options - `--no-open` — never launch a browser, only print links (SSH sessions, containers, CI). - `FAIVELO_TOKEN` — skip the browser sign-in entirely by supplying a session token (scripts and CI). ## Where things are stored The sign-in is saved to `~/.config/faivelo/credentials.json` (`%APPDATA%\faivelo` on Windows), readable only by your user. `npx faivelo logout` removes it. Mailbox passwords are never stored by the CLI — they are shown once, and optionally written to your project's `.env` when you say yes. # Adding a domain Every mailbox in Faivelo lives on a domain you own. Adding a domain takes under a minute; getting mail flowing then just needs a few DNS records — which Faivelo can often add for you automatically. ## Before you start You need a registered domain (like `yourcompany.com`) and access to wherever its DNS is managed — your registrar's dashboard, or an API key from it. Each domain can only be connected to one Faivelo account. ## Add the domain 1. Go to [faivelo.com/domains](https://faivelo.com/domains){rel=""nofollow""} in your dashboard. 2. Click **Add Domain**. A two-step dialog opens. 3. **Step 1 — Domain:** enter your domain name (e.g. `yourcompany.com`) and continue. 4. **Step 2 — DNS Setup:**Faivelo looks up your domain's nameservers and tells you which provider it detected — along with the nameservers it saw, so you can double-check. - If a supported provider is detected (Cloudflare, GoDaddy, Namecheap, Route 53, or Hostinger), you can paste an API key and Faivelo will configure your DNS automatically. See [Automatic DNS setup](https://faivelo.com/docs/domains/automatic-dns-setup) for where to get the key for each provider. - If you'd rather not share a key — or your provider isn't detected — just leave the field blank. You'll add the records manually; it only takes a minute. 5. Click **Add Domain**. ::docs-aside{title="Your API key is checked first" type="tip"} If you provide an API key, Faivelo tests it against your DNS zone *before* doing anything else. A wrong key or an inaccessible zone fails immediately with a clear message, so you can fix it and retry — nothing is left half-configured. :: ## What happens next When you add a domain, Faivelo: 1. **Provisions it on the mail server**, ready to host mailboxes. 2. **Registers it with the sending relay** so outbound mail is signed (DKIM) and delivered from your domain, not a third party's. 3. **Generates your full DNS record set** — MX, SPF, DKIM, DMARC, plus records for secure transport and mail-client auto-configuration. See [Manual DNS records](https://faivelo.com/docs/domains/manual-dns-records) for the complete list. 4. **Pushes the records to your registrar automatically**, if you provided an API key. 5. **Starts checking your DNS** in the background — first after about 30 seconds, then again over the next few minutes, and every few minutes after that until everything verifies. You land on the domain's page, where each DNS record shows a live status: **Verified**, **Pending**, or **Mismatch**. In the domain list, the domain shows a **Pending DNS** badge until every record checks out, then flips to **Verified**. You can create mailboxes right away, but mail won't reliably arrive or deliver until the domain's DNS is verified — treat verification as the finish line before you start using addresses in the wild. ## Next steps - [Set up DNS automatically](https://faivelo.com/docs/domains/automatic-dns-setup) with a registrar API key - [Add the records manually](https://faivelo.com/docs/domains/manual-dns-records) at any DNS provider - [How verification works](https://faivelo.com/docs/domains/verification) # Automatic DNS setup Setting up email means adding a dozen or so DNS records. If your domain's DNS is managed by a supported provider, you can skip the copy-paste entirely: give Faivelo an API key when you [add your domain](https://faivelo.com/docs/domains/adding-a-domain), and every record is created for you in seconds. Faivelo detects your provider automatically from your domain's nameservers, so the right instructions appear during setup. Supported providers: **Cloudflare, GoDaddy, Namecheap, Route 53 (AWS), and Hostinger**. ## What Faivelo injects The complete record set your domain needs: the MX record that routes incoming mail, SPF, DKIM, and DMARC records that authenticate your outbound mail, plus records for secure transport (MTA-STS, TLS reporting) and mail-client auto-configuration. The full list, with values, is in [Manual DNS records](https://faivelo.com/docs/domains/manual-dns-records). If a conflicting record already exists (say, an old MX record from a previous email provider), Faivelo replaces it so your new setup works immediately. ::docs-aside{title="Your key is stored encrypted" type="note"} Registrar API keys are encrypted at rest. Faivelo uses the key only to manage DNS records for the domains you connect. You can also re-push records later with the **Re-apply DNS records** button on your domain's DNS page. :: ## Cloudflare 1. Go to [Cloudflare API tokens](https://dash.cloudflare.com/profile/api-tokens){rel=""nofollow""} and click **Create Token**. 2. Use the **Edit zone DNS** template and give it access to your domain's zone. 3. Copy the token and paste it into Faivelo. Faivelo also disables Cloudflare **Email Routing** on the zone if it's active, since it injects its own MX records that would conflict with yours. ::docs-aside{type="caution"} Cloudflare's orange-cloud proxy must stay **off** for mail records. Faivelo creates them DNS-only, but if you edit them later, keep the proxy disabled — see [Troubleshooting DNS](https://faivelo.com/docs/domains/troubleshooting). :: ## GoDaddy 1. Go to [GoDaddy Developer Keys](https://developer.godaddy.com/keys){rel=""nofollow""} and create a **production** API key. 2. Copy both the **Key** and the **Secret**. 3. Paste them into Faivelo as one value in the format `key:secret`. ## Namecheap 1. Go to [Namecheap API access](https://ap.www.namecheap.com/settings/tools/apiaccess){rel=""nofollow""} and enable API access on your account. 2. Copy your **API Key**. 3. Paste it into Faivelo as `apiKey:username`, where `username` is your Namecheap account username. ## Route 53 (AWS) 1. In the [AWS IAM console](https://console.aws.amazon.com/iam/home#/users){rel=""nofollow""}, create an IAM user with **Route 53** permissions (it needs to list hosted zones and change record sets). 2. Create an access key for that user. 3. Paste it into Faivelo as `accessKeyId:secretAccessKey`. Your domain must have a hosted zone in the same AWS account the key belongs to. ## Hostinger 1. Go to the [Hostinger API page](https://hpanel.hostinger.com/api){rel=""nofollow""} in hPanel and generate an API token. 2. Copy the token and paste it into Faivelo. Hostinger domains are detected whether they use Hostinger's standard nameservers (`dns-parking.com`) or premium DNS. ## DreamHost 1. Open the [API page](https://panel.dreamhost.com/?tree=home.api){rel=""nofollow""} in your DreamHost panel. 2. In the list of functions, tick `dns-list_records`, `dns-add_record` and `dns-remove_record`, then click **Generate a new API Key now!** 3. Copy the key and paste it into Faivelo. DreamHost's API can add every record type except MX. After auto-setup, Faivelo shows you the one MX record to add yourself: in the panel, open **Manage Websites**, click the three dots beside your domain, choose **DNS Settings**, and add it exactly as shown. Faivelo keeps checking and verifies it automatically. The domain must be in your DreamHost panel (hosted, or DNS Only) and use DreamHost's nameservers (`ns1`, `ns2` and `ns3.dreamhost.com`). ## Prefer not to share a key? That's fine — leave the field blank and add the records yourself. Faivelo shows you exactly what to create, with one-click copy for every value. See [Manual DNS records](https://faivelo.com/docs/domains/manual-dns-records). ## Next steps Once the records are pushed, verification usually completes within a couple of minutes — see [Domain verification](https://faivelo.com/docs/domains/verification). # Manual DNS records If your DNS provider isn't supported for [automatic setup](https://faivelo.com/docs/domains/automatic-dns-setup) — or you'd rather not share an API key — you can add Faivelo's records by hand at any provider. It takes about a minute. ## Where your records live After you [add a domain](https://faivelo.com/docs/domains/adding-a-domain), open it under [faivelo.com/domains](https://faivelo.com/domains){rel=""nofollow""} and go to its **DNS Records** page. Every record is listed there with its exact **Type**, **Name**, and **Value** — click any of them to copy. Always copy from your dashboard rather than from this page: some values (like DKIM keys and verification tokens) are unique to your domain. In your DNS provider's dashboard, find the DNS management screen (often called "DNS", "DNS Records", "Advanced DNS", or "Zone Editor") and create one record per row. ## The records, explained Here's what Faivelo asks you to add and why. `yourdomain.com` stands in for your domain; unique values are shown as placeholders. | Type | Name | Value (example) | What it does | | -------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | MX | `@` | `mx.faivelo.com` (priority `10`) | Routes incoming mail to Faivelo | | TXT | `@` | `v=spf1 mx include:amazonses.com -all` | SPF — authorizes Faivelo to send for you | | TXT | `_dmarc` | `v=DMARC1; p=quarantine; sp=quarantine; adkim=r; aspf=r; pct=100; fo=1; rua=mailto:admin@faivelo.com` | DMARC — sends spoofed mail to spam | | CNAME | `._domainkey` (×3) | `.dkim.amazonses.com` | DKIM — cryptographically signs your outbound mail | | TXT | `_amazonses` | `` | Verifies your domain with the sending relay | | MX + TXT | `bounce` | relay bounce host / `v=spf1 include:amazonses.com ~all` | Handles bounces from your own domain | | CNAME | `mta-sts`, `autodiscover`, `autoconfig` | `mx.faivelo.com` | Enforces TLS and lets mail apps auto-configure | | TXT | `_mta-sts`, `_smtp._tls` | `v=STSv1; ...` / `v=TLSRPTv1; ...` | Secure-transport policy and TLS failure reports | A few provider quirks to watch for: - **Name field:** most providers want the *relative* name — `@` for the domain itself, `_dmarc` rather than `_dmarc.yourdomain.com`. Faivelo's dashboard shows names in this relative form. If your provider expects the full name, append your domain. - **MX priority:** enter `10`. Some providers have a separate priority field; others want it at the start of the value (`10 mx.faivelo.com`). - **DKIM CNAMEs:** there are three, each with a different token. Add all three exactly as shown. ::docs-aside{title="Only one SPF record" type="caution"} A domain may have only **one** SPF TXT record. If you already have one (from Google Workspace, a newsletter tool, etc.), don't add a second — merge the `include:` parts into a single record. See [Troubleshooting DNS](https://faivelo.com/docs/domains/troubleshooting). :: ::docs-aside{title="Cloudflare users" type="tip"} Set every mail-related record to **DNS only** (grey cloud). Proxied (orange cloud) records break mail delivery and verification. :: ## After you've added them Head back to your domain's DNS page in Faivelo. Records typically verify within a few minutes; Faivelo also re-checks automatically in the background, and you can click **Re-check All** at any time. Propagation occasionally takes longer — up to 48 hours in rare cases. ## Next steps - [How verification works](https://faivelo.com/docs/domains/verification) - [Troubleshooting DNS](https://faivelo.com/docs/domains/troubleshooting) if a record stays Pending or shows Mismatch # Domain verification Before you can create mailboxes on a domain, Faivelo confirms that every required DNS record is actually live on the public internet. This page explains how that check works and how long it typically takes. ## How checking works For each record on your domain's DNS page, Faivelo queries public DNS resolvers (Cloudflare's `1.1.1.1` and Google's `8.8.8.8`) and compares what the world sees with what's expected. Using public resolvers means the check reflects what real mail servers will see — not a cached or internal view. Each record gets one of three statuses: | Status | Meaning | | ------------ | ---------------------------------------------------------------- | | **Verified** | The record exists and its value matches | | **Pending** | No record found yet — it hasn't been added, or hasn't propagated | | **Mismatch** | A record exists at that name, but its value is wrong | Your domain is marked **Verified** once every record passes. Until then it shows a **Pending DNS** badge in your domain list. ## When checks run You don't have to sit and refresh — verification runs on its own: - **Right after you add a domain**, Faivelo checks in the background at roughly 30 seconds, 2 minutes, and 5 minutes. If you used [automatic DNS setup](https://faivelo.com/docs/domains/automatic-dns-setup), your domain often verifies on the very first pass. - **Continuously after that**, every unverified domain is re-checked automatically every few minutes until it passes. You can add your records, walk away, and come back to a verified domain. - **During onboarding**, the DNS step polls live every few seconds and moves you forward the moment everything verifies. ## Checking manually On your domain's DNS page there's a **Re-check All** button (labelled **Check now** during onboarding) that runs a fresh verification immediately and updates each record's status and last-checked time. Use it right after saving records at your provider. If your registrar is connected with an API key, you'll also see **Re-apply DNS records**, which pushes the full record set to your registrar again — handy if a record was deleted or edited by mistake. ## How long does propagation take? DNS changes don't appear everywhere instantly. Realistic expectations: - **Automatic setup:** usually verified within a couple of minutes. - **Manual setup at most providers:** a few minutes to an hour. - **Worst case:** up to 48 hours, typically when a record with a long TTL (time-to-live) was recently changed, or when a registrar's own systems are slow to publish. ::docs-aside{type="tip"} If a record still shows **Pending** after an hour, double-check it was actually *saved* at your provider — the most common cause is a record sitting unsaved in an edit form. If it shows **Mismatch**, Faivelo displays the value it currently sees so you can spot the difference. :: ## Does verification ever un-stick a working domain? Verification is about getting your domain live. Once verified, your domain stays usable; Faivelo focuses its recurring checks on domains that haven't passed yet. ## Next steps - Something stuck? See [Troubleshooting DNS](https://faivelo.com/docs/domains/troubleshooting). - Verified? [Create a mailbox](https://faivelo.com/docs/mailboxes/creating-mailboxes). # Troubleshooting DNS Most domains verify within minutes. When one doesn't, it's almost always one of the issues below. Work through them in order — and remember your domain's DNS page shows a live status per record, including the value Faivelo currently sees when there's a **Mismatch**. ## A record is stuck on "Pending" **Pending** means Faivelo can't see the record on public DNS at all yet. 1. **Confirm it's saved.** The single most common cause: the record is sitting in an edit form at your provider and was never saved. Go back and check it appears in the provider's record list. 2. **Check the name.** Most providers want the relative name (`@`, `_dmarc`, `bounce`) — if you pasted the full name and your provider appended your domain again, you end up with `_dmarc.yourdomain.com.yourdomain.com`, which Faivelo will never find. 3. **Wait for propagation.** New records usually appear within a few minutes, but can take up to 48 hours in rare cases — especially if you recently switched nameservers. Faivelo re-checks automatically every few minutes, so you don't need to babysit it; hit **Re-check All** whenever you want a fresh look. ## A record shows "Mismatch" A record exists at the right name, but its value is wrong. Faivelo shows you the value it found — compare it character-by-character with the expected one. - **Typos and stray characters:** extra quotes, a trailing period pasted into a TXT value, or a truncated DKIM token. - **Leftovers from an old provider:** an old MX or SPF record from your previous email host answering instead of the new one. Delete the old record — don't just add a new one beside it. ## Two SPF records This one matters most, because it silently breaks deliverability even after verification. ::docs-aside{title="A domain may have only ONE SPF record" type="danger"} SPF is the TXT record on your root domain starting with `v=spf1`. If two exist, receiving servers treat SPF as *invalid* — worse than having none. Never add a second one. :: If you already send mail through another service (Google Workspace, Mailchimp, etc.), **merge** the `include:` mechanisms into a single record. For example, Faivelo's record plus Google Workspace becomes: ```text v=spf1 mx include:amazonses.com include:_spf.google.com -all ``` Keep exactly one `v=spf1 ...` TXT record on `@`, listing every service that sends for you, ending with a single `-all` (or `~all`). ## Cloudflare: orange cloud breaks mail Cloudflare can proxy records through its network (the orange cloud icon). That's great for websites and fatal for mail: a proxied record no longer points at the real mail server, so delivery and verification fail. Set every record Faivelo asks for to **DNS only** (grey cloud) — especially the MX target and the `mta-sts`, `autodiscover`, and `autoconfig` CNAMEs. Also make sure Cloudflare **Email Routing** is off; it injects its own MX records that conflict with Faivelo's. (When you connect Cloudflare with an API key, Faivelo handles both of these for you.) ## Registrar quirks - **TTL:** leave it at the default (or set 1 hour / 3600). A very long TTL means any mistake takes that long to correct once cached. - **Namecheap** saves the whole record set at once — if you edit in two browser tabs, the second save can wipe the first. Edit in one place. - **GoDaddy and Hostinger** sometimes take several minutes to publish saved records to their public nameservers. Saved-but-Pending for 10–15 minutes is normal. - **Recently transferred domains:** confirm the nameservers actually point at the provider whose dashboard you're editing. Records added at the wrong provider never appear. ## Still stuck? Re-run the flow from the start: check each record on the [DNS page](https://faivelo.com/domains){rel=""nofollow""} against your provider, then **Re-check All**. If your registrar is connected with an API key, **Re-apply DNS records** rewrites the full set in one click. And see [Domain verification](https://faivelo.com/docs/domains/verification) for how the checks and timing work. # Creating mailboxes Once your domain is verified, you can create mailboxes — real email accounts with their own inbox, login, and storage. ## Create a mailbox 1. Go to [your dashboard](https://faivelo.com/dashboard){rel=""nofollow""} and open your domain. 2. Click **Mailboxes**, then **Add Mailbox**. 3. Enter the part of the address before the `@` — for example, `jane` to create `jane@yourdomain.com`. 4. Click create. A secure password is generated automatically and shown to you. After creation, Faivelo offers to email the login credentials to the person who'll use the mailbox, along with a link to sign in at webmail. ::docs-aside{title="Quick Create" type="tip"} Need the usual business addresses fast? Use **Quick Create** on the Mailboxes page to set up common addresses like `info@`, `support@`, `hello@`, `sales@`, and `billing@` in one go. :: ## Display name The display name is what recipients see next to the email address (for example, "Jane Smith" instead of just `jane@yourdomain.com`). The mailbox user can set it themselves in webmail under **Settings → Display Name**. ## Your password is shown once ::docs-aside{title="Save the password when you see it" type="caution"} The mailbox password is displayed **only once**, right after the mailbox is created. Faivelo stores it encrypted and never shows it again in the dashboard. :: If a password is lost, you don't need to delete the mailbox. On the Mailboxes page, open the menu next to the mailbox and choose **Send Credentials**. This resets the password and emails the new credentials to an address you choose, with instructions to sign in and change it. ## Limits You can create as many mailboxes as you like — plans are priced by **storage, not by the number of addresses**. A few safety limits apply: | Limit | Value | | -------------------------------- | ----- | | Mailbox creations per day | 50 | | Mailboxes in your first 24 hours | 25 | These limits protect deliverability for everyone on the platform. If you hit the new-account cap, the remaining wait time is shown at the top of the Mailboxes page. ## Managing mailboxes From the Mailboxes page you can also: - **View Setup** — see the mail server settings for connecting an email app. - **Signature Info** — manage signature details for the mailbox. - **Deactivate / Activate** — temporarily disable a mailbox without deleting it. - **Delete** — permanently remove the mailbox and its mail. The table shows each mailbox's storage use, message count, and last login, so you can spot unused addresses at a glance. ## Next steps Sign in to [webmail](https://faivelo.com/docs/mail/webmail), or connect a desktop or mobile app using the [IMAP & SMTP settings](https://faivelo.com/docs/mail/imap-smtp-settings). If you just need an extra address that routes into an existing inbox, create an [alias](https://faivelo.com/docs/mailboxes/aliases) instead. # Aliases An alias is an email address that forwards everything it receives to one or more existing addresses. It has no inbox, no password, and no storage of its own — it's simply a door that routes mail somewhere else. For example, you can create `info@yourdomain.com` as an alias that delivers to `jane@yourdomain.com`. Jane reads and replies from her own mailbox; nothing new to log in to. ## Create an alias 1. Go to [your dashboard](https://faivelo.com/dashboard){rel=""nofollow""} and open your domain. 2. Click **Aliases**, then **Add Alias**. 3. Enter the part of the address before the `@` — for example, `info` to create `info@yourdomain.com`. 4. Add one or more **destination** addresses that should receive the mail. 5. Save. The alias starts working right away. ## Destinations Each alias can deliver to up to **20 destination addresses**. Every destination receives its own copy of each incoming message, which makes aliases handy for shared addresses: - `support@yourdomain.com` → the whole support team - `billing@yourdomain.com` → you and your bookkeeper You can edit an alias's destinations at any time from the Aliases page. ## Managing aliases From the Aliases page you can: - **Edit** — change the destination addresses. - **Deactivate / Activate** — pause forwarding without deleting the alias. Mail sent to a deactivated alias is not delivered. - **Delete** — remove the alias permanently. The address stops accepting mail. ## Alias or new mailbox? | Use an alias when... | Create a mailbox when... | | -------------------------------------------------------------- | ------------------------------------------------------ | | You want an extra address for an existing person | Someone needs their own inbox and login | | A role address (info@, sales@) should reach one or more people | You want separate storage and mail history | | You don't want another password to manage | The person needs to sign in to webmail or an email app | ::docs-aside{type="tip"} A common setup: one real mailbox per person, plus aliases for every role address. `hello@`, `info@`, and `contact@` can all be aliases pointing at the same mailbox — you manage one inbox and one password. :: ::docs-aside{type="note"} Aliases only receive and forward mail. To send email *from* an address, it needs to be a real mailbox. :: ## Next steps If a destination person doesn't have a mailbox yet, see [Creating mailboxes](https://faivelo.com/docs/mailboxes/creating-mailboxes). Then read the forwarded mail in [webmail](https://faivelo.com/docs/mail/webmail) or any email app via [IMAP & SMTP](https://faivelo.com/docs/mail/imap-smtp-settings). # Webmail Webmail is the fastest way to use your Faivelo mailbox — nothing to install, works on any device with a browser. ## Signing in 1. Go to **[mail.faivelo.com](https://mail.faivelo.com){rel=""nofollow""}**. 2. Enter your full email address (for example, `jane@yourdomain.com`). 3. Enter your mailbox password — the one shown when the mailbox was created, or the one emailed to you by your administrator. ::docs-aside{type="note"} Webmail login uses your **mailbox** credentials, not your Faivelo account. If you manage domains in the dashboard, that's a separate login. :: If you've forgotten your password, ask whoever manages your domain to use **Send Credentials** on the mailbox — you'll receive a fresh password by email. ## Your inbox ### Folders The sidebar shows your standard folders — Inbox, Sent, Drafts, and so on. You can also create your own **custom folders** to organize mail your way, and rename or delete them later. Move messages between folders to keep things tidy. ### Compose Click **Compose** to write a new message. Unfinished messages are saved as drafts so you can pick up where you left off. You can also reply to and forward messages from the reading view. ### Search Use the search bar at the top to find messages. Results replace the current folder view; clear the search to get back to your inbox. ### Calendar invites When someone sends you a calendar invitation (an ICS attachment), webmail shows it as an event card right inside the message, so you can see the details at a glance. Webmail also includes a **Calendar** where your events live — and you can sync it with Apple Calendar, Thunderbird, or any CalDAV app from the calendar's sync settings. ## Settings Open **Settings** in webmail to personalize your account: - **Display name** — the name recipients see next to your address. - **Profile picture** — shown on your account in webmail. - **Email signature** — added to messages you send. If your domain administrator has set a company-wide signature, you'll see it marked as managed; you can still personalize details like your title and phone number. ## Prefer an email app? Webmail and email apps show the same mail — your messages live on the server, so anything you read, send, or file in one place shows up everywhere. ## Next steps To use your mailbox in Apple Mail, Outlook, Thunderbird, or your phone's mail app, see [IMAP & SMTP settings](https://faivelo.com/docs/mail/imap-smtp-settings) — or the dedicated [iPhone & iPad setup](https://faivelo.com/docs/mail/ios-profile) guide. # IMAP & SMTP settings Your Faivelo mailbox works with any standard email app. Use these settings whenever an app asks for server details. ## The settings | Setting | Incoming mail (IMAP) | Outgoing mail (SMTP) | | -------- | ----------------------- | ----------------------- | | Server | `mx.faivelo.com` | `mx.faivelo.com` | | Port | 993 | 587 | | Security | SSL/TLS | STARTTLS | | Username | Your full email address | Your full email address | | Password | Your mailbox password | Your mailbox password | ::docs-aside{type="note"} The username is always your **complete** email address (for example, `jane@yourdomain.com`), not just the part before the `@`. The password is your mailbox password — the one shown when the mailbox was created or emailed to you afterwards. :: ::docs-aside{type="tip"} You can view these settings anytime in the dashboard: open your domain, go to **Mailboxes**, and choose **View Setup** on a mailbox. :: ## Apple Mail (macOS) 1. Open **Mail**, then go to **Mail → Add Account...** 2. Select **Other Mail Account...** and click **Continue**. 3. Enter your name, email address, and mailbox password, then click **Sign In**. 4. If prompted, choose **IMAP**. 5. Enter `mx.faivelo.com` for both the incoming and outgoing mail server. 6. Click **Sign In** to finish. ## Outlook 1. Open **Outlook** and go to **File → Add Account**. 2. Enter your email address and click **Connect**. 3. Choose **IMAP**. 4. Incoming server: `mx.faivelo.com`, port **993**. Outgoing server: `mx.faivelo.com`, port **587**. 5. Enter your mailbox password and click **Connect**. ## Thunderbird 1. Open **Thunderbird** and go to **Account Settings → Account Actions → Add Mail Account**. 2. Enter your name, email address, and password. 3. Click **Configure manually**. 4. Incoming: IMAP, `mx.faivelo.com`, port **993**. Outgoing: SMTP, `mx.faivelo.com`, port **587**. 5. Click **Done**. ## Android (Gmail app) 1. Open the **Gmail** app and go to **Settings → Add account**. 2. Choose **Other** (or **IMAP**). 3. Enter your full email address and password. Choose **Manual setup** if prompted, then **IMAP**. 4. Incoming server: `mx.faivelo.com`, port **993**. Outgoing server: `mx.faivelo.com`, port **587**. 5. Tap **Next** to finish. ## Troubleshooting - **Login rejected?** Double-check that the username is the full address and that the password is the mailbox password, not your Faivelo account password. - **Can receive but not send?** Make sure the outgoing (SMTP) server also uses your full address and password for authentication, on port 587. - **Mailbox deactivated?** A deactivated mailbox can't sign in — check its status on the Mailboxes page in your dashboard. ## Next steps Setting up an iPhone or iPad? See the [iPhone & iPad setup](https://faivelo.com/docs/mail/ios-profile) guide — or skip apps entirely and use [webmail](https://faivelo.com/docs/mail/webmail). # iPhone setup Getting your Faivelo mailbox onto your iPhone takes two short steps: add the mail account, and (optionally) install the Faivelo configuration profile so your calendar syncs with Apple Calendar. ::docs-aside{title="Android" type="note"} A Faivelo Android app is coming soon. In the meantime, Android phones work great with any IMAP mail app — see [IMAP & SMTP settings](https://faivelo.com/docs/mail/imap-smtp-settings). :: ## Step 1: Add your mail account 1. Open **Settings** on your iPhone. 2. Tap **Mail → Accounts → Add Account**. 3. Tap **Other → Add Mail Account**. 4. Enter your name, full email address (for example, `jane@yourdomain.com`), and your mailbox password, then tap **Next**. 5. Select **IMAP**. 6. For both the incoming and outgoing mail server, enter `mx.faivelo.com`. 7. Tap **Save**. Your inbox will appear in the Mail app within a few moments. ::docs-aside{type="note"} If iOS asks for ports or security settings, use the values from the [IMAP & SMTP settings](https://faivelo.com/docs/mail/imap-smtp-settings) page: IMAP on port 993 (SSL/TLS) and SMTP on port 587 (STARTTLS), with your full email address as the username. :: ## Step 2: Install the calendar profile (optional) Faivelo can generate an Apple **configuration profile** (a `.mobileconfig` file) that adds your Faivelo calendar to your device as a native calendar account. Once installed, events sync both ways with Apple Calendar — invitations you accept in webmail show up on your phone, and events you create on your phone appear in webmail. 1. On your iPhone, open **Safari** and sign in to webmail at [mail.faivelo.com](https://mail.faivelo.com){rel=""nofollow""}. 2. Download the Faivelo calendar profile from webmail. Safari will confirm: tap **Allow**, and you'll see "Profile Downloaded". 3. Open **Settings**. Tap **Profile Downloaded** near the top (or go to **General → VPN & Device Management**). 4. Tap **Install**, enter your device passcode if asked, and confirm. That's it — your Faivelo calendar now appears in the Apple Calendar app. ::docs-aside{title="Use Safari" type="caution"} The profile download only works in **Safari**. Other browsers on iOS can't hand configuration profiles to Settings. :: ::docs-aside{type="tip"} Don't want to use a profile? You can add the calendar manually instead: go to **Settings → Calendar → Accounts → Add Account → Other → Add CalDAV Account**, and use server `mx.faivelo.com` with your email address and mailbox password. The same steps are shown in webmail under the calendar's sync settings. :: ## Removing the profile If you no longer want calendar sync on a device, go to **Settings → General → VPN & Device Management**, select the Faivelo profile, and tap **Remove Profile**. Your mail account is separate and won't be affected. ## Next steps Setting up a Mac, Windows PC, or Android phone too? All the server details and walkthroughs are in [IMAP & SMTP settings](https://faivelo.com/docs/mail/imap-smtp-settings). # Drive overview Faivelo Drive is cloud file storage built into your account. Upload documents, spreadsheets, images and more, organise them into folders, and share them with teammates or the outside world — all from the same account that runs your mail. ## Where to find it Open **Drive** from the sidebar in your dashboard, or go straight to [faivelo.com/drive](https://faivelo.com/drive){rel=""nofollow""}. Everyone on the account can reach Drive; each person only ever sees files they own or that were shared with them. ## Storage Drive and mail share a single storage pool. The size of that pool depends on your plan, and your dashboard shows how much of it you've used (mail + Drive combined). If you're running low, clear out large files or old mail, or upgrade your plan for more room. Individual files can be up to **5 GB** each. ## What's next - [Uploading & organising files](https://faivelo.com/docs/drive/files-and-folders) — folders, moving, renaming, trash. - [Sharing files](https://faivelo.com/docs/drive/sharing) — share links and inviting people. - [Connect Drive to other apps](https://faivelo.com/docs/drive/connect-apps) — let external tools read your files. # Uploading & organising files ## Uploading In [Drive](https://faivelo.com/drive){rel=""nofollow""}, use **Upload** to add files from your computer, or drag and drop them straight onto the file list. Files can be up to 5 GB each and count against your account's shared storage pool. ## Folders Create folders to keep things organised, and open a folder to work inside it. The path along the top (the breadcrumb) shows where you are — click any step to jump back up. Folders always sort ahead of files, and everything is listed alphabetically by name. ## Renaming and moving Any file or folder you own can be renamed, and you can move items between folders to reorganise as your Drive grows. ## Trash Deleting a file or folder moves it to the **Trash** rather than removing it immediately. Items in the Trash can be restored, and are automatically purged for good after **30 days**. Emptying the Trash yourself frees the storage right away. ## Searching Use search to find a file by name across your whole Drive without clicking through folders — handy once you've stored a lot. # Sharing files Faivelo Drive offers two ways to share, and you can use either on any file or folder you own. ## Share links A share link lets anyone with the URL open the item — no Faivelo account needed. When you create one you can add safeguards: - **Password** — the recipient must enter it before they can view or download. - **Expiry** — the link stops working after a date you choose. - **Download limit** — cap how many times the item can be downloaded. Revoke a share link at any time and the URL stops working immediately. ## Sharing with people You can also share directly with specific people by email address, the way you would in Google Drive. Each person gets a role: - **Viewer** — can open and download the item. - **Editor** — can also upload, rename and organise inside a shared folder. Sharing a folder shares everything inside it: the people you invite gain access to the folder's current and future contents, and they see it starting from the folder you shared (anything above it stays hidden). Change someone's role or remove their access whenever you need to. ## Which should I use? - Reach for a **share link** for one-off, external, or public sharing — sending a file to a client, for example. - Use **sharing with people** for ongoing collaboration with named teammates who should keep access over time. # Connect Drive to other apps Other applications can read files from your Faivelo Drive on your behalf — for example, an applicant-tracking system that imports a spreadsheet of candidates you keep in Drive. Access is granted through Faivelo's OAuth connection flow, so you stay in control and can revoke it at any time. ## How it works When you connect an app to Faivelo, it sends you to a Faivelo consent screen listing exactly what it wants to do. If the app asks for Drive access, you'll see: > **Read files from your Faivelo Drive** Approve the connection and the app can list your Drive files and download them; it **cannot** upload, change, or delete anything — Drive access is read-only. It also can't touch your mail, aliases, or account settings unless you granted those separately. ## Example: importing into Kabuna [Kabuna](https://kabuna.io){rel=""nofollow""} (an applicant-tracking system) can import candidates directly from a spreadsheet in your Drive: 1. In Kabuna, start a candidate import and choose **Faivelo Drive** as the source. 2. Connect (or reconnect) your Faivelo account and approve Drive access on the consent screen. 3. Pick the spreadsheet, map its columns, and Kabuna imports the rows as candidates. ## Managing and revoking access Connected apps appear under **Settings → Developers** in your dashboard as OAuth connections. Revoke any connection there and its access — including to your Drive — stops immediately. ::docs-aside{title="Connected before Drive access existed?" type="note"} An app you connected earlier won't have Drive permission. Disconnect and reconnect it (and approve Drive access) to grant it. :: ## For developers Drive is part of the Faivelo developer API and MCP server via the `drive:read` scope. See [AI agents & API keys](https://faivelo.com/docs/developers/ai-agents) and the [REST API reference](https://faivelo.com/docs/api){rel=""nofollow""}. # Sending limits Faivelo's sending limits are simple: your plan sets **monthly quotas**, and those quotas are available in full from day one — there is no hidden daily allowance to earn and no warm-up on paid plans. Instead, Faivelo watches the outcome of what you send. If bounces or spam reports climb, sending pauses automatically until the cause is fixed. The full rules live in the [Sending Policy](https://faivelo.com/sending-policy){rel=""nofollow""}; this page explains how they work day to day. ## Monthly quotas by plan Transactional (API) mail and campaigns have **separate budgets** — a newsletter can never eat into your app's password resets. Everyday mail from webmail or your own mail app is never metered. | Plan | Transactional / month | Campaigns / month | API rate | | ---------- | --------------------: | ----------------: | -------: | | Free trial | 100 | 100 | 10/min | | Starter | 3,000 | — | 10/min | | Growth | 20,000 | 3,000 | 60/min | | Pro | 50,000 | 25,000 | 120/min | | Business | 100,000 | 100,000 | 240/min | Every paid plan sends to anyone. Transactional mail also has a **daily cap of a tenth of your monthly allowance** (Starter 300, Growth 2,000, Pro 5,000, Business 10,000 a day), so normal bursts fit and a brand-new account cannot empty a month in one afternoon. Quotas reset on the **1st of each calendar month**. Unused sends don't roll over. Campaigns also have per-campaign size caps (Growth 3,000 · Pro 15,000 · Business 25,000 recipients). (The Free plan is forwarding-only and doesn't include sending.) ## Sending domains Receiving is unlimited everywhere, but **sending** happens from domains you designate (Starter/Growth 1, Pro 3, Business 10 — the domain page has the switch; your first verified domain is designated automatically). Paid plans send at their plan's full pace from the first day. Only **free trials** warm up: a trial's sending domain starts at 200 recipients a day and doubles every three clean days, and a trial account as a whole starts at 50 emails a day (25 an hour) and grows with clean history. That is plenty to try the product properly while a brand-new, unpaid account builds a reputation; upgrading lifts all of it at once. On **Pro and Business**, each sending domain carries its own reputation with our mail provider, so a bad list on one domain never pauses another. A **dedicated IP** is available as a $30 a month add-on on those plans from the billing page; it is worth it above roughly 50,000 emails a month, and below that a dedicated IP cannot stay warm and hurts placement, so the billing page says so before you turn it on. ## Everyday mail Mail sent **from your mailboxes** — webmail, Apple Mail or Outlook, or a mailbox API key — carries **no daily or hourly cap** on paid plans. Send what your business sends. The one exception is a catastrophe stop of 2,000 messages an hour per mailbox login, sized so no person or business gets near it; it exists to bound a runaway script or a compromised password in the seconds before the protections below react. ## No cold outreach Every campaign recipient must have opted in to hear from you: subscribers, customers, sign-ups. Purchased, rented or scraped lists are not allowed, on any plan. Campaigns to people who did not ask to hear from you are stopped and may lead to account suspension. The [Sending Policy](https://faivelo.com/sending-policy){rel=""nofollow""} has the full rules. ## Automatic protections Faivelo acts **after the fact**, on outcomes, the way the best transactional providers do. Every lane is covered the same way — campaigns, the transactional API, mailbox API keys, webmail and mail apps, and AI agents: - **Suppression list.** Addresses that hard-bounced or complained are dropped from every future send automatically — they never count against you again, and they never bounce against your reputation twice. - **First-batch check on campaigns.** The first 200 recipients of a campaign go out, then it holds briefly while delivery feedback arrives. If that batch bounces badly (3% or more), the campaign pauses itself and tells you why. A clean batch releases the rest at your plan's full pace. - **Automatic slow-down.** If hard bounces reach 4% of what a paid account sent over the last two days (or a handful, for very small senders), outgoing mail is slowed to a reduced number per hour until the two-day rate is back under 2%. You are judged on that two-day rate, never on a single hour, so a newsletter whose bounces all land in the same hour is not a problem. Mailboxes, logins and incoming mail carry on as normal. You're warned by email at half the line, and told by email when it happens — with your numbers, what to fix, and what happens next. - **Automatic pause.** Spam reports reaching 0.05%, or bounces on a free trial, pause outgoing mail across the whole account: all mailboxes, campaigns and API keys. You keep your logins, inbox and dashboard; incoming mail keeps arriving and nothing is lost. - **Resuming.** The **first** automatic pause on an account lifts itself after 24 hours, so a one-off bad list costs a day, not a support ticket. A second within 90 days lifts after 72 hours. A third stays until our team has reviewed it with you — reply to the email or write to . Pauses older than 90 days are forgotten. - **List-quality gate.** If more than 5% of a campaign list is undeliverable, the campaign is refused outright — that failure rate is the signature of a purchased or scraped list. An honest sender with the occasional bad address never gets near any of this; a purchased list trips it in the first minute. ## What counts as a send **One recipient = one send.** A campaign delivered to 500 addresses uses 500 sends, regardless of how many campaigns you split them across. The same is true for `cc` and `bcc` on API sends. Things that do *not* count against your quota: - Suppressed addresses that Faivelo skips automatically (they're never sent) - Regular day-to-day mail you send from your mailbox through an email app or webmail ## Separate pools Marketing sends and [transactional API sends](https://faivelo.com/docs/transactional/send-api) each draw from their own monthly quota; mailbox API keys, MCP and AI agents send as everyday mail. The automatic protections above judge the account as a whole, whichever lane a bounce came from. ## What happens when you hit a limit - **Starting a new campaign** is blocked with a clear error telling you how many sends you have left and which limit you hit. - **A campaign already in progress** is paused automatically. Nothing is lost — the remaining recipients stay queued, and it resumes when the limit resets or your plan changes. - **API sends** are rejected with the same limit information — monthly and daily limits are named separately, so your code can tell "wait until tomorrow" from "upgrade or wait for the 1st". Faivelo checks quotas continuously during a campaign, not just at the start, so you'll never accidentally overshoot. ## Where to see your usage Open the [Metrics page](https://faivelo.com/metrics){rel=""nofollow""} in your dashboard. It shows how many sends you've used this month, your plan's limit, and what's remaining. ## Need more sends? Upgrade at any time from the [Billing page](https://faivelo.com/billing){rel=""nofollow""} — the higher monthly quota applies immediately, and upgrades are prorated. See [Billing & plans](https://faivelo.com/docs/billing/plans) for a full comparison. ## Next steps - [Send your first campaign](https://faivelo.com/docs/sending/campaigns) - [Keep your mail out of spam](https://faivelo.com/docs/sending/deliverability) - [Read the Sending Policy](https://faivelo.com/sending-policy){rel=""nofollow""} # Campaigns Campaigns let you send the same email — personalized per recipient — to a list of contacts, straight from one of your own mailboxes. Everything lives at [faivelo.com/campaigns](https://faivelo.com/campaigns){rel=""nofollow""}. ## Create a campaign Click **New campaign** and work through the four-step wizard: 1. **Setup** — name the campaign and pick the mailbox it sends from. Replies go straight to that mailbox like normal mail. 2. **Recipients** — choose a saved recipient list or upload contacts. Faivelo can validate addresses before you send, and anything on your suppression list is excluded automatically. 3. **Content** — write your email or start from a saved template. Insert personalization variables like `[First Name]` and they're filled in per recipient (in the subject line too). Your mailbox signature is appended automatically if you have one configured. 4. **Review** — check the summary, then send. ::docs-aside{type="tip"} Save emails you reuse as **templates** (the Templates tab on the campaigns page) so the next send takes seconds. :: ## Sending behavior Campaigns send gradually — roughly two emails per second — rather than blasting everything at once. This pacing is deliberate: mailbox providers treat sudden bursts as a spam signal. Faivelo also protects you mid-send: - If mail to a particular recipient domain starts **bouncing or failing repeatedly**, remaining recipients at that domain are skipped and the campaign report tells you why. - If your account's bounce or complaint rate crosses safety thresholds, the campaign is **paused automatically** so your reputation isn't damaged further. - You can pause a running campaign yourself from its detail page at any time. Every recipient counts against your [monthly sending limit](https://faivelo.com/docs/sending/limits). ## Tracking opens and clicks Each campaign email includes an invisible open-tracking pixel, and links are rewritten to pass through Faivelo's click tracker before redirecting to the real destination. The campaign's detail page shows, per recipient, whether the message was sent, opened, clicked, bounced, or unsubscribed — plus overall totals. ::docs-aside{type="note"} Open tracking is an estimate. Some mail apps block remote images or pre-fetch them automatically, so real open rates can be higher or lower than reported. Clicks are more reliable. :: ## Unsubscribes Every campaign email carries standard one-click unsubscribe headers, so Gmail, Outlook, and other providers show their own built-in **Unsubscribe** button. Recipients who use it are marked as unsubscribed on the campaign. This isn't optional — bulk mail without a working unsubscribe gets flagged as spam. ## The suppression list Your suppression list is a per-account "never email again" list, visible under **Suppressed** on the campaigns page. Addresses are added automatically when: - a message **hard-bounces** (the address doesn't exist), or - a recipient **marks your mail as spam** (a complaint). Suppressed addresses are silently skipped in every future campaign, even if they appear in an uploaded list. You can remove an address manually if it was suppressed by mistake — but don't re-add complainers; that's how domains end up blocklisted. ## Next steps - [Understand your sending limits](https://faivelo.com/docs/sending/limits) - [Keep your campaigns out of spam](https://faivelo.com/docs/sending/deliverability) # Deliverability & staying out of spam Deliverability isn't magic — it's a reputation. Gmail, Outlook, and Yahoo score every sending domain on its history: authentication, bounce rates, complaints, and whether people actually read the mail. Faivelo handles the technical half automatically; the other half is how you send. This page covers both. ## The quick checklist 1. **Don't touch the DNS records Faivelo set up** — they're your authentication. 2. **Warm up a new domain** — start with small sends and ramp up over weeks. 3. **Only email people who asked** — never purchased or scraped lists. 4. **Watch your bounce and complaint rates** — under 2% bounces, well under 0.1% complaints. 5. **Write like a human** — real content, a plain-text version, a working unsubscribe. 6. **Earn engagement** — send things people open and reply to. Each point, in detail: ## 1. Authentication is the foundation When you added your domain, Faivelo created DNS records for **SPF**, **DKIM**, and **DMARC**. Together they prove to receiving servers that mail claiming to be from your domain really is — and mail that fails these checks is increasingly rejected outright, not just filtered. You don't need to understand the acronyms. You need to know one thing: **don't delete or edit those records.** If you (or your web developer, or a site migration) change DNS at your registrar, keep Faivelo's records intact. The domain page in your dashboard shows whether every record is still verified — if one goes red, fix it before sending anything. ## 2. Warm up a new domain A domain with no sending history is a stranger. If a stranger suddenly sends 10,000 emails, mailbox providers assume spam. Ramp up gradually instead: - **Week 1:** a few dozen emails a day, ideally to people likely to open and reply. - **Weeks 2–3:** a few hundred per day if bounces stay near zero. - **Week 4 onward:** scale toward your real volume, roughly doubling week over week. There's no exact formula — the principle is *consistent, gradually increasing volume with good engagement*. A month of patience buys you years of inbox placement. ## 3. List hygiene: only mail people who opted in This is the single biggest factor you control. - **Never buy, rent, or scrape lists.** They're full of dead addresses and spam traps, and the recipients didn't ask to hear from you — they will bounce and complain, and your domain pays the price. - **Use opt-in signups**, ideally confirmed (double opt-in), so every address is real and willing. - **Remove people who never engage.** An address that hasn't opened anything in six months is a liability, not an asset. - **Let bounces go.** Faivelo removes hard-bounced addresses for you (see below) — don't re-import them from an old spreadsheet. ## 4. Bounce and complaint rates Faivelo continuously monitors every sending domain and recalculates its 30-day campaign bounce and complaint rates: hard bounces and spam reports on campaign mail, over campaign mail. Soft bounces (a full mailbox, a greylisting retry) never count. Mailbox providers start to care around a **2% bounce rate**, so the first line is a heads-up there, and campaigns pause at the same 4% line the account is judged on: | Signal | Warning | Sending paused | Review | | -------------- | ------: | -------------: | -----: | | Bounce rate | 2% | 4% | 8% | | Complaint rate | 0.05% | 0.1% | 0.3% | - **Warning:** a heads-up email with your numbers; nothing changes yet. - **Paused:** campaigns from the domain stop automatically. Mailboxes, everyday mail and the API are not affected. The pause lifts itself after a week once the rates are back under the line, or sooner after a word with support. - **Review:** the same pause, plus someone on our team looks at the domain with you. Your account is never suspended automatically over a bad list. The table above is per sending domain and applies to campaigns. Account-wide, across every lane including the API, the hard-bounce line is **4% of what the account sent over the last two days** (Resend's published limit). A paid account is judged on that two-day rate, never on a single hour. Two things sit under that number and never move: one account can never produce more than a small share of the platform's daily bounces before it is slowed, and if the platform's own bounce metric climbs, every account is judged on a stricter 1.5% line for 24 hours. Only the signature of a spam script or a stolen password (a burst of bounces that is most of what a mailbox sent) pauses sending immediately regardless of rate. If your rates improve, the warning clears automatically. And note how low the complaint bar is: just **1 spam report per 1,000 emails** is a warning. That's why consent matters so much. Faivelo also handles the cleanup for you: **hard-bounced addresses and anyone who reports your mail as spam are added to your suppression list automatically** and never emailed again. Mid-campaign, if a particular recipient domain starts bouncing, Faivelo stops mailing that domain immediately rather than burning your reputation on it. ### Verify a list before sending For a list you did not collect yourself, or one that has sat for a while, verify it first. Faivelo checks every address against its live mail server and sorts the list into three buckets: | Bucket | Meaning | What happens at send time | | ------------- | -------------------------------------------------- | --------------------------------- | | Deliverable | The mailbox exists | Sends | | Accept-all | The server accepts any address, so nobody can tell | Held back unless you include them | | Undeliverable | The mailbox does not exist | Removed from every send | Verification costs **1 cent per address with a $5 minimum**, charged only when you choose it, from **Campaigns → Verify** or from any recipient list. A campaign that the 200-send check paused offers the same button; after verifying, resuming runs the check again on the cleaned list. Verification never lifts an account pause: it stops the next one. ## 5. Content that doesn't look like spam Filters read your email before humans do: - **Avoid classic spam patterns** — ALL-CAPS subjects, walls of exclamation marks, "FREE!!!", deceptive subject lines, link shorteners, or an email that's one giant image with no text. - **Include a plain-text version.** Faivelo campaigns send both HTML and plain text when you provide it — fill in the text version; HTML-only mail scores worse. - **Keep a working unsubscribe.** Every Faivelo campaign automatically includes one-click unsubscribe headers that Gmail and Outlook surface as a native button. Don't try to work around it — an easy unsubscribe is what *prevents* spam complaints. - **Send from a real mailbox and welcome replies.** A no-reply address that bounces responses is a negative signal. ## 6. Engagement matters Mailbox providers watch what recipients *do*: opens, clicks, replies, moves to the spam folder, moves *out* of the spam folder. High engagement is the strongest positive signal there is. - Send only when you have something worth reading. - A smaller, engaged list beats a huge, cold one — every time. - Ask new subscribers to reply to your first email; replies are gold for reputation. ## What Faivelo does for you So you know where the line is — these parts are handled automatically: - **SPF, DKIM, and DMARC** records generated for every domain, with verification status on your dashboard. - **A custom MAIL FROM domain**, so bounce-handling happens under your own domain instead of a shared one — providers see a consistent, aligned sender. - **Automatic suppression** of hard bounces and complaints, applied to all future campaigns. - **Reputation monitoring** that recalculates your bounce and complaint rates continuously, emails you at the first warning sign, and pauses sending before real damage is done. - **Paced sending and mid-campaign protection**, including skipping recipient domains that start bouncing. ## Next steps - [Send your first campaign](https://faivelo.com/docs/sending/campaigns) - [Check your sending limits](https://faivelo.com/docs/sending/limits) - [See your metrics](https://faivelo.com/metrics){rel=""nofollow""} # Transactional email Transactional email is the mail your **application** sends — receipts, password resets, magic links, shipping updates, alerts. It's one-to-one, triggered by something a user did, and it needs to arrive *now*. Faivelo's transactional email gives you: - **A send API** — `POST /api/v1/emails` sends from any address on one of your verified domains. No mailbox needs to exist for the sender: `receipts@yourdomain.com` works the moment the domain is verified. - **Designed templates** — build the email once in the visual template editor, then trigger it from code with an alias and variables. See [Templates](https://faivelo.com/docs/transactional/templates). - **Delivery tracking** — every send has a status (`sent` → `delivered`, `bounced`, `complained`, or `failed`) you can poll, plus [webhooks](https://faivelo.com/docs/transactional/webhooks) that push those events to your server as they happen. - **Automatic suppression** — addresses that previously hard-bounced or complained are dropped before sending, so a stale address in your database can't damage your domain's reputation. - **Safe retries** — send an `Idempotency-Key` header and a retried request returns the original result instead of emailing your customer twice. ## Who can use it Transactional email is included on **every paid plan**, and every plan sends to anyone: Starter sends 3,000 a month, Growth 20,000, Pro 50,000 and Business 100,000 — at 10/60/120/240 recipients a minute respectively, with a daily cap of a tenth of the month (see [rate limits](https://faivelo.com/docs/developers/ai-agents#rate-limits)). Transactional volume is a **separate budget from campaigns**, so a newsletter can never eat your password resets. Delivery webhooks are included from Pro, where each sending domain also carries its own reputation and a dedicated IP is available as an add-on. Every signed-in account can browse the Templates section and explore the editor. See [Billing & plans](https://faivelo.com/docs/billing/plans). ## Transactional vs. campaigns | | Transactional | [Campaigns](https://faivelo.com/docs/sending/campaigns) | | ------------------ | --------------------------------------------------------------------- | ------------------------------------------------------- | | Triggered by | Your code, one recipient at a time | You, to a whole list | | Examples | Receipts, resets, alerts | Newsletters, announcements, product updates | | Sent via | API (`POST /api/v1/emails`) | Dashboard campaign wizard | | Unsubscribe footer | Not added (it's not marketing) | Added automatically | | Counts against | Your [monthly sending limit](https://faivelo.com/docs/sending/limits) | Your monthly sending limit | Both kinds of sending draw from the same monthly pool and the same account-level [sending limits](https://faivelo.com/docs/sending/limits). ## Getting started 1. [Verify a domain](https://faivelo.com/docs/domains/adding-a-domain) (you've probably done this already). 2. Create an API key with the `mail:send` scope — see [AI agents & API keys](https://faivelo.com/docs/developers/ai-agents). 3. Send your first email — see [Sending via the API](https://faivelo.com/docs/transactional/send-api). 4. Optional: design a [template](https://faivelo.com/docs/transactional/templates) and add a [webhook](https://faivelo.com/docs/transactional/webhooks) for delivery events. # Templates Templates separate **design from triggering**: someone designs the receipt once in the visual editor, and your code sends it with three lines — an alias and the variables that change per email. No HTML in your codebase, and design fixes ship without a deploy. Find the editor in the dashboard under **Transactional → Templates**. Any signed-in account can browse it; creating and sending templates requires a **Pro** or **Business** plan (see [Transactional email](https://faivelo.com/docs/transactional/overview)). ## Aliases Every template has an **alias** — a short handle like `order-confirmation` — which is what your code passes as `templateAlias` on the [send call](https://faivelo.com/docs/transactional/send-api). Aliases are unique per account; if you create a template with a taken alias, Faivelo appends a number (`order-confirmation-2`). A template can be **paused** from the dashboard. Sends that reference a paused template fail with `409` and nothing goes out — useful when a template is mid-edit and must not be triggered. ## Variables Write `{{name}}` anywhere in the subject or body and it becomes a variable your code fills at send time: ```json { "templateAlias": "order-confirmation", "variables": { "name": "Robin", "total": "$42.00" } } ``` Rendering is **strict**: if the template references a variable the send call didn't provide, the call fails with `422` listing what's missing — nothing is sent. A receipt can't go out with a blank total. ## Repeating sections For variable-length content — order line items, a list of alerts — mark a block as a **section**. In the send call, feed it an array of rows, and the block renders once per row: ```json { "variables": { "items": [ { "product": "Notebook", "price": "$12.00" }, { "product": "Pen", "price": "$3.00" } ] } } ``` Inside the section block, `{{product}}` and `{{price}}` refer to the current row's values. ## The API-content slot A template can include an **API-content slot** — a placeholder that your send call fills with its own `html`. The caller's markup renders *inside* the designed template (header, theme, footer intact) instead of replacing it. This is the pattern for emails whose body is generated by your app — a digest, a report — that should still wear your design. If a template has no slot, any `html` on a template send is simply unused. ## Shared theme Your account has a shared **theme** — brand color, fonts, logo — that every template inherits by default. Change the theme once and every inheriting template updates together. A template can also **detach** and carry its own values when one email needs to look different. ## Test sends The editor's **test send** delivers the template to an address you choose through the real production pipeline, with the sample values shown in the preview — a faithful rehearsal, not a simulation. Test sends count against your [monthly sending limit](https://faivelo.com/docs/sending/limits) like any other delivery. ## Next steps - [Send a template from code](https://faivelo.com/docs/transactional/send-api) - [Get delivery events pushed to your server](https://faivelo.com/docs/transactional/webhooks) # Sending via the API One endpoint sends transactional mail: `POST /api/v1/emails`. It needs an API key with the `mail:send` scope (create one in the dashboard — see [AI agents & API keys](https://faivelo.com/docs/developers/ai-agents)) and a [verified domain](https://faivelo.com/docs/domains/verification) to send from. The full request/response reference lives in the [REST API reference](https://faivelo.com/docs/api){rel=""nofollow""} — this page covers how the endpoint behaves. ## A first send ```bash curl https://faivelo.com/api/v1/emails \ -H "Authorization: Bearer $FAIVELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "receipts@yourdomain.com", "to": "customer@example.com", "subject": "Your order is confirmed", "html": "

Thanks for your order!

" }' ``` The `from` address can be **any local part on any of your verified domains** — no mailbox has to exist for it. `to`, `cc`, and `bcc` each accept a single address or an array (up to 50 recipients per call). Provide `html`, `text`, or both. The response includes an `id`. Keep it: it's how you look the send up later. ## Sending a stored template Instead of inline content, pass a [template](https://faivelo.com/docs/transactional/templates) alias and its variables: ```json { "from": "receipts@yourdomain.com", "to": "customer@example.com", "templateAlias": "order-confirmation", "variables": { "name": "Robin", "total": "$42.00" } } ``` The template supplies the subject and body. Rendering is **strict**: if a variable the template references is missing, the call fails with `422` and nothing is sent — you get an error, not a receipt with a blank total. If the template has an **API-content slot**, any `html` you pass renders inside the designed template rather than replacing it. See [Templates](https://faivelo.com/docs/transactional/templates) for how slots and repeating sections work. ## Safe retries with idempotency keys Networks fail mid-request. To retry safely, send any unique string (up to 256 characters) as an `Idempotency-Key` header: ```bash curl https://faivelo.com/api/v1/emails \ -H "Authorization: Bearer $FAIVELO_API_KEY" \ -H "Idempotency-Key: order-8412-confirmation" \ ... ``` Two requests with the same key send **at most one email** — the second request gets the first one's response back. Derive the key from the event that triggered the send (an order id, a reset-token id), not from a timestamp. ## Attachments Attach up to **10 files, 10 MB total**, base64-encoded: ```json { "attachments": [ { "filename": "invoice.pdf", "content": "", "contentType": "application/pdf" } ] } ``` ## Suppression Recipients who previously hard-bounced or marked your mail as spam are on your **suppression list** and are dropped from the recipient set automatically. If *every* recipient is suppressed, the call fails with `422` and nothing is sent. This is protection, not an obstacle: sending to a known-bad address damages your domain's deliverability for everyone you mail afterwards. ## Tracking delivery A send starts with status `sent` (accepted for delivery) and updates as events arrive: | Status | Meaning | | ------------ | ------------------------------------------------------------ | | `sent` | Accepted for delivery; no events yet | | `delivered` | The receiving server accepted it | | `bounced` | The receiving server rejected it (the address is suppressed) | | `complained` | The recipient marked it as spam (the address is suppressed) | | `failed` | The send could not be completed | Poll with `GET /api/v1/emails/{id}`, or — better for anything real-time — register a [webhook](https://faivelo.com/docs/transactional/webhooks) and get pushed `email.delivered`, `email.bounced`, and `email.complained` events as they happen. The dashboard's Transactional section shows the same log with full detail. ## Limits Transactional sends count against your plan's [monthly sending limit](https://faivelo.com/docs/sending/limits) (and, on a free trial, the sending domain's warm-up ramp). There is no daily allowance to earn: paid plans send at their quota from day one, and bounce or spam-report rates are what pause an account. ## Sending from a mailbox instead `POST /api/v1/mailboxes/{address}/send` sends as an **existing mailbox**, authenticated as that mailbox — the same path a mail app uses. It also accepts `templateAlias`. Use `/emails` for application mail from role addresses that don't need a mailbox; use the mailbox send when the mail should come from a real person's account. # Webhooks Webhooks are the push counterpart of polling a send's status: register an HTTPS endpoint and Faivelo POSTs delivery events to it as they happen. Use them to mark a message delivered in your app, alert on bounces, or clean bad addresses out of your database the moment they bounce. Manage webhooks in the dashboard under **Settings → Developers → Webhooks**. They are included on the **Growth**, **Pro** and **Business** plans. This page covers the delivery events for transactional email. Webhooks also cover mailboxes, domains and account health, with retries, a delivery log and secret rotation: see the full [Webhooks guide](https://faivelo.com/docs/developers/webhooks). ## Events | Event | Fires when | | ------------------ | ------------------------------------------------------------------------- | | `email.delivered` | The receiving server accepted the message | | `email.bounced` | The receiving server rejected it (hard bounce; the address is suppressed) | | `email.complained` | The recipient marked it as spam (the address is suppressed) | Each webhook subscribes to the events you choose. ## The payload Every delivery is a JSON `POST`: ```json { "type": "email.bounced", "created_at": "2026-08-19T14:03:22.000Z", "data": { "email_id": "cme1x…", "from": "receipts@yourdomain.com", "to": ["customer@example.com"], "subject": "Your order is confirmed", "template_alias": "order-confirmation", "status": "BOUNCED", "sent_at": "2026-08-19T14:03:20.000Z" } } ``` `data.email_id` is the id the [send call](https://faivelo.com/docs/transactional/send-api) returned. Bounce and complaint events may carry extra detail about the reason. The request also carries an `X-Faivelo-Event` header naming the event type. ## Verifying signatures Anyone who discovers your endpoint URL can POST fake JSON to it — so verify every request. Each webhook has a **signing secret** (shown when you create it), and every delivery is signed with an `X-Faivelo-Signature` header: ```text X-Faivelo-Signature: t=1755612202,v1=5257a869e7… ``` `v1` is `HMAC-SHA256(secret, "{t}.{raw request body}")`. To verify: ```js import { createHmac, timingSafeEqual } from 'node:crypto' function verify(rawBody, header, secret) { const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('='))) // Reject stale timestamps to block replay attacks if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex') return v1.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected)) } ``` Compute the HMAC over the **raw request body**, before any JSON parsing — a re-serialized body won't match. ## Delivery behavior - Your endpoint has **5 seconds** to respond with a 2xx status. Respond first, process after — do your database work asynchronously. - Redirects are **not followed**; point the webhook at its final URL. - The dashboard shows each webhook's last successful delivery and last error, so a misbehaving endpoint is visible at a glance. - Each event is delivered **once** — there is no automatic retry queue. Treat webhooks as the fast path and the [send status API](https://faivelo.com/docs/transactional/send-api#tracking-delivery) as the source of truth you can re-query anytime. ## Testing Every webhook has a **Send test** button in the dashboard. It delivers a real signed `email.delivered` event with `"test": true` in the payload — so you can prove your endpoint and signature verification end-to-end without sending an email. # Migrating your email Switching to Faivelo doesn't mean leaving your email history behind. The migration wizard copies your existing mailbox — every folder — from your old provider into a Faivelo mailbox, while new mail keeps arriving normally. Nothing is deleted at the other end; Faivelo only reads your old account to copy it over. Whether you're moving from Gmail, Microsoft 365, Fastmail, or any other IMAP host, the flow is the same: connect your old account, pick where it should land, and let it copy in the background. ## How the wizard works Migration is a full-screen, step-by-step flow. It walks you through: 1. **Source** — choose where your email lives now (Gmail / Google Workspace, Microsoft 365 / Outlook, Fastmail, or any other IMAP provider). Faivelo fills in the technical server settings for you. 2. **Connect** — sign in to your old account. Most providers use an **app password** (a one-off credential, not your normal login); Microsoft 365 uses a secure sign-in with no password needed. A free connection test then shows you exactly what will move — your folders, message count, size, and a time estimate. 3. **Destination** — pick your Faivelo domain. Faivelo **creates the matching mailbox for you** (or uses an existing one) and confirms it can actually receive mail *before* anything starts, so nothing fails halfway. 4. **Copy** — your mail transfers in the background. Watch the live progress, or close the page and come back later — it keeps going. 5. **Finish** — Faivelo checks that your domain is set up to receive new mail and confirms you're fully migrated. ## Starting a migration - From your **dashboard**, choose **Bring your existing email over**, or - Open a **domain** and click **Import email**. Either way the wizard opens with that domain already selected, so you can go straight to connecting your old account. ::docs-aside{type="note"} Testing the connection (the pre-flight check) is always free. Running the actual migration is included with any paid plan. :: ## What gets copied - All your folders and the messages in them, with folder structure, read/unread state, and dates preserved. - Trash and Spam are skipped by default — they rarely need to come along. - Provider "virtual" folders (like Gmail's **All Mail** and **Starred**) are excluded automatically, so you won't get duplicate copies of every message. ## Your inbox never goes down ::docs-aside{title="No downtime, no gaps" type="tip"} The migration only *reads* from your old account — it never deletes or changes anything there. Your Faivelo mailbox keeps receiving new mail the entire time, so there's no gap in your inbox. You can send and receive normally while old mail copies over in the background. :: ## When you're fully migrated Once the copy finishes, Faivelo checks your domain's **MX records** — the setting that decides where *new* mail is delivered. When they point at Faivelo, you're receiving inbound mail here and you're fully migrated. If they don't yet, the wizard can set them for you (or show you exactly what to add). At that point it's safe to release your old email provider. We recommend keeping it running for about **14 days** as a safety net, just in case — then cancel it. ## Provider guides - [Migrating from Gmail](https://faivelo.com/docs/migrations/from-gmail) — using a Google app password (works for personal Gmail and Google Workspace). - [Migrating from Microsoft 365](https://faivelo.com/docs/migrations/from-microsoft-365) — with secure Microsoft sign-in. Moving from somewhere else? Any provider that supports IMAP works — pick **Other provider** in the wizard and enter your IMAP server details. # Migrating from Gmail Moving from Gmail (or Google Workspace) to Faivelo takes three things: a Google app password, a destination mailbox on your Faivelo domain, and a few minutes to kick off the import. Faivelo copies your mail over IMAP — nothing is deleted from your Google account. > New to this? Start with the [migration overview](https://faivelo.com/docs/migrations/overview) for how the whole wizard works. ## Before you start - Your domain is added to Faivelo. The wizard **creates the destination mailbox for you** (or you can point it at an existing one), so you don't need to set one up first. - Testing the connection (the pre-flight check) is free; running the actual migration is included with any paid plan. ## Step 1: Turn on 2-Step Verification Google only issues app passwords for accounts with 2-Step Verification enabled. If you haven't already, turn it on at [myaccount.google.com/security](https://myaccount.google.com/security){rel=""nofollow""}. ## Step 2: Create an app password 1. Go to [myaccount.google.com/apppasswords](https://myaccount.google.com/apppasswords){rel=""nofollow""}. 2. Give it a name (something like "Faivelo migration") and click **Create**. 3. Copy the 16-character password Google shows you. ::docs-aside{type="note"} An app password is not your normal Gmail password. It's a one-off credential you can revoke later without touching your real login. Faivelo removes the spaces automatically when you paste it, so don't worry about formatting. :: ## Step 3: Start the migration 1. In your Faivelo dashboard, open **Migrations**. 2. Pick **Gmail / Google Workspace** as the source — the server settings (`imap.gmail.com`) are filled in for you. 3. Choose the destination domain, then enter your Gmail address and paste the app password, and map it to the destination mailbox. 4. Faivelo runs a quick pre-flight check and shows you exactly what will move: your folders, the message count, the size, and a time estimate. 5. Review the folder list, then click **Start migration**. ## What gets copied - All your mail folders (labels) and the messages in them, preserving folder structure. - Trash and Spam are skipped by default — they rarely need to come along and just slow things down. - Gmail's virtual folders like **All Mail**, **Important**, and **Starred** are excluded automatically, so you won't end up with duplicate copies of every message. ## How long it takes The pre-flight check gives you an estimate up front. As a rule of thumb, expect roughly a few messages per second — Gmail throttles bulk IMAP access, so a large mailbox with tens of thousands of messages can take a few hours. You can watch live progress bars in the dashboard, and you don't need to keep the page open. ::docs-aside{title="Mail keeps flowing" type="tip"} The migration only reads from Gmail — it never deletes or changes anything there. Your Faivelo mailbox receives new mail normally the whole time, so there's no downtime and no gap in your inbox. You can keep sending and receiving while old mail copies over in the background. :: ## Bringing your calendar Mail moves over IMAP; your calendar comes across as a file — it takes about a minute: 1. In Google Calendar, open **Settings → Import & export → Export**. Google downloads a zip with one `.ics` file per calendar. 2. In Faivelo webmail, open **Calendar → Sync**, then **Import a calendar (.ics)** and pick the file. 3. Every event lands in your Faivelo calendar — including repeating events — and syncs out to any device you've connected. Importing the same file again updates events instead of duplicating them. ## Bringing your contacts 1. In [Google Contacts](https://contacts.google.com){rel=""nofollow""}, choose **Export** and keep the default **Google CSV** format. 2. In your Faivelo dashboard, open **Contacts → Import** and drop the file in — Faivelo recognizes Google's column names automatically. 3. Imported contacts appear in compose autocomplete in webmail, and sync to phones and Apple Contacts for every mailbox you've granted address-book access. ## After the migration - Spot-check a few folders in Faivelo webmail to confirm everything arrived. - Revoke the app password in your Google account — it's no longer needed. - If you're moving off Gmail entirely, make sure your domain's MX records point at Faivelo so new mail arrives in the right place. ## Next steps - [Migrating from Microsoft 365](https://faivelo.com/docs/migrations/from-microsoft-365) — if you have other accounts to bring over. - Set up your mail apps with your new Faivelo mailbox, or use Faivelo webmail right away. # Migrating from Microsoft 365 Moving from Microsoft 365 (or a personal Outlook.com account) to Faivelo doesn't require any passwords or app-specific credentials. You sign in with Microsoft once, approve access, and Faivelo copies your mail over. Nothing is deleted from your Microsoft account. ## Before you start - Your domain is added and verified in Faivelo, and the destination mailbox exists. If the domain has no mailboxes yet, create them first. - Testing the connection (the pre-flight check) is free; running the actual migration is included with any paid plan. ## Step 1: Start the migration 1. In your Faivelo dashboard, open **Migrations**. 2. Pick **Microsoft 365** as the source. 3. Choose the destination domain for your imported mail. ## Step 2: Sign in with Microsoft Faivelo sends you to the official Microsoft sign-in page — you enter your credentials with Microsoft, never with us. 1. Pick the account you want to migrate (Microsoft always lets you choose, even if you're already signed in to another account). 2. Review the consent screen. Faivelo asks for permission to read your mailbox over IMAP, plus offline access so the import can keep running after you close the page. 3. Approve, and you're sent back to the Faivelo dashboard. ::docs-aside{title="Work or school account blocked?" type="caution"} Some organizations restrict which third-party apps their users can approve. If you see a message like "Need admin approval" instead of a consent screen, your Microsoft 365 administrator has to grant consent for Faivelo first (or approve your request through Microsoft's admin-consent workflow). Personal Outlook.com accounts are never affected by this. :: ## Step 3: Review and run the import 1. Back in the dashboard, Faivelo runs a pre-flight check on the connected account and shows what will move: folders, message count, size, and a time estimate. 2. Map the source account to its destination Faivelo mailbox. 3. Click **Start migration**. The import runs in the background — you can watch live progress bars in the dashboard, but you don't need to keep the page open. ## What gets copied - Your mail folders and the messages in them, preserving the folder structure. - Deleted Items and Junk are skipped by default — they rarely need to come along. ## How long it takes The pre-flight estimate is your best guide. Microsoft throttles bulk mailbox access, so expect roughly a few messages per second: a small mailbox finishes in minutes, while tens of thousands of messages can take a few hours. ::docs-aside{title="Mail keeps flowing" type="tip"} The migration only reads from Microsoft 365 — it never deletes or changes anything there. Your Faivelo mailbox keeps receiving new mail normally the whole time, so there's no downtime while old mail copies over. :: ## After the migration - Spot-check a few folders in Faivelo webmail to confirm everything arrived. - You can remove Faivelo's access from your Microsoft account settings — the connection isn't needed after the import finishes. - If you're leaving Microsoft 365 entirely, make sure your domain's MX records point at Faivelo so new mail arrives in the right place. ## Next steps - [Migrating from Gmail](https://faivelo.com/docs/migrations/from-gmail) — if you have Google accounts to bring over too. - Set up your mail apps with your new Faivelo mailbox, or use Faivelo webmail right away. # Quickstart: send and receive email from code This page gets a script or an AI agent from nothing to sending and receiving real email on your own domain. Every command runs as pasted once two values are set. ## What you need first 1. **A Faivelo account with a verified domain.** A person sets this up once: sign up at [faivelo.com](https://faivelo.com/register){rel=""nofollow""}, add a domain, and Faivelo writes the DNS records for most hosts (or run `npx faivelo init yourdomain.com` from a terminal). See [Set up from the terminal](https://faivelo.com/docs/cli). 2. **An API key.** A person on the account creates it in [Settings → Developers](https://faivelo.com/settings/developers){rel=""nofollow""}. Pick the **agent** kind for anything autonomous. Give it the scopes `mail:send`, `mail:read`, `mailboxes:read` and `mailboxes:write`. The key starts with `fvl_live_` and is shown once. The API is included on every paid plan and during the free trial. Set both values in your shell: ```bash export FAIVELO_API_KEY="fvl_live_..." # the key from Settings → Developers export DOMAIN="yourdomain.com" # a verified domain on the account ``` Check the key works: ```bash curl https://faivelo.com/api/v1/mailboxes \ -H "Authorization: Bearer $FAIVELO_API_KEY" ``` A `200` with `{"success":true,"data":[...]}` means you are ready. Anything else returns an error with a `code` and a `fix`; see [Errors](https://faivelo.com/docs/developers/errors). ## Send an email `POST /api/v1/emails` sends from any address on a verified domain. No mailbox has to exist for the sender. ```bash curl https://faivelo.com/api/v1/emails \ -H "Authorization: Bearer $FAIVELO_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"from\": \"hello@$DOMAIN\", \"to\": \"you@example.com\", \"subject\": \"It works\", \"text\": \"Sent with the Faivelo API.\" }" ``` The response holds an `id`. `GET /api/v1/emails/{id}` returns its delivery status (`sent`, `delivered`, `bounced`, `complained` or `failed`). To retry safely after a network error, add an `Idempotency-Key` header. Two requests with the same key send at most one email. See [Sending via the API](https://faivelo.com/docs/transactional/send-api). ## The same in Node.js ```bash npm install faivelo ``` ```ts import { Faivelo } from 'faivelo' const faivelo = new Faivelo(process.env.FAIVELO_API_KEY!) const email = await faivelo.emails.send({ from: `hello@${process.env.DOMAIN}`, to: 'you@example.com', subject: 'It works', text: 'Sent with the Faivelo SDK.' }) console.log(email.id) ``` A failed call throws `FaiveloError` with the HTTP `statusCode` and the API's message. ## Give an agent its own mailbox An agent that signs up for services or talks to people needs an address that can receive mail too. Create one: ```bash curl https://faivelo.com/api/v1/mailboxes \ -H "Authorization: Bearer $FAIVELO_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"domain\": \"$DOMAIN\", \"localPart\": \"agent\"}" ``` `agent@yourdomain.com` now exists. An agent key can only see mailboxes it created or was granted, so it can never read the rest of the account. A key may create 10 mailboxes per 24 hours. Send as that mailbox (the message lands in its Sent folder, and replies come back to it): ```bash curl "https://faivelo.com/api/v1/mailboxes/agent@$DOMAIN/send" \ -H "Authorization: Bearer $FAIVELO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"to": "you@example.com", "subject": "Hello from an agent", "text": "Reply to this and I will read it."}' ``` ## Read the replies List the newest messages in the inbox: ```bash curl "https://faivelo.com/api/v1/mailboxes/agent@$DOMAIN/messages?folder=INBOX&limit=10" \ -H "Authorization: Bearer $FAIVELO_API_KEY" ``` Each message has a `uid`. Read one in full, body included: ```bash curl "https://faivelo.com/api/v1/mailboxes/agent@$DOMAIN/messages/" \ -H "Authorization: Bearer $FAIVELO_API_KEY" ``` Polling works for a script that waits for one verification code. For anything long-running, use a webhook instead. ## Get replies pushed as webhooks Add an endpoint in [Settings → Developers → Webhooks](https://faivelo.com/settings/developers/webhooks){rel=""nofollow""} and subscribe to `message.received` (Pro and Business). Faivelo sends a signed `POST` to your URL the moment mail arrives: ```json { "id": "evt_01J8ZK3V5QXR7", "type": "message.received", "created_at": "2026-09-20T14:02:11Z", "data": { "mailbox": "agent@yourdomain.com", "message_id": "eaaaaab", "thread_id": "b", "folder": "INBOX", "from": { "name": "Dana Whitfield", "address": "dana@northwind.io" }, "subject": "Re: Hello from an agent", "snippet": "Thanks, here is the code you asked for..." } } ``` Check the signature before trusting the body. Pass the raw body, not parsed JSON: ```ts import { Faivelo } from 'faivelo' const event = await Faivelo.webhooks.verify( rawBody, request.headers['x-faivelo-signature'], process.env.FAIVELO_WEBHOOK_SECRET! ) if (event.type === 'message.received') { // event.data.message_id works anywhere the API takes a message uid } ``` Every event, the payloads and the retry rules are in [Webhooks](https://faivelo.com/docs/developers/webhooks). ## Use it from an AI agent over MCP The hosted MCP server exposes the same actions as tools (`send_message`, `list_messages`, `read_message`, `create_mailbox` and more) at `https://faivelo.com/api/mcp`, over Streamable HTTP. It is included from the Growth plan. Claude Code, with an API key: ```bash claude mcp add --transport http faivelo https://faivelo.com/api/mcp \ --header "Authorization: Bearer $FAIVELO_API_KEY" ``` Any MCP client that reads JSON config: ```json { "mcpServers": { "faivelo": { "type": "http", "url": "https://faivelo.com/api/mcp", "headers": { "Authorization": "Bearer fvl_live_..." } } } } ``` Without a key, `claude mcp add --transport http faivelo https://faivelo.com/api/mcp` signs in through the browser instead, and the person picks which mailboxes the agent may use. See [Connect Claude](https://faivelo.com/docs/developers/connect-claude) and [AI agents & API keys](https://faivelo.com/docs/developers/ai-agents). ## For agents reading this page - Every docs page is available as markdown: add `.md` to its URL, for example `https://faivelo.com/docs/developers/quickstart.md`. - The index of all pages is at {rel=""nofollow""}, and all of them in one file at {rel=""nofollow""}. - The OpenAPI 3.1 spec is at {rel=""nofollow""}. - Errors carry a stable `code`, a `fix` and a `docs` link. Branch on `code`. See [Errors](https://faivelo.com/docs/developers/errors). - Creating an account, verifying a domain and creating a key need a person today. # Connect Claude Faivelo ships a hosted MCP (Model Context Protocol) server, so you can connect Claude directly to your mailboxes — read, search, send, and tidy up your mail by just asking. Setup takes about a minute, and there are no API keys to copy around: you sign in, pick exactly which mailboxes Claude may touch, and approve. You need an active paid Faivelo plan to use the connection. ## Connect claude.ai 1. In [claude.ai](https://claude.ai){rel=""nofollow""}, open **Settings → Connectors**. 2. Click **Add custom connector**and paste: ```text https://faivelo.com/api/mcp ``` 3. Your browser opens the Faivelo sign-in page — log in if you aren't already. 4. On the consent screen, choose which of your mailboxes Claude may access. Only the mailboxes you tick are reachable — everything else on your account stays invisible. 5. Optionally tick **Allow creating new mailboxes** if you want Claude to be able to provision new addresses on your domains (capped at 10 per day; new mailboxes it creates are added to the connection automatically). 6. Click **Approve**. That's it — no keys to copy, nothing to paste back. ## Connect Claude Code One command: ```bash claude mcp add --transport http faivelo https://faivelo.com/api/mcp ``` The first time Claude Code uses the connector, it opens the same Faivelo sign-in and mailbox picker in your browser. ## What Claude can do Once connected, Claude gets a full mail toolset — scoped to the mailboxes you selected: | Ability | Tools | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Get oriented | `list_mailboxes`, `list_domains`, `get_account_summary` (send quota used/remaining), `get_setup_summary` (a shareable summary of what is set up) | | Read mail | `list_messages`, `read_message`, `get_thread` (whole conversations), `search_messages`, `search_all_mailboxes` (one query across every shared mailbox), `list_folders`, `get_attachment` | | Look up contacts | `get_contacts` | | Send mail | `send_message` — supports attachments and a `sendAt` time; counts against your plan's send allowance | | Drafts and scheduled sends | `create_draft`, `update_draft`, `send_draft` (leave a reply in Drafts for you to check first), `list_scheduled`, `cancel_scheduled` | | Manage messages | `flag_message`, `label_message`, `mark_all_read`, `move_message`, `restore_message`, `mark_spam`, `delete_message`, `empty_trash` | | Manage aliases | `list_aliases`, `create_alias`, `delete_alias` — aliases may only route to the mailboxes you shared | | Check deliverability | `get_delivery_status` — did mail to a recipient bounce, are they suppressed? | | Browse Drive | `drive_list_files`, `drive_download_file` — only appear if you granted Drive access during consent | | Create mailboxes | `create_mailbox` — only appears if you opted in during consent | | Manage DNS | `list_dns_records`, `create_dns_record`, `update_dns_record`, `delete_dns_record` — API keys with the `dns:read` / `dns:write` scopes only, not Claude connections | ::docs-aside{title="Connected before these tools existed?" type="note"} Connections made before the toolset expanded won't have alias permissions. Disconnect and reconnect the Faivelo connector to pick up the full set. :: ## Things to try - "Summarize my unread mail." - "Find the invoice from Acme and reply that payment is on the way." - "Search support@ for anything mentioning refunds this week and give me a rundown." - "Move all the newsletters in my inbox to the Newsletters folder." ## Managing and revoking access Every connection is listed in your Faivelo dashboard under **Settings → Connected Apps**. You can see what each app can reach and revoke it with one click — revoking cuts access instantly. ## Security - **You choose the blast radius.** Claude can only reach the mailboxes you picked on the consent screen — never your other mailboxes, domains, billing, or account settings. - **Tokens expire and rotate.** Access tokens are short-lived (one hour) and refreshed automatically with rotating refresh tokens. If a rotated token is ever replayed, the whole connection is revoked as a precaution. - **Everything is revocable.** Remove the connection from Settings → Connected Apps at any time, and access stops immediately. ::docs-aside{type="note"} Sending through the connector uses your plan's normal monthly send allowance, and message actions (delete, move, mark spam) are real — Claude asks before doing anything destructive, but the changes it makes are the same as if you'd made them in webmail. :: ## Next steps - Building a headless agent instead? See [AI agents & API keys](https://faivelo.com/docs/developers/ai-agents) for scoped API keys and the same MCP server with Bearer auth. # AI agents & API keys AI agents need real email addresses — to sign up for services, receive verification codes, and talk to humans. Faivelo lets an agent spin up its own mailbox on your domain and drive it over a simple REST API or the hosted MCP server, with credentials that can't touch the rest of your account. The REST API is included on every paid plan (and during the free trial); the hosted MCP server is included from Growth. Sending pace scales with the plan — see [Rate limits](https://faivelo.com/docs/#rate-limits). An agent with no account at all can start on a free address: see [Start without an account](https://faivelo.com/docs/#start-without-an-account). ## Start without an account An agent in a terminal has no browser, no card and no inbox of its own to confirm. One call gives it a free address, an inbox on it and a key bound to that inbox: ```bash curl -X POST https://faivelo.com/api/v1/signup \ -H "Content-Type: application/json" \ -d '{"name": "acme-bot"}' ``` Or, with Node installed, the same thing from the CLI (it also writes `FAIVELO_API_KEY` and `FAIVELO_INBOX` to `./.env` when run inside a project): ```bash npx faivelo inbox acme-bot --json ``` The answer: ```json { "address": "agent@acme-bot.fvlmail.com", "api_key": "fvl_live_...", "claim_url": "https://faivelo.com/claim/...", "expires_at": "2026-10-11T12:00:00.000Z", "base_url": "https://faivelo.com/api/v1/mailboxes/agent@acme-bot.fvlmail.com", "mcp_url": "https://faivelo.com/api/mcp" } ``` `name` is optional (a random `agent-xxxxx` is picked otherwise) and `inbox` sets the local part (default `agent`). The key is shown once. ### Until a person claims it The account has nobody behind it yet, so it is **receive-first**: the inbox receives, the key reads, searches, fetches attachments and connects over MCP, which is enough to sign up for a service, read the code and hold a conversation. Sending is limited to **replies**: up to 5 a day, only to addresses that wrote to the inbox first. Any other send answers `403` with code `CLAIM_REQUIRED`. Every response carries `X-Faivelo-Claim: required` and `X-Faivelo-Claim-Expires`; after 7 days unclaimed the address and the account are removed. ### Claiming `claim_url` is for the person the agent works for. They open it, sign in or create a free account, and the address, its inboxes, keys and webhooks move into their account: the keys keep working, sending opens up to the free plan's 50 a day, the expiry goes away and the Inboxes console shows what the agent set up. The link is single-use; `POST /api/v1/account/claim` with the inbox key mints a fresh one. Signups are budgeted per address, per network and platform-wide; a refused one answers `429` or `503` with a plain message. ## Key kinds: account vs agent Faivelo has two kinds of API key: | Kind | Reach | Use for | | ----------- | ------------------------------------------------------------------- | --------------------------------------------- | | **Account** | The whole account, within its scopes | Your own scripts, integrations, admin tooling | | **Agent** | Sandboxed: only mailboxes the key created or was explicitly granted | Credentials you hand to an AI agent | Agent keys are the safe default for autonomous software. An agent key can create mailboxes and then operate them — but it can never read your other inboxes, add or remove domains or aliases, touch billing, or mint new keys. Revoke it at any time and access stops instantly. ## Create a key 1. Go to [Settings → Developers](https://faivelo.com/settings/developers){rel=""nofollow""} in your dashboard. 2. Choose the kind (**agent** for anything autonomous) and the scopes it needs. 3. Copy the key — it starts with `fvl_live_` and is shown exactly once. ## Scopes | Scope | Grants | | -------------------------------- | ----------------------------------------------------------------------- | | `mail:read` | List, read, and search messages; folders; contacts | | `mail:send` | Send mail (counts against your plan's send allowance) | | `mail:write` | Flag, move, mark spam, delete messages | | `mailboxes:read` | List mailboxes | | `mailboxes:write` | Create and update mailboxes | | `dns:read` / `dns:write` | Query and edit a domain's live DNS records | | `domains:read` / `domains:write` | Manage domains (account keys only) | | `aliases:read` / `aliases:write` | Manage aliases (account keys only) | | `drive:read` | List files and folders in your Faivelo Drive and get file download URLs | Agent keys can hold at most the mailbox, DNS and mail scopes — domain and alias management is deliberately off-limits so an agent credential can never reshape your account. DNS is allowed because agents pointing records at their own services is a core use case; records that email delivery depends on (MX, SPF, DKIM, DMARC, …) are flagged `mailCritical` and any edit or delete of them is refused unless the request repeats with an explicit `force: true`. ## Rate limits | Limit | Value | | ------------------------------------------- | ------------------------------------------------------------------------------ | | Requests per key | 120 per minute | | Mailbox creations per key | 10 per rolling 24 hours | | Sending | Counts against your plan's monthly allowance | | Sending rate (recipients/min) | Starter: 10 · trial: 10 · Growth: 60 · Pro: 120 · Business: 240 | | Transactional emails per month | Trial: 100 · Starter: 3,000 · Growth: 20,000 · Pro: 50,000 · Business: 100,000 | | Transactional emails per day | Starter: 300 · Growth: 2,000 · Pro: 5,000 · Business: 10,000 | | Marketing sends per month (separate budget) | Growth: 3,000 · Pro: 25,000 · Business: 100,000 | Sending limits are counted per account (not per key) across the REST API, MCP, and transactional sending together. Exceeding one returns `429` with a plain-English message and how long to wait; a request with more recipients than your per-minute rate is rejected outright — split the list. Like every email provider, new accounts also warm up: sending volume starts modest and rises automatically as you send cleanly, the same way a fresh domain builds reputation. You'll rarely notice it — and if your sending has outgrown the automatic ramp, request a higher limit in Settings → Sending limits; it's usually approved the same day. ## REST API The full REST surface — domains, mailboxes, aliases, sending, folders, messages, search, attachments — is documented in the [API reference](https://faivelo.com/docs/api){rel=""nofollow""}. Authenticate with a Bearer header: ```bash curl https://faivelo.com/api/v1/mailboxes \ -H "Authorization: Bearer fvl_live_..." ``` The typical agent loop is three calls: `POST /api/v1/mailboxes` to provision an address like `my-agent@yourdomain.com`, `POST /api/v1/mailboxes/{address}/send` to send, and the message endpoints to poll for and read replies (great for extracting verification codes). For application mail — receipts, password resets, alerts — see [Transactional email](https://faivelo.com/docs/transactional/overview): `POST /api/v1/emails` sends from any address on a verified domain with no mailbox required, supports designed templates, and can push delivery events to your server via webhooks. ### Reading Drive files With the `drive:read` scope a key can browse the account's Faivelo Drive and pull file contents — useful for agents and integrations that need to ingest a stored spreadsheet or document. List a folder (omit `parentId` for the root), then exchange a file id for a short-lived download URL: ```bash # List the Drive root curl "https://faivelo.com/api/v1/drive" \ -H "Authorization: Bearer fvl_live_..." # Get a presigned URL for a file, then download it curl "https://faivelo.com/api/v1/drive//download-url" \ -H "Authorization: Bearer fvl_live_..." ``` ## MCP for headless agents The same hosted MCP server that powers the [Claude connector](https://faivelo.com/docs/developers/connect-claude) accepts raw API keys, so headless agents skip OAuth entirely. Point any Streamable-HTTP MCP client at the endpoint with a Bearer header: ```json { "mcpServers": { "faivelo": { "url": "https://faivelo.com/api/mcp", "headers": { "Authorization": "Bearer fvl_live_..." } } } } ``` If your client can't set custom headers, embed the key in the URL instead: ```text https://faivelo.com/api/mcp/fvl_live_... ``` ::docs-aside{type="caution"} A key in a URL can end up in logs and config files. Prefer the Authorization header whenever your client supports it, and rotate any key you suspect has leaked. :: The MCP toolset covers the full mail surface: discovery (`list_mailboxes`, `list_domains`, `get_account_summary`, `get_setup_summary`), reading (`list_messages`, `read_message`, `get_thread`, `search_messages`, `search_all_mailboxes`, `list_folders`, `get_contacts`, `get_attachment`), sending (`send_message` with attachments and an optional `sendAt`), drafts and scheduled sends (`create_draft`, `update_draft`, `send_draft`, `list_scheduled`, `cancel_scheduled`), housekeeping (`flag_message`, `label_message`, `mark_all_read`, `move_message`, `restore_message`, `mark_spam`, `delete_message`, `empty_trash`), aliases (`list_aliases`, `create_alias`, `delete_alias`), DNS (`list_dns_records`, `create_dns_record`, `update_dns_record`, `delete_dns_record` — mail-critical records need `force: true`), deliverability (`get_delivery_status`), Drive (`drive_list_files`, `drive_download_file` — with the `drive:read` scope), and `create_mailbox` — all enforcing the same scoping, creation caps, and rate limits as the key itself. Agent keys see only the mailboxes they created or were granted, and their aliases may only route to those mailboxes. ## Next steps - [API reference](https://faivelo.com/docs/api){rel=""nofollow""} — every endpoint, schema, and example. - [Connect Claude](https://faivelo.com/docs/developers/connect-claude) — the no-key OAuth flow for claude.ai and Claude Code. # Webhooks A webhook is a URL on your server that Faivelo calls when something happens in your account. Instead of asking the API "anything new?" every few seconds, you hear about it the moment it happens. Webhooks are included on the Growth, Pro and Business plans (not on free trials). Every plan can have up to 10 endpoints. The delivery log and Events list keep 3 days on Growth, 7 on Pro and 30 on Business. Manage them in [Settings → Developers → Webhooks](https://faivelo.com/settings/developers/webhooks){rel=""nofollow""}. ## Add an endpoint 1. Open **Settings → Developers → Webhooks** and choose **Add endpoint**. 2. Enter an `https` URL, pick the events you want, and choose whether to listen to the whole account or only some domains or mailboxes. 3. Copy the **signing secret**. It is shown once. 4. Press **Send test event**. You see what your server answered straight away. ## Events | Event | Fires when | | ------------------------- | ------------------------------------------------------------------------------------------------------ | | `message.received` | A new message landed in a mailbox, spam folder included. Pro and Business. | | `message.sent` | A message left a mailbox for the outside world, from webmail, a mail app or the API. Pro and Business. | | `email.delivered` | The recipient's server accepted an email sent through the API. | | `email.bounced` | An email could not be delivered. | | `email.complained` | The recipient marked an email as spam. | | `mailbox.created` | A mailbox was created. | | `mailbox.deleted` | A mailbox was deleted. | | `account.sending_paused` | We paused sending for the whole account, usually for bounces or spam reports. | | `account.sending_resumed` | Sending was restored after a pause. | | `account.storage_warning` | Storage passed 80% or 95% of the plan. Repeats daily while it stays there. | | `domain.verified` | A domain passed verification. | | `domain.dns_broken` | A required DNS record on a verified domain went missing or changed. | | `domain.expiring` | A domain registered with us expires in 30 days, and again at 7 days. | ## The payload Every event has the same envelope. `data` depends on the event type. ```json { "id": "evt_01J8ZK3V5QXR7", "type": "email.bounced", "created_at": "2026-09-20T14:02:11Z", "data": { "email_id": "em_01J8ZJW2HN", "from": "billing@testcompany.com", "to": ["dana@northwind.io"], "subject": "Your receipt from Test Company", "bounce": { "type": "permanent", "reason": "Mailbox does not exist" } } } ``` ### Message events `message.received` and `message.sent` carry a summary of the message, not the whole thing: ```json { "id": "evt_01J8ZK3V5QXR7", "type": "message.received", "created_at": "2026-09-20T14:02:11Z", "data": { "mailbox": "support@testcompany.com", "message_id": "eaaaaab", "thread_id": "b", "folder": "INBOX", "from": { "name": "Dana Whitfield", "address": "dana@northwind.io" }, "to": [{ "name": "Test Company Support", "address": "support@testcompany.com" }], "subject": "Question about our invoice", "snippet": "Hi team, I noticed the March invoice lists two seats we removed in February...", "received_at": "2026-09-20T14:02:11Z", "attachments": [{ "name": "invoice-march.pdf", "content_type": "application/pdf", "size": 48213 }] } } ``` `message_id` is the message's permanent id. Pass it to the API wherever a message UID goes, for example `GET /api/v1/mailboxes/support@testcompany.com/messages/eaaaaab`, to read the full body, download attachments, flag, move or delete it. Unlike a UID it stays the same when the message moves to another folder. Two things to know about `message.sent`. It arrives about 20 seconds after the send, because mail apps save the Sent copy after sending. And an app that keeps no Sent copy (plain SMTP senders) still fires the event, with `message_id`, `thread_id`, `subject` and `snippet` set to `null`. An endpoint narrowed to certain domains or mailboxes only hears about those. One account can cause at most 2,000 message events an hour; past that they are dropped, not delayed. ## Partner endpoints Partners add endpoints in the partner console under **Developers**. One endpoint receives events for every customer you created, and every payload carries a `customer_id`. Partner endpoints also get `customer.created`, `customer.plan_changed`, `customer.paused` and `customer.resumed` (the last two are your own pauses; a pause by Faivelo arrives as `account.sending_paused`). Customers created with a sandbox key fire events too, marked `"sandbox": true`. `message.received` and `message.sent` reach a partner endpoint only for customers where you hold a mailbox key with the `mail:read` scope, and they carry a pointer rather than the mail itself: `mailbox`, `message_id`, `thread_id`, `folder` and `received_at`. No sender, subject or snippet. Fetch the message with that customer's key, `GET /api/v1/mailboxes/{address}/messages/{message_id}`, which is also what puts the read on the customer's audit trail. ## Verify the signature Each request has an `X-Faivelo-Signature` header: `t=,v1=`. The signature is HMAC-SHA256 of `.` with your signing secret. The SDK (0.6.0 and later) checks it, and rejects timestamps older than 5 minutes, in one call. It throws `FaiveloWebhookError` when a request cannot be trusted; answer those with a 400. ```ts import { Faivelo } from 'faivelo' const event = await Faivelo.webhooks.verify( rawBody, // the raw request body, not parsed JSON request.headers['x-faivelo-signature'], process.env.FAIVELO_WEBHOOK_SECRET ) ``` ## Limits To keep webhooks from being pointed at other people's servers, test events and resends are limited to 20 per 10 minutes per account, and the URL must resolve to a public address. We do not follow redirects. ## Delivery and retries - Answer with any `2xx` within 10 seconds. Do slow work after you respond. - A failed delivery is retried with growing pauses for 24 hours. - An event can arrive more than once. Use its `id` to ignore repeats. - Events can arrive out of order. Use `created_at` if order matters. - An endpoint that fails every delivery for 5 days is turned off, and we email you. Turn it back on from its page once your server is fixed. ## Debugging Each endpoint has a **Deliveries** log: every attempt, the exact body we sent, what your server answered, and a **Resend** button. The **Events** tab lists everything that happened since you added your first endpoint, for the last 30 days, including events no endpoint was subscribed to. # Partner API Faivelo partners resell mailboxes to their own clients: agencies putting their clients on email, hosting companies adding a modern mailbox, and platforms that want an inbox inside their own product. One API creates a customer, their domain and their mailboxes. Your clients see your name, and you set your price. ## Two ways to run it It is up to you how much of Faivelo your clients see. - **Use our white-label apps.** The partner console at `partner.faivelo.com` manages customers, domains and mailboxes by hand, and your clients get a webmail, calendar and Drive at your logo and colours, with every email from us in your name and their language. No code required. - **Build your own on the API.** Keep clients inside your own product: create customers, domains and mailboxes from your code, read DNS status and health, and pull the usage report into your billing. Your clients use any mail app, or a front end you build. Both are included in the same per-customer price, and you can mix them. Everything the console does is an API call, so starting by hand and automating later loses nothing. This page covers the API. The console's Guides section explains the rules of being a partner in plain language. ## Partner keys Partner accounts get a third kind of API key, `partner`, issued from **Developers** in the partner console once your account is approved. A partner key: - acts on your end customers, never on your own account; - holds only the scopes `partner:read` and `partner:write`; - works under `/api/partner`, and is refused by `/api/v1` and the MCP server. Send it as a Bearer token, like any other key: ```text Authorization: Bearer fvl_live_xxxxxxxxxxxxxxxxxxxx ``` A customer that is not yours answers **404**, never 403, so a key learns nothing about other accounts. ## Sandbox mode Mint a partner key with **Sandbox** ticked and it starts with `fvl_test_` instead of `fvl_live_`. Same endpoints, same responses, but every customer it creates is a sandbox: domains come back verified the moment you add them, mailboxes exist only as rows with credentials, nothing touches the mail server, no seat lands on your invoice, no email goes to anyone, and nothing counts in the reputation ladder, reports or outbox. Live and sandbox customers never see each other. One call exists for sandbox only: `DELETE /customers/{id}` erases a sandbox customer. Anything you leave behind is erased after 30 days. The console has the same switch under your organisation name: in Sandbox mode it shows sandbox customers only, and a New customer there creates a sandbox. ## The onboarding loop Every partner integration is the same four calls. In the SDK: ```ts import { Faivelo } from 'faivelo' const faivelo = new Faivelo(process.env.FAIVELO_PARTNER_KEY!) // 1. Create the customer. You attest, per customer, that their lists are // first-party and that you accepted the end-customer terms for them. const customer = await faivelo.partner.customers.create({ email: 'owner@smiledental.example', companyName: 'Smile Dental', attestation: { firstPartyListsOnly: true, termsAcceptedOnBehalf: true } }) // 2. Add their domain. The response lists the DNS records to show them. const domain = await faivelo.partner.domains.add(customer.id, { domain: 'smiledental.example', brandName: 'Smile Dental' }) // domain.dnsRecords -> [{ type: 'MX', name: ..., value: ..., verified: false }, ...] // 3. Poll until the records are live. const status = await faivelo.partner.domains.get(customer.id, 'smiledental.example', { verify: true }) // 4. Create mailboxes. Password and IMAP/SMTP settings come back once. if (status.verified) { const inbox = await faivelo.partner.mailboxes.create(customer.id, 'smiledental.example', { localPart: 'hello', displayName: 'Smile Dental' }) // inbox.credentials.password, inbox.credentials.imapServer, ... } ``` The same loop with curl is in the [API reference](https://faivelo.com/docs/api#tag/partners){rel=""nofollow""}. The customer has no password and no Faivelo dashboard by design. They use the webmail, which wears your brand, and you operate the account through the API or the console. ## What the customer sees Each customer domain gets a webmail at its own subdomain. The look is resolved per domain, in this order: 1. The domain's own name and logo, set with `PUT /customers/{id}/domains/{domain}/branding`. 2. Your partner brand, set once in the console: logo, sign-in photo, theme, favicon. 3. Faivelo's stock look. The sign-in page and the inbox carry a small "Powered by Faivelo" line. Everything else is yours. ## Sending health Every customer is an isolated sending tenant with its own reputation. `GET /customers/{id}` reports: | Field | Meaning | | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `status` | `active`, `paused` or `suspended` | | `lockedBy` | Who set the current sending lock: `partner` (you), `faivelo` (an abuse control), or null | | `rates` | The customer's own sends, bounces and complaints over the last 30 days, and whether it is over the pause line on its own numbers | | `reputation` | The tenant's sending state, ours and the mail provider's | | `relayCeiling` | `trial` until the customer earns the standard ceiling on clean history | | `domainList` | Per-domain verification, enforcement tier and rates | Use `POST /customers/{id}/pause` to hold a customer's sending yourself and `resume` to lift it. A lock set by a Faivelo abuse control is not lifted by `resume`; the console shows what it needs. Bounces and complaints count against the whole partner account as well as the customer. A customer that crosses the line is paused on its own; a pattern across customers pauses provisioning for the partner. The thresholds are published in the console's Guides and never change without notice. ## The outbox `GET /outbox` lists every system email Faivelo sent about your customers: set-up mail, credentials, recovery, notices. Filter by customer, category, status and date. `GET /outbox/{id}` returns the body, except for credential and sign-in link mail, which never stores one. ## Webhooks Rather than polling, add an endpoint in the partner console under **Developers**. One endpoint hears every customer, each payload carries a `customer_id`, and you get customer events (`customer.created`, `customer.plan_changed`, `customer.paused`, `customer.resumed`) next to the account, domain and delivery events. If you are building an inbox into your own product, `message.received` tells you the moment mail lands. Signatures, retries and the payloads are in the [Webhooks guide](https://faivelo.com/docs/developers/webhooks#partner-endpoints). ## Billing your clients You bill your clients; Faivelo bills you one seat per live customer. `GET /reports/usage?month=2026-09` returns one line per customer for the month: days live, domains, mailboxes, storage, sends, bounces and complaints. Add `format=csv` to download a file. The console's Reports page shows the same table. ## Limits - 120 requests per minute per key. - Provisioning is refused with **403** while your partner account is paused or at its customer cap. - New customers start on the trial sending ceiling and graduate automatically. ## Endpoints | Method | Path | Scope | | ------ | --------------------------------------------------------------------- | --------------- | | GET | `/customers` | `partner:read` | | POST | `/customers` | `partner:write` | | GET | `/customers/{id}` | `partner:read` | | POST | `/customers/{id}/pause` | `partner:write` | | POST | `/customers/{id}/resume` | `partner:write` | | GET | `/customers/{id}/domains` | `partner:read` | | POST | `/customers/{id}/domains` | `partner:write` | | GET | `/customers/{id}/domains/{domain}` | `partner:read` | | DELETE | `/customers/{id}/domains/{domain}` | `partner:write` | | PUT | `/customers/{id}/domains/{domain}/branding` | `partner:write` | | GET | `/customers/{id}/domains/{domain}/mailboxes` | `partner:read` | | POST | `/customers/{id}/domains/{domain}/mailboxes` | `partner:write` | | DELETE | `/customers/{id}/domains/{domain}/mailboxes/{address}` | `partner:write` | | POST | `/customers/{id}/domains/{domain}/mailboxes/{address}/reset-password` | `partner:write` | | GET | `/outbox` | `partner:read` | | GET | `/outbox/{id}` | `partner:read` | | GET | `/reports/usage` | `partner:read` | All paths are under `https://faivelo.com/api/partner`. Full request and response shapes are in the [API reference](https://faivelo.com/docs/api#tag/partners){rel=""nofollow""}. # Intake and Lens ::note Intake and Lens are in beta. The payload shape is stable, but Lens fields can be wrong: treat them as a first pass and check them before you act on them. :: Intake watches a mailbox. Every email that lands in it is fetched whole, the reply is separated from quoted history, attachments become download links, and the result reaches you as a signed `intake.message` webhook, or waits in the API if you set no webhook. Lens is the optional layer on top: you describe the fields you want, Lens reads each email and fills them in. Intake is included on the Pro and Business plans. Free trials can set it up and watch messages arrive in the Activity view; webhooks start delivering on a paid plan. Lens comes with 1,000 runs a month on Pro and 2,500 on Business; past that it runs on [extra usage](https://faivelo.com/billing){rel=""nofollow""}, at about a tenth of a cent per email. ## Set it up 1. Open **Intake** in the sidebar and choose **Set up Intake**. 2. Pick a mailbox, or create one on the spot (`invoices@`, `support@`, `leads@`). 3. Give us a webhook URL, pick an endpoint you already have, or choose to read messages from the API instead. 4. Turn on Lens if you want fields. Start from a template (Invoice, Order, Support ticket, Lead, Job application) or write your own list. 5. Press **Send me a test email**. A real email goes to the address, and the parsed payload appears on the page a few seconds later. Intake mailboxes are ordinary mailboxes. Mail keeps arriving as usual, replies work, and you can read the inbox in webmail. Set a retention period (7, 30 or 90 days, or forever) and Intake deletes parsed records and the stored copy after it. ## The payload `intake.message` uses the same envelope as every other [webhook](https://faivelo.com/docs/developers/webhooks). `data` looks like this: ```json { "mailbox": "invoices@example.com", "message_id": "msg_01J8ZK3V5Q", "thread_id": "thr_01J8ZK3V5Q", "from": { "name": "Dana Whitfield", "address": "dana@northwind.io" }, "to": [{ "name": "", "address": "invoices@example.com" }], "cc": [], "reply_to": null, "subject": "Invoice NW-2041 for September", "received_at": "2026-09-20T14:02:11Z", "reply": "Hi team, please find September's invoice attached. Thanks, Dana", "text": "Hi team, please find September's invoice attached...\n\nOn Sep 18, 2026, Example wrote:\n> Could you send it?", "html": "
Hi team, ...
", "headers": { "message_id": "", "date": "Sun, 20 Sep 2026 14:02:11 +0000" }, "attachments": [ { "name": "invoice-NW-2041.pdf", "content_type": "application/pdf", "size": 48213, "url": "https://faivelo.com/api/intake/attachments/…", "expires_at": "2026-09-21T14:02:11Z", "text": "INVOICE NW-2041\nNorthwind Supplies\nDue 2026-10-18 ..." } ], "lens": { "vendor_name": "Northwind Supplies", "invoice_number": "NW-2041", "total_amount": 1240.5, "currency": "USD" }, "intake_id": "clx1intake01", "test": false } ``` | Field | What it is | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reply` | The message with quoted history and the signature removed. What most apps want. | | `text`, `html` | The full body, cut at 100 KB and 200 KB. | | `attachments[].url` | A signed link, valid for 24 hours. No API key needed. | | `attachments[].text` | The readable text inside a PDF, Word, spreadsheet or plain-text attachment (first three files, up to 20,000 characters each). With Lens on, images and scanned PDFs get a transcript here too. `null` otherwise, with `text_error` saying why. | | `lens` | Your fields, keyed as you named them. `null` when Lens is off or did not run. | | `intake_id` | The id to fetch this message again from the API. | | `test` | `true` for the emails Faivelo sends from **Send me a test email**. | ## Lens fields Each field has a key, a type (text, number, date, yes/no, email address, list) and a one-line description of what to look for. Lens returns `null` for anything the email does not say and never invents values. Dates come back as `YYYY-MM-DD`, numbers without currency symbols. Edit fields any time from the **Lens** tab. **Test on recent emails** runs your current list on the last few parsed messages without saving, so you can tune descriptions before they go live. Lens reads the email text and the text inside document attachments (PDF, Word, spreadsheets, plain text), so a CV or an invoice sent as a PDF with an empty body still fills every field. Images and scanned PDFs are read too: Lens looks at the file itself, fills the fields from it, and writes what it read into that attachment's `text`. Limits per message: the first two such files, 5 MB each, scans up to 5 pages. A longer scan comes back as a link with a `text_error` saying so. Reading a scan costs more of a run's tokens than the same content as text, so a message with scans counts toward extra usage sooner once the monthly allowance is gone. | Format | Read as | | ------------------------------------------------------------------------------------ | ----------------------------- | | PDF with a text layer, .docx, .xlsx, .xls, .txt, .md, .csv, .tsv, .json, .rtf, .html | Extracted text | | .png, .jpg, .jpeg, .gif, .webp, scanned PDF | The file itself, with Lens on | | .doc, .pptx, .odt, archives | Link only | ## Reading from the API Everything Intake parses is also available with an API key that has the `mail:read` scope: ```bash curl "https://faivelo.com/api/v1/intake/messages?mailbox=invoices@example.com" \ -H "Authorization: Bearer $FAIVELO_API_KEY" ``` `GET /v1/intake/messages` lists parsed messages newest first (page with `?before=`). `GET /v1/intake/messages/{id}` returns one with the full payload and fresh attachment links. See the [API reference](https://faivelo.com/api/v1/openapi.json){rel=""nofollow""} for the schema. # Use Faivelo from your coding agent Your coding agent can set up email for the project it is building: put `hello@` on the domain, wire the app's transactional email, and read replies. Two pieces make that work, and most tools take both in one command: - **The MCP server** at `https://faivelo.com/api/mcp` lets the agent read, search, send and organise mail, create mailboxes and edit DNS. It signs in through your browser the first time, and you tick which mailboxes it may use. - **The `faivelo-email` skill** teaches the agent the setup path (`npx faivelo init`), the send API, the SDKs and how to verify webhooks, so it writes working code the first time. The MCP server is included from the Growth plan and in the free trial. The skill and the CLI work on any plan. ## Claude Code Plugin with both the MCP server and the skill: ```text /plugin marketplace add ethannschwartz/faivelo-mcp /plugin install faivelo@faivelo ``` MCP server only: ```bash claude mcp add --transport http faivelo https://faivelo.com/api/mcp ``` More on what Claude can do once connected: [Connect Claude](https://faivelo.com/docs/developers/connect-claude). ## Cursor [![Add Faivelo to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=faivelo&config=eyJ1cmwiOiJodHRwczovL2ZhaXZlbG8uY29tL2FwaS9tY3AifQ%3D%3D){rel=""nofollow""} Or add it to `.cursor/mcp.json` (this project) or `~/.cursor/mcp.json` (every project): ```json { "mcpServers": { "faivelo": { "url": "https://faivelo.com/api/mcp" } } } ``` ## VS Code [Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=faivelo&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Ffaivelo.com%2Fapi%2Fmcp%22%7D){rel=""nofollow""}, or from a terminal: ```bash code --add-mcp '{"name":"faivelo","type":"http","url":"https://faivelo.com/api/mcp"}' ``` ## OpenAI Codex ```bash codex mcp add faivelo --url https://faivelo.com/api/mcp codex mcp login faivelo ``` ## Gemini CLI Extension with the MCP server and the skill: ```bash gemini extensions install https://github.com/ethannschwartz/faivelo-mcp ``` ## Windsurf Add to `~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`: ```json { "mcpServers": { "faivelo": { "serverUrl": "https://faivelo.com/api/mcp" } } } ``` ## Any agent that reads Agent Skills ```bash npx skills add ethannschwartz/faivelo-mcp ``` Installs the `faivelo-email` skill for whichever agents you have (Claude Code, Codex, Cursor, OpenCode and others). ## Agents with no browser Servers, CI and long-running agents can't click through a sign-in. Give them an **agent key** instead: create one in [Settings → Developers](https://faivelo.com/settings/developers){rel=""nofollow""} with kind *agent*, and send it as a header. ```json { "mcpServers": { "faivelo": { "url": "https://faivelo.com/api/mcp", "headers": { "Authorization": "Bearer fvl_live_..." } } } } ``` An agent key only reaches the mailboxes it created or was granted. It can't read your other inboxes, change domains or billing, or make more keys. See [AI agents & API keys](https://faivelo.com/docs/developers/ai-agents). ## SDKs ```bash npm install faivelo # Node.js and TypeScript pip install faivelo # Python ``` ## When the agent finishes Ask it to call `get_setup_summary`. It returns a short summary of what is set up, what is still waiting on DNS, and where to manage it, ready to paste into a README or send to a teammate. # API errors Every error from the REST API (`/api/v1`) and the partner API (`/api/partner`) has the same shape: ```json { "success": false, "error": "This API key is missing the required scope: mail:send", "code": "insufficient_scope", "fix": "Create a key that includes the \"mail:send\" scope at https://faivelo.com/settings/developers and use it instead; scopes cannot be added to an existing key.", "docs": "https://faivelo.com/docs/developers/errors#insufficient_scope", "statusCode": 403 } ``` | Field | Meaning | | ------------ | -------------------------------------------------------------------------------------------- | | `code` | Stable, machine-readable. Branch on this, never on the message text. | | `error` | What went wrong, in plain English. May include specifics such as the scope or address. | | `fix` | What to change before trying again. | | `docs` | A link to the code's entry on this page. | | `param` | The request field at fault. Only on `validation_error`, and only when one field is to blame. | | `statusCode` | The HTTP status, repeated for convenience. | Some errors carry extra fields, such as `requiredScope` on `insufficient_scope` and `retryAfter` (seconds) on `rate_limited`. A `429` also sets the `Retry-After` header. ::docs-aside{title="Retry or not?" type="tip"} Retry `429` after the wait it names, and `5xx` with backoff. Send the same `Idempotency-Key` on a retried send and it goes out at most once. Every `4xx` other than `429` fails the same way until the request or the account changes: read `fix` first. :: The SDK (`npm install faivelo`) throws these as `FaiveloError`, with the HTTP status in `statusCode` and the message in `message`. ## Authentication (401) ### `missing_api_key` `401` · Send the key as "Authorization: Bearer fvl\_live\_..." (or an "X-API-Key" header). Keys start with fvl\_live\_; a person on the account creates one at {rel=""nofollow""}. ### `invalid_api_key` `401` · The key is unknown or was revoked. Check it was copied in full, or create a new key at {rel=""nofollow""}. ### `api_key_expired` `401` · Create a new key at {rel=""nofollow""} and replace the expired one. ### `invalid_access_token` `401` · The OAuth access token (fvl\_oat\_...) is invalid, expired or revoked. Refresh it with your refresh token, or reconnect the app. ### `unauthorized` `401` · Authenticate with an API key in the Authorization header: "Bearer fvl\_live\_...". ## Billing (402) ### `plan_required` `402` · The account's plan does not include this. A person on the account can upgrade at {rel=""nofollow""}. ## Permission and account state (403) ### `insufficient_scope` `403` · The key does not carry the scope this endpoint needs (named in the error). Create a key with that scope at {rel=""nofollow""}; scopes cannot be added to an existing key. ### `partner_key_not_allowed` `403` · Partner keys only work on /api/partner/\* endpoints. Use an account or agent key (fvl\_live\_...) for /api/v1. ### `account_paused` `403` · The partner that manages this account paused it. The partner can resume it from the partner API or console. ### `account_suspended` `403` · Retrying will not help. The account owner should contact . ### `sending_paused` `403` · Sending is paused because recent mail bounced or was reported as spam. Retrying will not help; the account owner should read the email Faivelo sent them or contact . ### `send_limit_reached` `403` · The plan's monthly send allowance is used up. Wait for the next billing month or upgrade at {rel=""nofollow""}. ### `domain_not_on_account` `403` · Send from an address on a domain this account owns. List them with GET /api/v1/domains. ### `domain_not_verified` `403` · The sending domain has not passed DNS verification yet. Add the DNS records shown for it in the dashboard (GET /api/v1/domains/{domain} returns its status), then retry once it is verified. ### `shared_domain_phone_required` `403` · A person on the account must verify a phone number in the dashboard before this free address can send. ### `forbidden` `403` · The key is valid but not allowed to do this. Check the key kind and scopes, or use a key from the account that owns the resource. ## Request problems (400, 413) ### `validation_error` `400` · A field in the request is missing or has the wrong type or format (named in "param" when known). Correct it and resend; the API reference at {rel=""nofollow""} lists every field. ### `invalid_sender` `400` · Use a plain sender like "" or "Name " on a verified domain. ### `idempotency_key_invalid` `400` · Send an Idempotency-Key of 256 characters or fewer, derived from the event that triggered the send (an order id, not a timestamp). ### `invalid_request` `400` · The request was malformed. Check it against the API reference at {rel=""nofollow""}. ### `attachments_too_large` `413` · Keep attachments to 10 files and 10 MB in total (before base64), or send a link instead. ### `payload_too_large` `413` · Send a smaller request body. ## Not found (404) ### `mailbox_not_found` `404` · Use the full address (). GET /api/v1/mailboxes lists the mailboxes this key can reach; agent keys only see mailboxes they created or were granted. ### `domain_not_found` `404` · GET /api/v1/domains lists the domains on this account. Use the bare domain, e.g. "yourdomain.com". ### `alias_not_found` `404` · GET /api/v1/aliases lists the aliases on this account. ### `email_not_found` `404` · Use the "id" returned by POST /api/v1/emails. Ids belong to the account that sent the email. ### `template_not_found` `404` · Check the template alias in the dashboard under Transactional → Templates; aliases are case-sensitive. ### `not_found` `404` · The resource does not exist or this key cannot see it. Check the path against {rel=""nofollow""}. ## Conflicts and refused content (409, 422) ### `idempotency_in_progress` `409` · A request with the same Idempotency-Key is still running. Wait a few seconds and retry with the same key to get its result. ### `idempotency_key_reused` `422` · This Idempotency-Key was already used with a different request body. Use a new key for a new request. ### `template_paused` `409` · Resume the template in the dashboard under Transactional → Templates, or send inline html/text instead. ### `conflict` `409` · The resource is in a state that does not allow this. Read it again, then retry. ### `missing_template_variables` `422` · Pass every variable the template uses in "variables" (the missing names are in the error). Nothing was sent. ### `all_recipients_suppressed` `422` · Every recipient previously hard-bounced or reported spam, so nothing was sent. Remove them from the suppression list in the dashboard only if you are sure the address now works. ### `unprocessable` `422` · The request was understood but could not be completed. The error says why. ## Limits (429) ### `rate_limited` `429` · Too many requests for this key (120 per minute). Wait for the Retry-After header (seconds), then retry. ### `mailbox_creation_limit` `429` · A key may create 10 mailboxes per rolling 24 hours. Reuse an existing mailbox or try again tomorrow. ### `send_rate_limited` `429` · The plan's sending speed or daily volume is used up. The error says which limit and when it resets; wait that long, or split the recipients across several calls. ### `shared_domain_send_limit` `429` · Free shared addresses have a small daily send allowance. Wait until tomorrow, or send from your own domain on a paid plan. ## Server (5xx) ### `send_failed` `502` · The email could not be handed to the mail system. Retry with the same Idempotency-Key; it is safe and sends at most once. ### `internal_error` `500` · Something went wrong on our side. Retry with backoff; if it persists, email with the time of the request. # Billing & plans Faivelo pricing is based on **storage, not seats**. Every paid plan includes unlimited mailboxes and aliases — you pay for the space your mail takes up, and you can create as many addresses as your team needs. There's also a **Free** plan: email forwarding only, with unlimited aliases and a catch-all per domain across unlimited domains. It has no mailboxes, webmail, or campaign sending — it's what your account becomes after the trial if you don't subscribe. ## Plan comparison | | Starter | Growth | Pro | Business | | ------------------------------- | ----------- | ---------------- | ------------------ | ------------------ | | **Price** | $6/month | $12/month | $24/month | $49/month | | **Price (billed annually)** | $5/month | $10/month | $20/month | $40/month | | **Storage** | 10 GB | 200 GB | 1 TB | 2 TB | | **Domains** | Up to 3 | Unlimited | Unlimited | Unlimited | | **Mailboxes** | Unlimited | Unlimited | Unlimited | Unlimited | | **Transactional sends / month** | 3,000 | 20,000 | 50,000 | 100,000 | | **Transactional sends / day** | 300 | 2,000 | 5,000 | 10,000 | | **Marketing sends / month** | — | 3,000 | 25,000 | 100,000 | | **API sending rate** | 10/min | 60/min | 120/min | 240/min | | **Sending domains** | 1 | 1 | 3 | 10 | | **Reputation isolation** | Per account | Per account | Per sending domain | Per sending domain | | **Dedicated IP** | — | — | $30/month add-on | $30/month add-on | | **Developer API** | Included | Included | Included | Included | | **MCP (AI agents)** | — | Included | Included | Included | | **Webhooks** | — | — | Included | Included | | **Bookings (Calendello)** | — | Included | Included | Included | | **Booking-page branding** | — | Calendello badge | Calendello badge | Fully custom | **Growth** is our most popular plan. Storage is pooled across all your mailboxes and domains (on the TB tiers a single mailbox can use up to a quarter of the pool). You'll get a heads-up email when you reach 80% and again at 95%, so a full mailbox never sneaks up on you. Transactional and campaign sends are **separate budgets** — a newsletter can never eat into your app's password resets. Receiving is unlimited everywhere; *sending* domains are the ones you designate on the domain page, up to your plan's count. ### What's gated by plan - **The developer API** (REST) is included on **every paid plan** and sends to anyone: Starter includes 3,000 transactional sends a month, Growth 20,000, Pro 50,000 and Business 100,000, with a daily cap of a tenth of the month. The **hosted MCP server** for AI agents is included from **Growth**. Sending rate scales with the plan (10/60/120/240 recipients a minute); see [rate limits](https://faivelo.com/docs/developers/ai-agents#rate-limits). - **[Transactional email](https://faivelo.com/docs/transactional/overview)** — the send API and designed templates — is included on **every paid plan**; **delivery webhooks from Pro**. Every account can browse the Templates section. - **Campaigns** are included from **Growth** (3,000/month) and scale to 100,000 on Business, with per-campaign size caps (3,000 / 15,000 / 25,000). - **Reputation isolation and dedicated IPs.** On Pro and Business each sending domain carries its own reputation with our mail provider, so a problem on one domain never pauses another. A **dedicated IP** is a $30 a month add-on on those plans, switched on from the billing page; it is recommended above roughly 50,000 emails a month, since a dedicated IP that sends less cannot stay warm. - **Bookings (Calendello)** — Faivelo's scheduling product — is included from **Growth**, and previewable during the trial. Growth and Pro booking pages carry a small "Calendello by Faivelo" badge; **Business** unlocks a fully custom-branded booking page. ## The free trial Every new account starts with a **14-day free trial** of the Growth plan — no credit card required. The trial is fully functional with one guardrail: sending is capped at **100 emails**, since a brand-new domain shouldn't be sending at volume anyway (see [warm-up](https://faivelo.com/docs/sending/deliverability)). ### When the trial ends If you haven't subscribed by day 14, your account drops to the **Free plan** — email forwarding keeps working, but mailboxes, webmail, and campaign sending are turned off — and your mailbox data is **scheduled for deletion**. You'll receive a warning email first, and there's a grace period before anything is removed — subscribing at any point during that window keeps everything exactly as it was: domains, mailboxes, and mail. ::docs-aside{type="caution"} Don't ignore the deletion warning email. Once the grace period passes, mailbox data is permanently removed and can't be recovered. :: ## Upgrades and downgrades Manage your plan from the [Billing page](https://faivelo.com/billing){rel=""nofollow""}. - **Upgrades** take effect immediately. Billing is prorated, so you only pay the difference for the rest of the current period. Your new storage and sending limits apply right away. - **Downgrades** work the same way, with one check: you must be using **less storage than the target plan allows**. If you're on Pro using 300 GB, you'll need to get under 200 GB (delete old mail or unused mailboxes) before dropping to Growth. The billing page tells you exactly how much to free up. Dropping to Starter also requires having no more than 3 domains. ::docs-aside{type="note"} Downgrading also turns off the features the higher plan includes — dropping below Growth stops campaigns, MCP and booking pages and stops webhook creation, and dropping below Pro releases a dedicated IP. The REST API keeps working on every paid plan, at the lower tier's sending rate and allowance. :: ## Next steps - [Sending limits by plan](https://faivelo.com/docs/sending/limits) - [Open the billing page](https://faivelo.com/billing){rel=""nofollow""} # Security Email hosting means holding things that matter: your messages, your passwords, and API keys for your domain registrar. Here's concretely how Faivelo protects them — no hand-waving. ## Encryption at rest **Registrar API keys** (the Cloudflare, GoDaddy, Namecheap, or Route 53 credentials you provide for automatic DNS setup) are encrypted with **AES-256-GCM** before they're stored. They're decrypted only at the moment Faivelo talks to your registrar, and they're never shown back to you in the dashboard. **Mailbox passwords** are also AES-256-GCM encrypted at rest. They have to be encrypted rather than hashed because the mail server needs the real password to authenticate your email apps — which is why Faivelo shows a mailbox password **exactly once, at creation**. After that, nobody can read it out of the dashboard, including you. If it's lost, you reset it; you don't recover it. **Your account email address** is encrypted at rest as well, with a separate keyed hash used for login lookups — so even the address you sign in with isn't sitting in the database as plain text. ## Your account password Your Faivelo login password is **hashed with bcrypt (12 rounds)**, never encrypted and never stored in a recoverable form. Faivelo cannot read it, and a database leak would not reveal it. Password resets always issue a new one — there is no "email me my password." ## Sessions Signing in issues a signed session token stored in an **httpOnly cookie**. "httpOnly" means the browser withholds it from any JavaScript running on the page, so a script injected into your browser can't steal your session. The cookie is scoped to Faivelo and expires on its own. ## API keys Developer API keys are shown **once at creation**, then only an HMAC-SHA256 hash is stored — Faivelo can verify a key but can never display it again. Keys support: - **Scopes** — a key gets only the permissions you grant it. - **Mailbox restriction** — a key can be limited to specific mailboxes instead of your whole account, which is the right setup for AI agents and third-party tools. - **Expiry and revocation** — set an expiry date, see when each key was last used, and revoke any key instantly from [Settings → Developers](https://faivelo.com/settings/developers){rel=""nofollow""}. A revoked key stops working immediately. If a tool or agent you connected no longer needs access, revoke its key. That's the whole off-switch. ## Connected apps Apps you connect with OAuth — like [Claude via the MCP connector](https://faivelo.com/docs/developers/connect-claude) — never see a long-lived key at all. They get short-lived access tokens (about an hour) that rotate automatically, scoped to exactly the mailboxes you picked on the consent screen. Every connection is listed under [Settings → Connected apps](https://faivelo.com/settings/connected-apps){rel=""nofollow""}, and disconnecting one instantly revokes all of its tokens. ## Audit log Faivelo keeps a per-account audit log of significant actions — what was done, to what, from which IP address, and when. If something looks off in your account, there's a trail to check rather than guesswork. ## What you should do on your end Security is shared. The short list: 1. **Use a strong, unique password** for your Faivelo account — it's the key to everything else. 2. **Save mailbox passwords in a password manager** when they're shown at creation; they won't be shown again. 3. **Give API keys the narrowest scope that works**, and revoke keys you no longer use. 4. **Use registrar API tokens with limited permissions** where your registrar supports it (for example, a Cloudflare token scoped to DNS on one zone), rather than a global account key. ## Next steps - [Manage your API keys](https://faivelo.com/settings/developers){rel=""nofollow""} - [Billing & plans](https://faivelo.com/docs/billing/plans)