Skip to main content

Mailjet Integration with OmniCRM

OmniCRM integrates with Mailjet to manage all email communication with customers and staff, ensuring professional, branded, and reliable email delivery for both transactional emails and marketing campaigns.

Overview​

The Mailjet integration provides:

  • Automated Transactional Emails - Password resets, invoices, welcome emails, notifications
  • Contact Syncing - Customer contacts automatically synced to Mailjet for campaigns
  • Email Templates - 10+ pre-configured email types with customizable Mailjet templates
  • Marketing Campaigns - Segmented email campaigns based on customer data
  • Reliable Delivery - Professional email infrastructure with tracking and analytics

Configuration​

Mailjet is configured in OmniCRM-API/crm_config.yaml under the mailjet section.

Basic Configuration​

mailjet:
  api_key: your_mailjet_api_key
  api_secret: your_mailjet_api_secret

Obtaining API Credentials:

  1. Create account at <https://www.mailjet.com>
  2. Navigate to Account Settings → API Keys
  3. Copy API Key and Secret Key
  4. Paste into crm_config.yaml

Email Template Configuration​

OmniCRM uses 10 distinct email template types for automated communications. Each template is configured with:

  • from_email - Sender email address
  • from_name - Sender display name
  • template_id - Mailjet template ID (numeric)
  • subject - Email subject line

Template Types and Configuration​

Customer Welcome Email​

Sent when a new customer account is created.

api_crmCommunicationCustomerWelcome:
  from_email: "support@yourcompany.com"
  from_name: "Your Company Support"
  template_id: 5977509
  subject: "Welcome to Your Company"

When Sent:

  • New customer signs up via Self-Care portal
  • Staff creates new customer account
  • Customer activates service for first time

Template Variables Available:

  • {{ var:customer_name }} - Customer's full name
  • {{ var:email }} - Customer's email address
  • {{ var:company_name }} - Your company name
  • {{ var:login_url }} - Link to Self-Care portal
  • {{ var:support_url }} - Link to support page

Customer Invoice Email​

Sent when an invoice is generated and ready for payment.

api_crmCommunicationCustomerInvoice:
  from_email: "billing@yourcompany.com"
  from_name: "Your Company Billing"
  template_id: 6759851
  subject: "Your Invoice - "

When Sent:

  • Invoice automatically generated for billing period
  • Manual invoice created by staff
  • Customer requests invoice copy

Template Variables Available:

  • {{ var:customer_name }} - Customer's full name
  • {{ var:invoice_number }} - Invoice ID/number
  • {{ var:invoice_date }} - Invoice issue date
  • {{ var:due_date }} - Payment due date
  • {{ var:total_amount }} - Total amount due
  • {{ var:invoice_url }} - Link to view/download invoice PDF
  • {{ var:pay_url }} - Link to pay invoice online

Invoice Attachment:

The invoice PDF is automatically attached to the email.

Customer Invoice Reminder​

Sent to remind customers of overdue invoices.

api_crmCommunicationCustomerInvoiceReminder:
  from_email: "billing@yourcompany.com"
  from_name: "Your Company Billing"
  template_id: 6759852
  subject: "Payment Reminder - Invoice Overdue"

When Sent:

  • Invoice is X days past due (configurable)
  • Manual reminder triggered by staff
  • Automated reminder workflow (if configured)

Template Variables Available:

  • {{ var:customer_name }}
  • {{ var:invoice_number }}
  • {{ var:due_date }}
  • {{ var:days_overdue }}
  • {{ var:total_amount }}
  • {{ var:pay_url }}

Staff User Welcome Email​

Sent when a new staff user account is created.

api_crmCommunicationUserWelcome:
  from_email: "admin@yourcompany.com"
  from_name: "Your Company Admin"
  template_id: 5977510
  subject: "Welcome to the Team"

When Sent:

  • Admin creates new staff user
  • "Send Welcome Email" button clicked in user management

