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:

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:

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.

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:

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.

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

All paths are under https://faivelo.com/api/partner. Full request and response shapes are in the API reference.