mailgun clients

Mailgun Email Clients

The project uses three types of Mailgun clients for sending emails, each designed for specific use cases.

Client Types

1. SystemMailer (server/graphql/helpers/emails/SystemMailer.ts)

Used for system notifications from Toprent.app:

• Feedback notifications
• Operator birthday reminders
• Client greeting emails
• System errors and administrator notifications

Features:

• ❌ No branding - emails are sent without the ability to customize company logo or styles
• ❌ Fixed domain - cannot change sender domain (always no-reply@mg.toprent.app)
• ✅ Designed for simple system notifications without branding requirements

Methods:

• sendText(data) - send plain text email
• sendEmail(data) - send HTML email

Usage example:

import { systemMailer } from '@power-rent/server/graphql/helpers/emails/SystemMailer';

const mailer = new SystemMailer();
await mailer.sendEmail({
  to: 'user@example.com',
  subject: 'System Notification',
  html: '<p>Hello</p>',
  companyId: 'company-id',
});

2. ExternalMailer (server/graphql/helpers/emails/ExternalMailer.ts)

Used for client notifications to external users:

• Order notifications (creation, status changes)
• Check-in/check-out notifications
• Contract sending
• Delivery/collection notifications
• Login links
• Driver cancellation

Features:

• ✅ Branding support - allows passing branding variables (logo, colors, company domain) in email HTML content
• ✅ Domain customization - can use company domain in email content (links, logos)
• ✅ Designed for client emails with company branding capability

Methods:

• sendText(data) - send plain text email
• sendEmail(data) - send HTML email

Usage example:

import { externalMailer } from '@power-rent/server/graphql/helpers/emails/ExternalMailer';

const mailer = new ExternalMailer();
await mailer.sendEmail({
  to: 'client@example.com',
  subject: 'Order Update',
  html: '<p>Your order has been updated</p>',
  companyId: 'company-id',
});

3. BillionMailer (server/graphql/helpers/emails/BillionMailer.js)

Used for Billion marketplace integration and Mailgun template management:

• Billion account activation notifications
• Email address confirmation
• Rental start notifications
• Billion order notifications
• Mailgun template management

Methods:

• sendTemplate(data) - send email via Mailgun template
• sendText(data) - send plain text email
• sendEmail(data) - send HTML email
• getTemplateHTMLByName(name) - get template HTML
• getTemplateVersionByName(name) - get template version
• createTemplate(name, options) - create new template
• updateActiveTemplateByName(name, options) - update active template

Usage example with template:

import { billionMailer } from '@power-rent/server/graphql/helpers/emails/BillionMailer';

const mailer = new BillionMailer();
await mailer.sendTemplate({
  from: 'Toprent.app<no-reply@mg.toprent.app>',
  to: 'user@example.com',
  subject: 'Account Activated',
  templateName: 'billion-account-activated',
  variables: {
    name: 'John Doe',
    link: 'https://example.com',
  },
  companyId: 'company-id',
});

Common Parameters

All clients require mandatory companyId parameter in options for:

• Sending limit checks (6000 emails per month)
• Billing system reporting

Client Selection

Use SystemMailer if:

• Email is sent from Toprent.app system
• It’s a system notification or reminder
• It’s an internal notification for operators/administrators
• Company branding is not required and domain customization is not needed

Use ExternalMailer if:

• Email is sent to external client
• It’s an order or booking notification
• It’s a client service status notification
• Company branding is required (logo, colors, domain) in email content

Use BillionMailer if:

• Email is related to Billion marketplace integration
• Mailgun templates need to be used
• Template management is required (creation, update, retrieval)

Important Notes

1. All clients automatically check sending limits before sending emails
2. All sends are tracked in the billing system (cost: $0.001 per email)
3. All emails are sent from Toprent.app<no-reply@mg.toprent.app> (technically, but ExternalMailer can use company domain in content)
4. BillionMailer uses singleton pattern - one instance is created per application
5. Difference between SystemMailer and ExternalMailer: SystemMailer does not support branding and domain customization, unlike ExternalMailer which can use company branding variables in HTML content

Future Improvements

Mailgun Replaceability

It would be beneficial to make Mailgun a replaceable provider, allowing switching to another provider when issues occur (outage) or for other reasons. This would improve the reliability of the email sending system.

Potential fallback provider:

• Inbound.new - can be used as a backup provider for email sending

To implement such functionality, it is recommended to:

1. Create an abstraction over email providers (Email Provider Interface)
2. Implement adapters for each provider (Mailgun, Inbound.new, etc.)
3. Add an automatic switching mechanism when the primary provider fails
4. Maintain a unified interface for all Mailer classes (SystemMailer, ExternalMailer, BillionMailer)