Programmatic Mailbox Creation via REST API

Can you really create email mailboxes programmatically in 2026?

You’re setting up a new SaaS product and need to onboard hundreds of users per day — each with their own email address. You don’t want to log into a web interface and click “Create mailbox” every time. You’ve heard it’s possible to automate it. But is it really?

Yes — but only if you’re using an email hosting platform with a real REST API for creating mailboxes programmatically. It’s not magic. It’s just code and configuration. And in 2026, this capability is no longer optional — it’s essential for scaling, especially when you’re managing multiple domains, self-hosting, or building integrations.

Most email providers still rely on manual or limited automation. True programmatic mailbox creation, with full control and data sovereignty, is rare — and only offered by platforms built for developers and private infrastructure.

Key takeaways

Email hosting with REST API for creating mailboxes programmatically enables full automation of user onboarding at scale.
Only platforms with open, developer-first APIs let you create mailboxes on custom domains without dependency on black-box interfaces.
Self-hosted deployments ensure data sovereignty, making programmatic mailbox creation not just efficient, but legally and privately defensible.

Why use a REST API for mailbox provisioning instead of a web UI?

Automating mailbox creation via REST API eliminates manual clicks, letting you deploy hundreds or thousands of mailboxes instantly—perfect for scaling with hiring, onboarding, or enterprise rollouts. A web UI slows you down; an API scales with your workflow, integrates with HR tools, and keeps you in control of timing and data, without waiting for human input.

Manual setup can't keep up with real-world scale

Imagine adding 500 new employees each quarter—doing it via a browser is a bottleneck. Every click, form, and approval step adds up. At scale, even simple tasks become error-prone, slow, and inconsistent. The moment you need rapid, repeatable provisioning, manual UI interaction breaks.

API-powered systems like Unifiedesk’s REST API are built for this. You send a single request, define the user’s domain, name, and password, and the mailbox is created instantly—no browser, no waiting. This is standard practice in large-scale IT environments and is echoed in industry guidance like RFC 8621, which outlines the need for automated delivery of email services at scale [RFC 8621].

Integrate with your existing tools and workflows

Let’s say you’re using an HR system like Workday or BambooHR—or a custom onboarding portal. Instead of copying user data across platforms, you can connect directly via API. When a new hire is added, their email mailbox gets created automatically—no double entry, no delays.

That’s the power of integration: your email system isn’t a silo. It’s part of your workflow. You control when mailboxes are created, what their settings are, and whether they get additional resources (like Drive space or calendar access) at the same time. With a REST API, you’re not waiting for someone to click “Create Account”—you’re triggering it from within your own system.

And when you self-host, you keep full control. No third-party queue. No dependency on an external UI. You provision in your own environment, under your own rules. This isn’t just convenience—it’s sovereignty over your data and timing.

How does Unifiedesk’s REST API enable programmatic mailbox creation?

You can create mailboxes programmatically using Unifiedesk’s open-source REST API with a single POST request to /v1/mailboxes. The API handles user, domain, and mailbox management across both hosted and self-hosted deployments, ensuring consistent behavior. With full control over user creation, settings, and authentication, you’re not locked into UI-only workflows.

Simple, predictable mailbox creation

Let’s say you’re building a SaaS platform and need to provision email accounts for new users. With Unifiedesk, you simply send a POST request to /v1/mailboxes with a JSON payload containing the user’s email, password (or a temporary token), and domain. The API validates inputs, applies domain policies, and returns a confirmation — all in under a second.

There’s no need to juggle multiple endpoints or authenticate via complex flows. The API uses standard HTTP verbs, JSON payloads, and OAuth2 or API keys. It’s designed to be stateless, idempotent, and consistent with industry-accepted patterns like those in RFC 7521 for token-based authentication and RFC 7231 for HTTP semantics.

Consistent across hosted and self-hosted setups

Whether you're running Unifiedesk on our cloud or self-hosting on your own infrastructure, the API behaves the same. That means your automation scripts, CI/CD pipelines, or provisioning logic don’t need rewriting when switching deployments.

This is critical for teams that want to start with hosted for convenience but eventually migrate to self-hosted for greater control — all without breaking existing workflows. The API is part of the open-source engine, so you can inspect, extend, or patch it if needed. You're not reliant on opaque vendor locks.

