Automate SaaS User Mailbox Provisioning with UGMail

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 in UGMail
A valid Bearer token stored as a server-side environment variable (UGMAIL_TOKEN)

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 guide to complete this one-time step.

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.

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.

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.

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.

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.

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.

Get Started

Core Concepts

Protocols

Guides

Security

Automate SaaS User Mailbox Provisioning with UGMail

Why use UGMail for SaaS provisioning

Prerequisites

Next steps

Manage Aliases

Provision a Mailbox

​Why use UGMail for SaaS provisioning

​Prerequisites

​Next steps

Manage Aliases

Provision a Mailbox

Why use UGMail for SaaS provisioning

Prerequisites

Next steps