Template Variables Available:

  • {{ var:user_name }} - Staff user's full name
  • {{ var:email }} - Staff user's email
  • {{ var:role }} - Assigned role(s)
  • {{ var:login_url }} - Link to admin portal login
  • {{ var:temp_password }} - Temporary password (if applicable)
  • {{ var:support_email }} - IT support contact

User Password Reset​

Sent when a user requests to reset their password.

api_crmCommunicationUserPasswordReset:
  from_email: "noreply@yourcompany.com"
  from_name: "Your Company Security"
  template_id: 5977511
  subject: "Password Reset Request"

When Sent:

  • User clicks "Forgot Password" on login page
  • User submits password reset request

Template Variables Available:

  • {{ var:user_name }}
  • {{ var:reset_url }} - Time-limited password reset link (typically 1 hour)
  • {{ var:expiry_time }} - When reset link expires

Security Note:

Reset links expire after configured time period (default 1 hour).

User Password Reset Success​

Sent to confirm password was successfully changed.

api_crmCommunicationUserPasswordResetSuccess:
  from_email: "noreply@yourcompany.com"
  from_name: "Your Company Security"
  template_id: 5977512
  subject: "Password Changed Successfully"

When Sent:

  • User successfully completes password reset
  • Immediately after new password is set

Template Variables Available:

  • {{ var:user_name }}
  • {{ var:change_date }} - Date/time password was changed
  • {{ var:ip_address }} - IP address of change (optional)
  • {{ var:support_email }} - Contact if change was unauthorized

User Password Change​

Sent when a user changes their password from settings.

api_crmCommunicationUserPasswordChange:
  from_email: "noreply@yourcompany.com"
  from_name: "Your Company Security"
  template_id: 5977513
  subject: "Password Change Notification"

When Sent:

  • User changes password from profile/settings
  • Admin resets user password

Template Variables Available:

  • {{ var:user_name }}
  • {{ var:change_date }}
  • {{ var:changed_by }} - "Self" or admin name
  • {{ var:support_email }}

Email Verification​

Sent to verify a user's email address.

api_crmCommunicationEmailVerification:
  from_email: "noreply@yourcompany.com"
  from_name: "Your Company"
  template_id: 5977514
  subject: "Verify Your Email Address"

When Sent:

  • New account created (customer or staff)
  • User changes email address
  • Email verification required for security

Template Variables Available:

  • {{ var:user_name }}
  • {{ var:verification_url }} - Link to verify email
  • {{ var:verification_code }} - Code to enter manually (alternative to link)

Balance Expired Notification​

Sent when a customer's service balance/allowance has expired.

api_crmCommunicationsBalanceExpired:
  from_email: "support@yourcompany.com"
  from_name: "Your Company Support"
  template_id: 5977515
  subject: "Your Service Balance Has Expired"

When Sent:

  • Prepaid balance expires
  • Monthly allowance renewal date passed
  • Service expiry date reached

Template Variables Available:

  • {{ var:customer_name }}
  • {{ var:service_name }} - Name of expired service
  • {{ var:expiry_date }}
  • {{ var:balance_type }} - "Data", "Voice", "Monetary", etc.
  • {{ var:renewal_url }} - Link to renew/top-up

Low Balance Alert​

Sent when a customer's balance falls below configured threshold.

api_crmCommunicationsBalanceLow:
  from_email: "support@yourcompany.com"
  from_name: "Your Company Support"
  template_id: 5977516
  subject: "Low Balance Alert"

When Sent:

  • Balance drops below threshold (e.g., 20% remaining)
  • Configured in service plan or OCS
  • Real-time monitoring triggers alert

Template Variables Available:

  • {{ var:customer_name }}
  • {{ var:service_name }}
  • {{ var:current_balance }}
  • {{ var:threshold }}
  • {{ var:balance_type }}
  • {{ var:topup_url }} - Link to add balance

Creating Mailjet Email Templates​

For each email type, you need to create a corresponding template in Mailjet.