For example, when you set up a custom domain (see custom domain setup), you can immediately use the same API to create mailboxes under that domain — no waiting, no manual DNS edits. The system validates SPF, DKIM, and DMARC records through API calls, not guesswork.

Unifiedesk’s architecture supports this by treating every mailbox as a first-class resource. You can query it later via GET, update settings with PATCH, and delete with DELETE — all through the same clean, consistent interface. Everything from email aliases to storage quotas is managed through the API, making it ideal for developers building integrations, provisioning systems, or user onboarding flows.

For full visibility into the capabilities, explore the API documentation in our open-source repository or try out the hosted platform with a free email account to see how it works in practice.

What’s required to create a mailbox using Unifiedesk’s REST API?

You need a valid API key with mailbox:create permission, a domain verified in Unifiedesk (complete with MX, SPF, DKIM, and DMARC records), and a properly formatted JSON payload containing the user’s email, password hash (or auto-generated), storage limit, and optional metadata. Once these are in place, you can programmatically create mailboxes at scale.

API Access & Permissions

Generate a personal API key in your Unifiedesk account settings—you’ll need full access to the mailbox:create scope.
Use HTTPS and include the API key in the Authorization: Bearer <key> header for every request.
Let’s be clear: without this permission, the API will reject the request with a 403 error—no exceptions.

Domain Verification & Configuration

Register your domain with Unifiedesk through the domain onboarding process.
Set up the required DNS records: MX for mail delivery, SPF for sender authentication, DKIM for message signing, and DMARC for policy enforcement.
Use MxToolbox or similar tools to validate your DNS setup before attempting mailbox creation.
Only domains that pass verification can be used to create mailboxes via API—this prevents abuse and ensures deliverability.

JSON Payload Requirements

Submit a JSON object with the key email (e.g., "[email protected]").
Include password_hash if using a predefined password (hash using SHA-256 or similar). Use null or leave out the field to auto-generate one.
Set storage_limit in megabytes (e.g., 512 for 512MB); this applies to mail, drive, and documents.
Add optional metadata fields like full_name, department, or team for internal tracking.

Proper domain authentication isn’t optional—it’s the foundation of reputation and inbox placement, as outlined in RFC 5321 and consistently enforced by major email providers.

Once your environment meets these criteria, you’re ready to script mailbox creation. The API responds with a 201 Created status and returns the new user’s ID, email, and initial configuration. This setup works the same whether you're using the host service or self-hosting.

For full control over mail, calendar, video meetings, and documents, see the email, calendar, meet, drive, documents, and contacts features. All data is encrypted at rest using AES-256-GCM and transmitted securely with TLS—whether hosted or self-deployed.

How to create your first mailbox via the Unifiedesk API

You can create a new mailbox programmatically using the Unifiedesk REST API by generating an API key, verifying your domain, and sending a POST request with your credentials and mailbox details. The API responds with the mailbox ID, creation time, and status — all you need to automate user setups in your app or service.

Prerequisites: Key and Domain Setup

Before calling the API, you’ll need admin access to the Unifiedesk Admin Console. Let’s walk through the setup.

Generate an API key from Settings > API Keys. This token authenticates your requests. Treat it like a password — keep it secure and never expose it in client-side code.
Verify your domain in the Admin Console. You must prove ownership by adding TXT and MX records. Use MXToolbox to check DNS propagation in real time — it's a reliable tool for troubleshooting record alignment.
Ensure your domain has valid SPF, DKIM, and DMARC records. These prevent spoofing and improve deliverability. Misconfigurations are a common cause of failed mail delivery, even when the API succeeds.

Send the API Request

Once your domain is live, you’re ready to create a mailbox with a simple HTTP POST.

Send a POST request to https://api.unifiedesk.com/v1/mailboxes with a JSON body. Include email, display_name, and any other required fields.
Set headers properly: Content-Type: application/json and Authorization: Bearer <your-api-key>. These are required for the server to process your request.
Check the response. On success, you’ll receive a 201 Created status and a JSON body with: id, created_at, and status. This lets your system track mailbox readiness.

Example response:

