> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mail.ugmail.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Automate SaaS User Mailbox Provisioning with UGMail

> Automatically create a dedicated mailbox for every new user or team in your SaaS app using the UGMail Management API during your onboarding flow.

Many SaaS products need to give each new user or team their own email address — for transactional notifications, collaborative inboxes, or white-labeled email identities. Doing this manually doesn't scale, and most hosted email providers charge per-seat fees that become prohibitive as your user base grows. UGMail solves both problems: you provision mailboxes instantly via a single API call, with no per-user fees regardless of volume. This guide shows you how to call the UGMail API inside your onboarding flow so that every new user gets a ready-to-use mailbox the moment they sign up.

## Why use UGMail for SaaS provisioning

* **No per-user fees** — provision unlimited mailboxes under a flat plan without per-seat charges eating into your margins
* **Instant provisioning** — mailboxes are live within seconds of the API call, so there's no delay in your onboarding experience
* **Full API control** — create, update, and delete mailboxes programmatically without touching a dashboard
* **Standard protocols** — every provisioned mailbox works over SMTP and IMAP, so it integrates with any email client or library your users might choose

## Prerequisites

* Your domain(s) are [set up and DNS-verified](/guides/setup-domain) in UGMail
* A valid Bearer token stored as a server-side environment variable (`UGMAIL_TOKEN`)

<Steps>
  <Step title="Set up your domain in UGMail">
    Before you can provision mailboxes, the domain you want to use (e.g., `mail.yourapp.com`) must be registered in UGMail and have its MX, SPF, and DKIM records configured. Follow the [Set Up Your First Domain](/guides/setup-domain) guide to complete this one-time step.
  </Step>

  <Step title="Call the UGMail API in your onboarding webhook or trigger">
    Add a mailbox provisioning step to the server-side function or webhook that runs when a new user completes sign-up. The function below is a drop-in example you can adapt to your stack — it provisions the mailbox and returns the connection settings your application needs.

    ```javascript theme={null}
    async function provisionUserMailbox(userEmail, password) {
      const response = await fetch('https://mail.ugmail.co/api/principal', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.UGMAIL_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name: userEmail,
          type: 'individual',
          secrets: [password],
          emails: [userEmail]
        })
      });

      if (!response.ok) {
        throw new Error(`Provisioning failed: ${response.status}`);
      }

      return {
        email: userEmail,
        smtp: { host: 'mail.ugmail.co', port: 587, secure: false },
        imap: { host: 'mail.ugmail.co', port: 993, secure: true }
      };
    }
    ```

    Call this function from your sign-up handler, post-payment webhook, or any other trigger that marks a user as fully onboarded. The returned object contains everything the user or your application needs to start sending and receiving email.
  </Step>

  <Step title="Store the provisioned credentials securely">
    After provisioning, persist the mailbox credentials in your database alongside the user record. Store the password in encrypted form — never in plaintext. If your stack uses a secrets manager, you can store only a reference to the secret rather than the value itself.

    At minimum, record:

    * The provisioned email address
    * A reference to (or encrypted copy of) the password
    * The SMTP and IMAP connection settings

    This lets you display connection details to the user later, reset passwords on request, and deprovision the mailbox if the user closes their account.
  </Step>

  <Step title="Return connection settings to the new user">
    Surface the SMTP and IMAP settings in your post-onboarding UI so users can configure their email client or integrate their new mailbox into their own application. A clear connection settings screen reduces support requests significantly.

    | Protocol         | Host             | Port  | Security |
    | ---------------- | ---------------- | ----- | -------- |
    | SMTP (sending)   | `mail.ugmail.co` | `587` | STARTTLS |
    | IMAP (receiving) | `mail.ugmail.co` | `993` | SSL/TLS  |

    The username for both protocols is the full email address (e.g., `alice@yourapp.com`) and the password is the one you set during provisioning.
  </Step>
</Steps>

<Warning>
  Never expose your `UGMAIL_TOKEN` in client-side code, public repositories, or API responses. Treat it like a database password — store it as a server-side environment variable and rotate it if you suspect it has been compromised. Anyone with access to this token can create, modify, or delete all mailboxes and domains on your UGMail account.
</Warning>

<Tip>
  If you need to provision mailboxes in bulk — for example, when migrating an existing user base or onboarding an enterprise team — batch your requests and add a small delay between calls to avoid hitting rate limits. You can also parallelize with a concurrency limit (e.g., 10 requests at a time using `Promise.all` with a semaphore) to speed up large imports while staying well within safe thresholds.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Manage Aliases" icon="at" href="/guides/manage-aliases">
    Add team-level addresses like support@ that route to individual user inboxes.
  </Card>

  <Card title="Provision a Mailbox" icon="inbox" href="/guides/provision-mailbox">
    Explore all the options available when creating a single mailbox via the API.
  </Card>
</CardGroup>