Importing Mailboxes in Bulk

When you are setting up email for a whole team at once, the Import screen lets you paste a list of addresses and create every mailbox in one pass instead of running the new-mailbox wizard over and over.

This is about creating the mailboxes themselves. Moving the existing messages across from your old provider is a separate step covered in Migrating to Kapsule, and the two are usually done together: import the addresses first, then run the mail migration into them.

Before You Start

The domain has to be verified before you can add mailboxes to it. If it is not, each row is rejected with "Verify ownership of {domain} before adding mailboxes." Verification is a TXT record you publish on the domain, shown on the Deliverability tab of any mailbox at that domain. Domains registered through Kapsule are on our DNS already, so the record can be published for you.

You also need enough mailbox capacity on your plan. Each email plan grants a number of mailboxes, and the import creates real mailboxes that count against that number. If you are importing more addresses than your plan covers, upgrade first: see Upgrading Your Plan.

Importing requires the Owner or Admin role on the account.

Opening the Import Screen

Sign in to KPanel and click Email in the left sidebar.
Click Import in the header.

The page is titled "Import mailboxes" and works in two steps: 1 - Paste the list, then 2 - Review and import.

Import mailboxes screen in KPanel

The List Format

One mailbox per line. The simplest possible list is just addresses:

sarah@yourdomain.com
tom@yourdomain.com
accounts@yourdomain.com

Each line can also be a CSV row with up to four fields, in this order:

email, password, name, quota

email is the only required field.
password is optional. Leave it blank and a strong one is generated for you.
name is the display name shown on outgoing mail.
quota is in megabytes and must be digits only.

A fully specified row looks like this:

sarah@yourdomain.com, , Sarah Nguyen, 10240
tom@yourdomain.com, , Tom Blake, 10240

Any row that omits a quota gets the standard 10 GB mailbox. Any password shorter than eight characters is replaced with a generated one.

The import creates at most 200 mailboxes per run. The paste box warns you when you go over and the import button disables, and the server refuses anything larger with "At most 200 mailboxes per import." Split a bigger list into batches of 200.

Reviewing and Importing

Move to step two and check the parsed list before committing. Each row appears with the address it resolved to, so a stray comma or a wrapped line is obvious before you create anything.

Click the import button and each row is processed independently. Rows come back marked Created or Failed with a reason, so one bad address does not stop the rest of the batch.

Generated passwords are shown once and never again. Each created row has a Reveal one-time password control. Copy them into your password manager before you leave the page. If you lose one, you are not locked out permanently, but you will have to reset it from the mailbox's Password tab.

The footer note says it plainly: "Mailboxes provision in the background. Generated passwords are shown once, copy them now."

What Happens Next

Provisioning runs in the background and normally takes seconds. Open Email and the new mailboxes appear in the list with a status pill: Provisioning while they are being created, then Active.

Once a mailbox is Active, hand the user their address and password and point them at Setting Up Your Mailbox. The connection settings are on the mailbox's Setup tab and are the same for every mailbox on the platform, so you can send one set of instructions to the whole team.

Common Rejection Reasons

Each failed row tells you why. The reasons you will actually hit are:

Invalid email format. Usually a stray character, a missing @, or a wrapped line from a spreadsheet paste.
Verify ownership of {domain} before adding mailboxes. The domain has not passed the ownership check yet.
Already in use. There is already a mailbox, alias, forwarder or shared inbox on that address.
A Kapsule staging subdomain was used. Mailboxes go on your own domain, not a temporary hosting address.

Export your existing mailbox list from your old provider to CSV, open it in a spreadsheet, delete every column except the address and the display name, and paste the result straight into the box. The parser handles the comma separation, so there is nothing to reformat.

Moving the Existing Mail Across

Creating the mailbox gives you an empty inbox. To bring across the message history, run an email migration, which connects to your old provider over IMAP and copies folders and messages into the new mailboxes.

Start it from Email, then Migrate from another host. You will need the source host name and, for each mailbox, the source address and its password. Many providers require an app password rather than the account password for this, and the wizard tells you which ones and how to generate it.

Source passwords are encrypted at rest and wiped automatically once the migration completes, and message contents are never logged. Full detail is in Migrating to Kapsule.

Run the import first and the migration second. The migration needs the destination mailboxes to exist.

Troubleshooting

Every row failed with a domain verification error. Publish the TXT record shown on the Deliverability tab of any mailbox at that domain, then click Verify. If you have no mailbox at that domain yet, create the first one through the normal wizard, which walks you through verification.

Some rows created and some failed. That is by design: rows are independent. Fix the failed ones and re-run the import with just those lines. Re-importing an address that already exists fails harmlessly with "Already in use."

A mailbox is stuck on Provisioning. Open the mailbox and give it a moment; the page polls and updates itself. If it is still not Active after a few minutes, check the Activity tab on the mailbox for the provisioning history, then open a support ticket with the address.

I pasted 400 lines and only got 200. The cap is 200 per import. Split the list.

I do not want generated passwords. Supply your own in the second field of each row. Anything shorter than eight characters is replaced, so use something substantial.