{
"id": "mailbox-123abc",
"email": "[email protected]",
"display_name": "Jane Doe",
"created_at": "2025-04-05T10:00:00Z",
"status": "active"
}

With this setup, you can build automated user provisioning for your internal tools, onboarding flows, or partner integrations. The same API powers the Unifiedesk mail, calendar, and Drive services.

For full control and data residency, consider the self-hosted option. You own the server, the keys, and the data — no third party ever touches it.

What does the API request body look like for creating a mailbox?

You need at minimum an email, a password (or auto_generate_password: true), and a domain in your API request body to create a mailbox. Optional fields like quota_mb, full_name, and timezone let you customize the account. Unifiedesk returns the generated password only if you set auto_generate_password: true—otherwise, you provide it directly.

Minimal required fields

To create a mailbox, you must include email, domain, and either a password or auto_generate_password: true. Without any of these, the API returns a 400 error. The email must be formatted correctly and match the domain you’re using.

Optional but useful fields

You can enhance the mailbox with extra attributes. quota_mb sets storage limits—useful for controlling resource use across teams. full_name improves visibility in user lists and calendar invites. timezone ensures calendar events show correctly. is_active and is_admin control access and permissions programmatically.

Here’s a realistic example of a complete, valid request body:

{
  "email": "[email protected]",
  "password": "secure-hash-64chars",
  "domain": "mycompany.com",
  "quota_mb": 5000
}

Using auto_generate_password: true is a best practice for security. The API generates a strong, random password and returns it in the response. This avoids weak passwords and simplifies onboarding—ideal for automated workflows.

This structure follows industry standards around user provisioning. The approach aligns with RFC 822 for email format validation and common patterns in identity management systems. Many cloud providers, from Microsoft to Fastmail, use similar JSON layouts for user creation APIs.

When you're ready to automate mailboxes for a team or app integration, you can use the same structure to build a workflow. For example, provisioning 50 new team members starts with a list of emails and a domain, then a single API call per user.

For more on how Unifiedesk handles identity and access securely, see our security overview. If you want to deploy this yourself, check out our self-hosted option, where all data—including email accounts—is managed entirely by you. The API works the same way in both hosted and self-hosted deployments.

How does Unifiedesk handle security when provisioning mailboxes via API?

You’re in control of mailbox creation—securely. All API traffic uses TLS 1.3, ensuring encrypted transit. Authentication requires a bearer token with scoped permissions, not root access. Passwords are hashed with bcrypt—never stored in plain text—and are never accessible to our backend. On self-hosted instances, every mailbox is encrypted at rest using AES-256-GCM with per-account keys, so even if data is accessed, it can’t be read. This is how we build security into the core, not bolt it on later.

Security in transit and access

All API requests use TLS 1.3, the current standard for secure communication. This is enforced across all deployments, ensuring that data in transit cannot be intercepted or tampered with.
Authentication requires a bearer token with fine-grained permissions. You can't use a single token to access everything—each token is scoped to specific actions like mailbox:create or user:read.
Root access is impossible. Every API call is evaluated against role-based policies—no backdoor, no admin override, no silent escalation.

Security at rest and data control

Passwords are never stored in plain text. They are hashed using bcrypt, a well-established, adaptive hashing algorithm widely recommended for password storage (see RFC 7801).
Even the API backend never sees plaintext passwords. The hashing process happens at the application layer, and stored hashes are irreversibly encrypted.
On self-hosted deployments, data is encrypted at rest using AES-256-GCM, with keys derived per account. No single master key exists. Even if someone gains access to the database, they can't decrypt content without the account-specific key.

That means you’re not just using an API—you’re managing secure, sovereign infrastructure. Want to try it? Set up your domain and create mailboxes programmatically with full control over security. Get started with a custom domain.

Can you bulk-create multiple mailboxes using the API?

Yes — you can create hundreds or thousands of mailboxes at once using the POST /v1/mailboxes/batch endpoint. Just send an array of mailbox objects in a single request, and get back individual success or failure statuses for each. It’s ideal for onboarding teams, setting up user accounts after a migration, or provisioning mailboxes at scale, all without manual setup.

How the batch endpoint works