Step 1: Create Template in Mailjet​

  1. Login to Mailjet dashboard
  2. Navigate to Email Templates → Transactional Templates
  3. Click Create a New Template
  4. Choose Code your own template (for advanced users) or Use template builder

Step 2: Design Template​

Use Mailjet's drag-and-drop builder or HTML editor to design your email.

Essential Elements:

  • Header - Company logo and branding
  • Greeting - Personalized with {{ var:customer_name }} or {{ var:user_name }}
  • Content - Main message body
  • Variables - Insert template variables from list above
  • Call to Action - Buttons/links for user actions
  • Footer - Unsubscribe link, company address, support contact

Example Template (Password Reset):

<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: Arial, sans-serif; }
        .button { background-color: #4CAF50; color: white; padding: 14px 28px; }
    </style>
</head>
<body>
    <img src="https://yourcompany.com/logo.png" alt="Logo" width="200">

    <h2>Password Reset Request</h2>

    <p>Hello {{ var:user_name }},</p>

    <p>We received a request to reset your password. Click the button below to create a new password:</p>

    <a href="{{ var:reset_url }}" class="button">Reset Password</a>

    <p>This link expires in {{ var:expiry_time }}.</p>

    <p>If you didn't request this, please ignore this email.</p>

    <hr>
    <p style="font-size: 12px; color: #666;">
        Your Company | support@yourcompany.com<br/>
        123 Business St, City, Country
    </p>
</body>
</html>

Step 3: Get Template ID​

  1. Save template in Mailjet
  2. Note the Template ID (numeric, e.g., 5977509)
  3. Copy this ID to crm_config.yaml

Step 4: Test Template​

  1. In Mailjet, use Test Email feature
  2. Provide sample values for all variables
  3. Send test email to yourself
  4. Verify formatting, links, and branding

Step 5: Configure in OmniCRM​

Add template configuration to crm_config.yaml:

mailjet:
  api_key: your_api_key
  api_secret: your_secret

  api_crmCommunicationUserPasswordReset:
    from_email: "noreply@yourcompany.com"
    from_name: "Your Company Security"
    template_id: 5977511
    subject: "Password Reset Request"

Restart OmniCRM API for changes to take effect:

cd OmniCRM-API
sudo systemctl restart omnicrm-api

Contact Syncing​

All customer contacts in OmniCRM are automatically synced to Mailjet.

What Gets Synced:

  • Contact name
  • Email address
  • Contact type (billing, technical, etc.)
  • Customer location
  • Custom fields

Sync Frequency:

Contacts sync in real-time when:

  • New customer created
  • Contact added/updated
  • Customer details modified

Troubleshooting​

Email not sending

  • Cause: Invalid API credentials, Mailjet account suspended, or template ID wrong
  • Fix:
    • Verify api_key and api_secret in crm_config.yaml
    • Check Mailjet account status and billing
    • Verify template ID exists in Mailjet
    • Check API logs for errors

Template variables not substituting

  • Cause: Variable name mismatch or missing data in OmniCRM
  • Fix:
    • Verify variable names match exactly (case-sensitive)
    • Use {{ var:variable_name }} format
    • Check OmniCRM is passing variable data in API call
    • Test with sample data in Mailjet

Invoice PDF not attaching

  • Cause: PDF generation failed or file size too large
  • Fix:
    • Check invoice generation logs
    • Verify invoice template renders correctly
    • Ensure PDF under 15MB (Mailjet limit)
    • Test invoice PDF generation separately

Contacts not syncing to Mailjet

  • Cause: API rate limit exceeded or sync service not running
  • Fix:
    • Check Mailjet API rate limits (200 calls/minute)
    • Verify OmniCRM-API service is running
    • Review sync logs for errors
    • Manually trigger sync for testing
  • administration_configuration - Complete Mailjet configuration reference
  • payments_invoices - Invoice generation and email delivery
  • authentication_flows - Password reset and verification emails
  • customer_care - Self-Care portal welcome emails

Further Reading​