Mailcow

Mailcow Domain Admin ExtensionCopy Anchor Link

Your new Mailcow integration lets Paymenter automatically create a domain inside Mailcow, hand over a dedicated domain-admin account to the customer, and keep the service lifecycle (create, suspend, terminate, upgrade) in sync. This guide walks both administrators and end users through the essentials—no code knowledge needed.

---

1. What the extension doesCopy Anchor Link

When a product using this server extension is provisioned, Paymenter will:

1. Create the customer’s domain in Mailcow with the limits you define.
2. Generate a domain-admin user and secure password for that domain.
3. Save the login details so the user can view them inside the client portal.
4. Send a polished welcome email (if email delivery is configured) with the control-panel link.

Later on, Paymenter can suspend/unsuspend the domain, adjust limits, or fully remove it—all through the Mailcow API.

---

2. Administrator setupCopy Anchor Link

PrerequisitesCopy Anchor Link

• A working Mailcow (dockerized) installation accessible over HTTPS.
• A Mailcow read-write API key created under Configuration → Access → API.
• Optional: Mail routing configured so Paymenter can send emails (SMTP settings under Admin → Settings → Mail).

Step-by-stepCopy Anchor Link

1. Install the extension
   Upload the “Mailcow Domain Admin” server extension to your Paymenter instance if it is not already present (the repository layout expects it under extensions/Servers/Mailcow).
2. Create a server in Paymenter
   • Navigate to Admin → Products → Servers → New.
   • Choose the “Mailcow Domain Admin” extension.
   • Fill in:
     • Mailcow Base URL – e.g. https://mail.example.com
     • API Key – your Mailcow read-write key
     • License Key – paste the license key you received with your purchase (%%__Mailcow_paymenter_License__%% is the placeholder). The extension validates this key online, so make sure outbound HTTPS is allowed.
     • Verify TLS certificates – keep this enabled unless you must use a self-signed certificate.
3. Wire the server to products
   • Create (or edit) a product in Paymenter and assign the Mailcow server to it.
   • Configure product-level limits:
     • Mailbox cap
     • Default / maximum per-mailbox quota (in MiB)
     • Total domain quota
     • Optional alias limit
     • Optional outbound rate limit (messages per second/minute/hour/day)
4. Test the connection
   Use the “Test Connection” button on the server configuration page—Paymenter will confirm the API credentials by calling Mailcow.
5. Enable email notifications (optional but recommended)
   If Paymenter can send mail, the extension will automatically email the customer their domain-admin credentials using the default header/footer you’ve configured.

---

3. Service lifecycle in plain termsCopy Anchor Link

---

4. Admin checklist when something looks offCopy Anchor Link

• Domain not created?
  Double-check the Mailcow API key permissions, confirm the license key is valid, and ensure the product collected a domain name at checkout.
• Emails not arriving?
  Verify Paymenter’s SMTP configuration and check storage/logs/laravel-*.log for mail delivery errors.
• License errors in the log?
  The extension refuses to provision if the License check fails. Confirm that the key hasn’t exceeded its activation limits.
• Token or login issues?
  The client area shows the stored username/password. Ask the customer to reset the password inside Mailcow if they lose it.
• Service termination fails?
  Look for error details in the Laravel log—the order of deletion is already handled automatically (mailboxes → aliases → domain).

---

5. Customer experience (share this with end users)Copy Anchor Link

1. Provisioning confirmation
   Shortly after purchase your service appears under My Services in the Paymenter client area. An email (if enabled) also shares the Mailcow login details.
2. Viewing credentials manually
   • Log in to Paymenter.
   • Open Services → (Your Mailcow service).
   • The page lists:
     • Domain Admin Username
     • Domain Admin Password
     • A button labelled “Open Mailcow Control Panel” linking to https://mail.example.com/domainadmin.
3. First login tips
   • Use the credentials exactly as shown (they are case-sensitive).
   • After logging in, change the password to something memorable.
   • Navigate to “Mailboxes” in Mailcow to create, edit, or delete mailboxes and aliases within your domain.
4. When to contact support
   • You can’t log in even with the provided credentials.
   • You need higher limits than your plan allows.
   • You suspect suspicious activity on your domain.
     Use your provider’s ticket system (Support → Open Ticket) and mention your domain name for faster help.

---

6. FAQCopy Anchor Link

Do customers get full Mailcow admin access?
No. They receive a domain-admin login scoped strictly to their domain. They cannot see other domains or server-wide settings.

Can customers reset their password themselves?
Yes. Inside Mailcow, domain admins can change their own password. If they lose access entirely, the Paymenter administrator can regenerate a password by updating the service properties or re-provisioning.

Is single sign-on available?
Not in this minimal release. Customers log in with the stored username and password. (You can add SSO later if needed.)

How are rate limits enforced?
If enabled on the product, outgoing messages are capped per selected time window (second/minute/hour/day) using Mailcow’s built-in throttling.

---

7. Updating or removing the extensionCopy Anchor Link

1. Back up your Paymenter instance (files + database).
2. Replace the extension files under extensions/Servers/Mailcow as needed.
3. Clear application cache if you deploy code changes (php artisan cache:clear).
4. Removing the extension will stop new provisioning, but existing services remain until you terminate them manually.

---

With this guide, both administrators and customers can work confidently with the Mailcow Domain Admin extension—no developer jargon required. Happy hosting!

---