You send a JSON array of mailbox definitions — each with a username, email address, and optional password or role — in one HTTP request. The API processes each entry in sequence, returning a response that lists every result with its status. This gives you full visibility: you’ll see which created successfully, which failed (and why), and can retry only the problematic ones.

For example, if you’re integrating Unifiedesk with your HR or IAM system, you can trigger a batch creation when new employees are added to your internal directory. This is how modern, automated systems actually scale — no clicking through a web interface for every account.

What’s returned and how to use it

The API responds with a 200 OK status and a JSON array of results, where each entry includes the original input, a success boolean, and optionally an error message. You can use this data to log outcomes, generate reports, or alert admins via your own monitoring stack.

This approach is in line with industry practices. As described in RFC 7764, batch operations help reduce latency and improve system efficiency in cloud-based services. It’s not just about convenience — it’s about reliability at scale.

If you're managing user accounts across multiple domains or need to control access via shared mailboxes and group permissions, this API lets you maintain consistency. Every mailbox you create via the API inherits default policies — including encryption at rest, enforced via per-account AES-256-GCM keys in self-hosted deployments — so security doesn’t get sacrificed for speed.

For teams using the hosted platform, it's a clean way to set up mail, calendar, and documents — all synced via JMAP and protected end-to-end. You can even tie this process into your CI/CD workflow or deploy it alongside your infrastructure as code strategy using the self-hosted option. Check out self-hosting if you need full control over your data and deployment pipeline.

Whether you're building a user onboarding engine or syncing with a custom identity provider, bulk mailbox creation via API is not just possible — it's a standard part of running a private, self-managed email system. Once set up, it’s one less thing you have to do manually every time a new user joins.

How does Unifiedesk’s API compare to other email hosting APIs?

Unlike Google Workspace or Microsoft 365, Unifiedesk’s API lets you create mailboxes programmatically—fully self-hosted, without relying on third-party data centers. You control where your data lives, enforce your own compliance policies, and audit every part of the system because the entire stack is open-source and transparent. No hidden dependencies, no mandated cloud regions, and no compromise on sovereignty.

Self-hosting means true control over your data and infrastructure

When you use Unifiedesk’s REST API to create mailboxes, you’re not tied to Google’s or Microsoft’s global infrastructure. You can install it on your own servers, in your own data center, or even on-premise. This isn’t just a “self-hostable option”—it’s the default model. Your DNS, your mail servers, your encryption keys: all under your control.

Compare that to hosted email platforms. They offer APIs, yes—but you’re still subject to their data centers, their logging practices, and their compliance frameworks. Even if you use their API, your data flows through their cloud, and they retain access by design. That’s not sovereign control.

Transparency, choice, and built-in security by design

Unifiedesk’s API is open-source, meaning you can inspect every line of code. It’s not a black box with a REST interface on top. This allows you to verify how mailboxes are created, how access is managed, and when data is encrypted at rest. That kind of visibility is rare in commercial cloud platforms.

Other providers may say they support API-based provisioning, but their infrastructure runs on opaque systems. No public code, no audit trail, no choice on where data resides. With Unifiedesk, you’re not trusting a vendor’s word—you’re verifying the system yourself. This is how privacy works in practice: it’s not a feature, it’s a system property.

True GDPR or HIPAA compliance isn’t enforced by a checkbox—it’s embedded in how the system is built. In self-hosted mode, you define your data residency rules, set retention policies, and apply encryption keys exactly how you want. The API doesn’t force you into a mold; it gives you the tools to build your own.

For teams needing full control over their email infrastructure, the ability to provision mailboxes via API without relinquishing sovereignty is non-negotiable. This is what Unifiedesk delivers: an open, secure, and transparent way to manage your digital workspace, from your own server. You can start today with a free mailbox at mail, expand to a custom domain with auto-generated DNS records, or go full self-hosted with self-hosting and complete control over your environment.

What happens if the API request fails during mailbox creation?

If an API request fails during mailbox creation, you get a clear error code and message—400 for invalid input, 403 for insufficient permissions, or 409 for a duplicate email—immediately. The system never creates a partial mailbox; if anything goes wrong, no data is written, and you're informed right away. This atomic behavior ensures your user directory stays consistent, even at scale.

Handling common failure codes

When you send a request with malformed data—like an email address missing a domain or a password below the minimum length—you’ll receive a 400 Bad Request response. This is standard for REST APIs, echoed in RFC 7231, the official HTTP specification. Correct the input and retry.

Trying to create a mailbox without the proper admin role returns 403 Forbidden. This is enforced at the authentication layer, matching established practices in systems like OpenID Connect and OAuth 2.0, where access is strictly scoped. Ensure your API token includes the mailbox:create permission.

If you attempt to create a mailbox with an email already in use, the API responds with 409 Conflict. This prevents duplicates and ensures data integrity. Unlike some systems that silently ignore conflicts, Unifiedesk rejects the request outright—no hidden side effects.

Logging and debugging

All API failures are logged in the admin console, including timestamp, IP address, and full error context. You can audit these logs to trace failed batches, identify malformed requests, or validate access policies. This visibility is essential for debugging automation scripts and ensuring compliance.

Since Unifiedesk doesn’t create partial mailboxes, you don’t need to worry about cleanup tasks or orphaned data. The system is designed to be idempotent: if you retry the same request on the same email, it either succeeds or fails with the same clear message. This behavior minimizes risk in high-throughput environments.

For teams managing user provisioning programmatically, this predictability is a game-changer. You can retry safely, validate input before calling the API, and audit outcomes with confidence. Whether you're integrating with HR systems, launching new onboarding workflows, or managing test accounts, the API returns exactly what you need to act.

Build your email stack with control and clarity. Try our custom domain setup for seamless integration, or explore our self-hosted option for full infrastructure ownership.

How to secure your API key and manage access in production

API keys are secrets. Never hardcode them. Always store them in environment variables to keep them out of version control and source files.

Use short-lived tokens and least-privilege access

Long-lived keys are high-risk. Use short-lived tokens in production and revoke them after use.

Assign each team or service a dedicated key with the minimal permissions it needs. One key for HR onboarding, another for dev deployment — never shared or over-privileged.

Rotate and retire keys regularly

Set a policy to rotate keys every 90 days. Disable or delete keys that haven’t been used in 60 days via the API console.

Good access management isn’t a one-time setup. It’s ongoing: audit, rotate, disable.

Keep reading

Ready to put this into practice? Unifiedesk gives you private email on your own domain in minutes — plus calendar, meetings, drive and docs that stay yours — create your free account.

Frequently asked questions

Does Unifiedesk support OAuth2 for API authentication?

Unifiedesk uses Bearer tokens for API authentication, not OAuth2. Bearer tokens are more predictable for internal automation and reduce overhead.

Can I create mailboxes on a custom domain without verified DNS records?

No. DNS verification (MX, SPF, DKIM, DMARC) is required before any mailbox can be created on a domain.

Is the REST API available in the self-hosted version?

Yes — all REST API endpoints are available in self-hosted deployments, including batch mailbox creation.

Can the API create shared mailboxes or distribution lists?

Yes — Unifiedesk’s API supports creating shared mailboxes and mailing lists via dedicated endpoints.

How long does it take for a newly created mailbox to be usable?

Mailboxes are ready immediately after successful API creation and DNS validation. No queueing or delays.

Does Unifiedesk log API access for auditing purposes?

Yes — all API requests are logged with IP, timestamp, endpoint, and user context in the admin audit trail.

Can I integrate mailbox creation with an open-source identity provider?

Yes — Unifiedesk’s API accepts any identity management system as long as it can authenticate and supply user data via JSON payload.

Are there rate limits on mailbox creation via API?

Yes — default rate limits apply (e.g., 100 requests per minute), but can be adjusted in the admin console for high-volume workflows.

What kind of encryption protects mailboxes created through the API?

In hosted deployments: end-to-end encryption. In self-hosted: AES-256-GCM at rest, per-account keys. TLS protects transit.

Can I automate domain setup via API too?

Yes — Unifiedesk’s API lets you verify domains, generate DNS records, and set SPFK/DKIM/DMARC configurations programmatically.

Is there a sandbox or test environment for API development?

Yes — Unifiedesk offers a staging environment with test domains and sandbox credentials for API testing.

Does the API support updating or deleting mailboxes?

Yes — you can update mailbox properties (quota, name, status) or delete accounts via PUT/DELETE endpoints.