E-mail Templates

In the Akinon Commerce platform, email templates play a crucial role in maintaining consistent and effective communication with users. These templates are pre-defined email formats used to send automated messages to users based on specific triggers or actions within the platform. This document provides a comprehensive overview of managing email templates, including their loading process, creation, and updating via the Omnitron panel. Additionally, it details the various types of email templates available, their usage, and the context variables associated with each template.

Managing Email Templates

The default email templates are loaded in projects deployed via ACC. This loader checks for the existence of email templates in the following order:

1. Database:

   • The loader first checks if the email template exists in the database.

   • If the template is found in the database, it is used for sending emails.

2. File System:

   • If the template is not found in the database, the loader then checks the file system for the template.

   • The file path for the template is used if it is not present in the database.

Creating and Updating Mail Templates

Mail templates can be created and managed through the Omnitron panel (Sales Channels > Content Management > Mailing Templates). This interface allows for the management of mail templates used across various sales channels.

Send Emails in Different Languages

When users interact with your site in a language other than the default—such as Arabic—they should receive all system-generated emails (e.g., order confirmation, welcome emails, password reset emails) in the same language. However, if the multilingual configuration is incomplete, emails may still be sent in the default language (e.g., English), regardless of the language used on the site.

To ensure emails are sent in the appropriate language:

1. Define Supported Languages in Project Settings During project setup, all supported languages and locales must be defined. Follow the Language and Locale Setup Guide and make sure any additional languages (e.g., Arabic) are added correctly.

2. Create Language-Specific Email Templates in Omnitron The languages defined in the project become available as options in the Language dropdown when creating or editing email templates in Omnitron > Sales Channels > Content Management > Mailing Templates.

3. Enter the Corresponding Content Per Language For each email type (order, reset password, welcome, etc.), select the desired "Language" from the dropdown and provide the content in that language. This ensures that users always receive localized email content matching their on-site experience.

All Existing Email Templates

1. Contact Us

This is a communication email template that allows users to reach out to the brand. Users can select from predefined subjects relevant to their inquiry.

Template Path:

emails/accounts/contact-us.html

Context Variables:

• subject: The subject line of the email, chosen by the user from a list of predefined subjects set by the brand.

• full_name: The full name of the user who is sending the email.

• email: The email address of the user.

• message: The main body of the user's message.

• phone: The user's phone number.

• file: Any file uploaded by the user. This can include documents, images, or any relevant files that support the user's message.

• order: An object representing the user's order details. The details of the order object are provided in the Order table.

• operation: The mail group category defined in the module.

• site_domain: The domain of the website from which the email is sent.

2. Password Reset

A password reset email is sent by the commerce platform when a user requests to reset their password. The email facilitates the process by providing a link or instructions for resetting the password.

Template Path:

There is no existing template; it needs to be entered manually into the RESET_EMAIL_HTML_TEMPLATE dynamic setting in Omnitron.

Context Variables:

• email: The email address to which the password reset email will be sent. This is the user's registered email address used for receiving the reset instructions.

3. Post Order Discount

This email is sent to notify the user about discounts earned after placing an order. The email informs the user about any applicable post-order coupons or discounts.

Template Path:

When creating a campaign in Omnitron with the action type set to "Coupon", a path is generated in the format emails/promotions/{template_prefix}. This path uses the {template_prefix} value entered in the "Email Templates" parameter of the coupon information field. Based on the entered {template_prefix}, a path will be automatically generated.

Example: If you enter summer_sale as the template prefix, the generated path will be emails/promotions/summer_sale.

Context Variables:

• basket_offer: The BasketOffer object related to the post-order discount. This object contains details about the discount or promotion applied to the user's order. The details of the basket_offer object are provided below.

  • basket_offer.label

  • basket_offer.promotion.name

• site_domain: The domain of the website where the order was placed.

• user: The User object representing the user who placed the order. This object contains the user's information necessary for personalization and addressing the email. The details of the user object are provided in the User table.

4. Email Verification

An email verification message is sent to users to verify their email address during the registration process. However, this behavior can be disabled by configuring the ACCOUNT_EMAIL_VERIFICATION setting in the Commerce environment of ACC.

Setting ACCOUNT_EMAIL_VERIFICATION = 'none' disables automatic email verification during registration.

Template Path:

account/email/email_confirmation.html

Context Variables:

• user: The User object representing the new user who is registering. This object contains the user's information necessary for personalization and addressing the email. The details of the user object are provided in the User table.

• activate_url: The URL provided for email verification. This link redirects the user to a page where they can verify their email address.Example URL: https://akinon.akinon.net/users/registration/account-confirm-email/{confirmation_key}/

• current_site: The domain of the verification website.

• key: The confirmation key used to authenticate the user's email address. This key is also included within the above activate_url. There is no expiration period for this key.

5. Loyalty Money Refund

A notification email sent when loyalty money used in an order is refunded.

Template Path:

emails/loyalty/applied-loyalty-money.html

Context Variables:

• user: The User object representing the user who is receiving the refund. The details of the user object are provided in the User table.

• loyalty_money_amount: The amount of loyalty money that is being refunded.

• currency: The currency in which the refunded amount is issued.

• order_number: The number associated with the order for which the loyalty money is being refunded.

• order_language_code: The language code of the order.

6. Order Received

A notification email sent to users when an order is successfully placed. This email is automatically sent during the order creation process.

Template Path:

emails/orders/completed.html

Context Variables:

• order: The Order object representing the details of the placed order. The details of the order object are provided in the Order table.

• site_domain: The domain of the website where the order was placed.

7. Order Shipped

A notification email sent to users when their order has been shipped. This email is triggered when the order status changes to 'shipped = 500'.

Template Path:

emails/orders/cargo.html

Context Variables:

• order: The Order object representing the details of the shipped order. The details of the order object are provided in the Order table.

• site_domain: The domain of the website where the order was placed.

8. Partially Shipped Order

A notification email sent when some items in an order are shipped.

Template Path:

emails/orders/partial-cargo.html

Context Variables:

• order: The Order object representing the details of the order. The details of the order object are provided in the Order table.

• order_items: The OrderItem objects that have been shipped. This includes information about the items that are on their way to the customer. The details of the order_items object are provided in the Order_item table.

• shipping_company: The name of the shipping company handling the shipment. This helps the customer know which carrier is delivering their items.

• tracking_number: The tracking number provided by the shipping company. This allows the customer to track the shipment of the partially shipped items.

• site_domain: The domain of the website where the order was placed.

• remaining_orderitems: All OrderItem objects that are still pending shipment. This informs the customer about the items that have not yet been shipped. It includes the same details as the order_items object.

9. Order Delivered

A notification email sent to users when their order is delivered.

Template Path:

emails/orders/order-delivered.html

Context Variables:

• order: The Order object representing the details of the delivered order. The details of the order object are provided in the Order table.

• site_domain: The domain of the website where the order was placed.

• return_address: The return address provided in the settings. Enter this into the ORDER_RETURN_ADDRESS field in the Django settings, with the string type.

10. Partially Delivered Order

A notification email sent when some items in an order are delivered.

Template Path:

emails/orders/partial-delivered-cargo

Context Variables:

• order: The Order object representing the details of the order. The details of the order object are provided in the Order table.

• order_items: The OrderItem objects that have been delivered. This includes information about the items that have reached the customer. The details of the order_items object are provided in the Order_item table.

• shipping_company: he name of the shipping company handling the delivery. This helps the customer know which carrier has delivered their items.

• tracking_number: The tracking number provided by the shipping company. This allows the customer to track the delivery of the partially delivered items.

• site_domain: The domain of the website where the order was placed.

11. Order Ready for Pickup

A notification email sent to users when their order is ready for pickup. This email, triggered when the order arrives at the store, provides information about the pickup process. It simply informs users that their order is ready and provides details on how to collect it.

Template Path:

emails/orders/order-ready-for-pickup.html

Context Variables:

• order: The Order object representing the details of the order. The details of the order object are provided in the Order table.

• site_domain: The domain of the website where the order was placed.

• return_address: The return address provided in the settings.

12. Package Created in OMS

An email sent to relevant stock locations when a package is prepared or created in the Order Management System (OMS).

Template Paths:

package.created:

• For mail body: emails/orders/package-created.html(This template is used for the body of the email that is sent when a package is created.)

• For mail subject: emails/orders/package-created-subject.html(This template is used for the subject line of the email that is sent when a package is created.)

package.status.preparing:

• For mail body: emails/orders/offer-accepted.html(This template is used for the body of the email that is sent when an offer is accepted.)

• For mail subject: emails/orders/offer-accepted-subject.html(This template is used for the subject line of the email that is sent when an offer is accepted.)

Context Variables:

The payload from the OMS request is directly used as the context. The specific details of the payload are not included due to size, but they typically include information about the package, order details, and relevant stock location data.

Example Payload:

curl -X POST 'http://{{xxx}}/api/v1/packages/notify/' --header 'Content-Type: application/json' --header 'Authorization: Token 138ddd19a0436166354cccbacb4cdsfsdbb0473104193' --data '{
  "event": {
    "type": "package.created",
    "uuid": "741077e138c14d329cdfgd8eca6773f94f56"
  },
  "payload": {
    "channel_name": "XXX-Shop",
    "city": "İSTANBUL",
    "created_date": "2020-12-17T10:55:58.648867Z",
    "commands": [
      {
        "command": "PKG_STATE_TRANSITION",
        "destination_state": 37,
        "id": 3,
        "is_packageitem_parameter_required": false,
        "label": "Hazırla",
        "source_state": 35,
        "ui_visibility": [
          "third_party",
          "oms_web",
          "instore"
        ]
      },
    ],
    "date_placed": "2020-12-17T10:55:58.648867Z",
    "delivery_range": null,
    "id": 808,
    "invoice_number": null,
    "is_click_and_collect": false,
    "number": "1529805300913185P2",
    "order_gift_box_note": null,
    "order_id": 868,
    "order_notes": null,
    "order_number": "152980530980913185",
    "order_retail_store_id": null,
    "packageitem_set": [
      {
        "commands": [
          
        ],
        "created_date": "2020-12-17T11:23:01.878961Z",
        "denial_reason": null,
        "id": 908,
        "modified_date": "2020-12-17T11:23:01.878983Z",
        "order_item": {
          "attributes": {
            
          },
          "attributes_kwargs": {
            
          },
          "commands": [
            
          ],
          "created_date": "2020-12-17T10:56:08.556951Z",
          "discount_amount": "0.00",
          "extra_field": {
            "price_extra_field": {
              "offer_price": 6145
            },
            "stock_extra_field": null
          },
          "id": 838,
          "image": null,
          "installment_interest_amount": null,
          "modified_date": "2020-12-17T10:56:08.556978Z",
          "net_amount": "6719.00",
          "omnitron_id": 977,
          "order": 868,
          "price": "6719.00",
          "price_currency": "try",
          "price_list": {
            "code": "shop_price_list",
            "created_date": "2020-11-09T06:45:52.649753Z",
            "is_auto_sync": true,
            "modified_date": "2020-11-09T06:45:52.649774Z",
            "name": "Shop Price List",
            "pk": 1
          },
          "product": {
            "attributes": {
              "erp_category_code": "24020500",
              "erp_category_code_path": "24000000|24020000|24020500",
              "erp_category_name_path": "Ev Aletleri|Buzdolabı|Üstten donduruculu",
              "erp_color": "WHITE",
              "integration_star_grade": "0",
              "product_desi": "90000",
              "product_kind": "Refrigerator"
            },
            "attributes_kwargs": {
              "integration_color": {
                "data_type": "dropdown",
                "label": "WHITE",
                "value": "WHITE"
              },
            },
            "barcode": null,
            "base_code": "266",
            "created_date": "2020-11-26T07:08:30.140687Z",
            "extra_attributes": {
              
            },
            "id": 267,
            "modified_date": "2020-12-17T08:30:05.748471Z",
            "name": "Buzdolabı 543 L",
            "omnitron_id": 3054,
            "productimage_set": [
              {
                "id": 519,
                "order": 2,
                "product": 267,
                "url": "https://xxx.akinoncdn.com/products/2020/11/17/3054/63cfbfgdgfe29-038b-4213-9ed9-229c71878e78.jpg"
              },
          ],
            "remote_modified_date": "2020-12-15T03:48:12.855393Z",
            "sku": "RT53K63gfg60WW/TR"
          },
          "retail_price": "7899.00",
          "state": {
            "config": {
              
            },
            "content_type": 2,
            "created_date": "2020-11-05T13:29:46.633809Z",
            "enum_class": "OrderStatus",
            "enum_value": "400",
            "id": 23,
            "modified_date": "2020-11-05T13:29:46.633832Z",
            "name": "Approved"
          },
          "stock_list": {
            "code": "shop_stock_list",
            "created_date": "2020-11-09T06:42:34.242889Z",
            "is_auto_sync": true,
            "modified_date": "2020-11-09T06:42:34.242911Z",
            "name": "Shop Stock List",
            "pk": 1
          },
          "tax_amount": null,
          "tax_rate": "18.00",
          "without_net_amount": null
        },
        "package": 808,
        "selected_barcode": null,
        "state": {
          "config": {
            
          },
          "content_type": 4,
          "created_date": "2020-11-05T13:29:46.982791Z",
          "enum_class": "PackageItemStatus",
          "enum_value": "100",
          "id": 54,
          "modified_date": "2020-11-05T13:29:46.982816Z",
          "name": "Waiting"
        },
        "transfer_order": null,
        "unit_weight": null
      }
    ],
    "payment_type": "credit_card",
    "remote_id": null,
    "shipment": null,
    "shipment_date": null,
    "shipping_address": {
      "address_type": "customer",
      "city": {
        "country": 1,
        "is_active": true,
        "latitude": null,
        "longitude": null,
        "name": "İSTANBUL",
        "pk": 40
      },
      "company_name": "",
      "country": {
        "code": "tr",
        "is_active": true,
        "latitude": null,
        "longitude": null,
        "name": "Türkiye",
        "pk": 1
      },
      "created_date": "2020-12-14T14:06:25.417903Z",
      "customer": {
        "channel": 1,
        "email": "[email protected]",
        "erp_code": null,
        "first_name": "xxx",
        "last_name": "xxx",
        "phone_number": "xxx",
        "pk": 3
      },
      "district": {
        "city": 40,
        "is_active": true,
        "latitude": null,
        "longitude": null,
        "name": "AHMEDİYE MAH",
        "pk": 35232,
        "township": 449
      },
      "e_bill_taxpayer": false,
      "email": "[email protected]",
      "first_name": "xxx",
      "id": 529,
      "is_active": true,
      "last_name": "xxx",
      "line": "xxx",
      "mapping": null,
      "modified_date": "2020-12-17T10:56:08.518268Z",
      "notes": null,
      "omnitron_id": 826,
      "phone_number": "+xxxx",
      "postcode": "xxx",
      "tax_no": "",
      "tax_office": "",
      "title": "Ev",
      "township": {
        "city": 40,
        "is_active": true,
        "latitude": null,
        "longitude": null,
        "name": "ÜSKÜDAR",
        "pk": 449
      }
    },
    "shipping_label": null,
    "state": {
      "config": {
        
      },
      "content_type": 3,
      "created_date": "2020-11-05T13:29:46.774796Z",
      "enum_class": "PackageStatus",
      "enum_value": "100",
      "id": 35,
      "modified_date": "2020-11-05T13:29:46.774821Z",
      "name": "Waiting"
    },
    "stock_location": {
      "address": {
        "city": {
          "country": 1,
          "is_active": true,
          "latitude": null,
          "longitude": null,
          "name": "İSTANBUL",
          "pk": 40
        },
        "country": {
          "code": "tr",
          "is_active": true,
          "latitude": null,
          "longitude": null,
          "name": "Türkiye",
          "pk": 1
        },
        "district": null,
        "id": 110,
        "is_active": true,
        "latitude": "40.96816250",
        "line": "xxx",
        "longitude": "29.26235830",
        "mapping": null,
        "notes": null,
        "postcode": null,
        "title": "xxx",
        "township": {
          "city": 40,
          "is_active": true,
          "latitude": null,
          "longitude": null,
          "name": "SULTANBEYLİ",
          "pk": 455
        }
      },
      "conf": {
        
      },
      "created_date": "2020-11-18T10:27:56.829361Z",
      "daytime_phone": "xxx",
      "email": "[email protected]",
      "engine": 1,
      "erp_code": "C750_034_100341",
      "evening_phone": "xxx",
      "fax_number": "",
      "id": 110,
      "is_active": true,
      "is_delivery_location": false,
      "is_fast_delivery_available": false,
      "is_fulfillment_center": true,
      "is_pickup_location": false,
      "is_return_available": true,
      "modified_date": "2020-11-19T08:53:49.340558Z",
      "name": "xxx",
      "priority": 10,
      "stock_location_type": "store",
      "target_packing_interval": "5 00:00:00",
      "target_transfer_interval": "3 00:00:00",
      "use_as_shipper_location": false
    },
    "target_packing_date": "2020-12-22T10:55:58.648867Z",
    "tracking_number": null
  }
}'

13. Checkout URL

An email sent to users containing the checkout URL. This email provides the user with a direct link to complete their purchase. The user can either scan a QR code in-store or receive the link via SMS, both of which direct them to the checkout page where they can proceed with their payment.

Template Path:

emails/orders/order-checkout-url.html

Context Variables:

• user: The User object representing the user who will receive the checkout URL. The details of the user object are provided in the User table.

• checkout_url: The URL where the user can complete their purchase.

• site_domain: The domain of the website where the order was initiated.

14. Order Cancellation/Return Request

An information email sent to users when they request to cancel or return an order.

Template Paths:

• refund: emails/orders/refund-request.html

• cancel: emails/orders/cancel-request.html

• easy return: emails/orders/easy-refund-request.html

Context Variables:

• default:

  • order: The Order object representing the order that is being canceled or returned. The details of the order object are provided in the Order table.

  • site_domain: The domain of the website where the order was placed.

• easy return:

  • return_code: The code assigned to the return request.

  • order_items: The OrderItem objects that are being returned via the easy return process.The details of the order_items object are provided in the Order_item table.

15. Product Back in Stock

A notification email sent to users when a product that was previously out of stock is back in stock. However, it is important to note that no email is triggered for extra stock of the same product once the initial notification has been sent.

Template Path:

emails/whislists/stock-alert.html

Context Variables:

• product: The Product object that is back in stock. The details of the user object are provided in the Product table.

• site_domain: The domain of the website where the product is listed.

• user: The User object representing the user who is receiving the notification. The details of the user object are provided in the User table.

16. Price Drop Alert

A notification email sent to users when the price of a product drops below a certain threshold. This email was not triggered for the extra product stock and extra product price lists.

Template Path:

emails/wishlists/price-alert.html

Context Variables:

• product: The Product object with the price drop. The details of the user object are provided in the Product table.

• site_domain: The domain of the website where the product is listed.

• user: The User object representing the user who is receiving the notification. The details of the user object are provided in the User table.

17. Verification Code

An email sent to the user for activation purposes. After the initial automated activation email is sent (detailed in the 4. Email Verification section), a manual activation email can be resent through Omnitron. This is done by clicking the highlighted button on the User Detail Page in Omnitron.

Template Path:

account/email/email_otp_verification_message.html

Context Variables:

• verification_code: The code sent to the user for verification. This code is used to verify the user's identity or action and is typically a one-time password (OTP).

18. Membership Welcome Email

A welcome email sent to the user when they register. This email is sent by the allauth package.

Template Path:

account/email/email_confirmation_signup.html

Context Variables:

• user: The User object representing the new user who has registered. The details of the user object are provided in the User table.

• activate_url: The email verification link that the user must click to verify their email address and activate their account.

• current_site: The domain of the verification site.

• key: The verification key used to validate the email verification link.

Rules for Sending Emails on Order Status Transitions

Emails are sent to inform users about specific transitions in the order status. For these emails to be sent, the following conditions must be met. Additionally, if necessary, the corresponding dynamic settings should be configured in Omnitron > Sales Channel Settings > Dynamic Settings page.

1. Order Shipped

Rule:

• SEND_SHIPPING_NOTIFICATIONS_PARTIALLY dynamic setting is set to False.

  
• The previous status of the order is either OrderStatus.approved or OrderStatus.preparing.

• The new status of the order is OrderStatus.shipped.

• A tracking number is present on the order.

Email Triggered: When these conditions are met, an email notification is sent to inform the user that their order has been shipped.

2. Order Ready for Pickup

Rule:

• The previous status of the order is either OrderStatus.shipped or OrderStatus.shipped_and_informed.

• The new status of the order is OrderStatus.ready_for_pickup.

Email Triggered: When these conditions are met, an email notification is sent to inform the user that their order is ready for pickup.

3. Order Delivered

Rule:

• SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY dynamic setting is set to False.

  
• The previous status of the order is either OrderStatus.shipped, OrderStatus.shipped_and_informed, or OrderStatus.attempted_delivery.

• The new status of the order is OrderStatus.delivered.

Email Triggered: When these conditions are met, an email notification is sent to inform the user that their order has been delivered.

4. Partially Shipped Order

Rule:

• SEND_SHIPPING_NOTIFICATIONS_PARTIALLY dynamic setting is set to True.

  
• is_status_changed is True (the order item's status has changed).

• The new status of the order item is OrderStatus.shipped.

• A tracking number is present on the order item.

Email Triggered: When these conditions are met, an email notification is sent to inform the user that some items in their order have been shipped.

5. Partially Delivered Order

Rule:

• SEND_SHIPPING_DELIVERED_NOTIFICATIONS_PARTIALLY dynamic setting is set to True.

  
• is_status_changed is True (the order item's status has changed).

• The new status of the order item is OrderStatus.delivered.

Email Triggered: When these conditions are met, an email notification is sent to inform the user that some items in their order have been delivered.

Enabling/Disabling Emails

Most emails sent during user membership, order status changes, etc., cannot be disabled. However, the sending of the following email can be stopped by setting the corresponding dynamic setting to False.

Verification Email

• Dynamic Setting: SHOULD_SEND_VERIFICATION_EMAIL

• Description: Sent when a user signs up to verify their email address.

Triggering Emails in Local Environment

Configuring SMTP Server

To send emails through the application in a local environment, SMTP settings need to be configured. Fill in the following settings with the SMTP server information that will be used for sending emails:

Observing Emails Without SMTP Server

​​If the SMTP server settings are not configured, the content of sent emails will be written to the console. For example, the "Order Received" email sent to the user upon placing an order will be displayed in the console.

Identifying Email Sending Errors

Errors in the code blocks responsible for sending emails are usually caught and sent to Sentry. The errors that occur during these send operations can be reviewed in the Sentry logs of the relevant brand. For mail send operations without controlled error handling, the errors can be observed in the application logs.

Common Errors

Most errors during mail sending are related to template rendering. To reproduce and fix these errors, the relevant templates can be rendered locally.

Troubleshooting Tips

1. Check Sentry Logs: If your application is integrated with Sentry, check the Sentry dashboard for any errors related to email sending.

2. Review Application Logs: Look at the console logs for any error messages or stack traces that can provide clues.

3. Validate Templates: Ensure that all required context variables are being passed to the template and that the template is correctly formatted.

4. Test Locally: Render the email templates locally with test data to see if any errors occur.

Object Details

This section provides a detailed overview of various objects and their associated attributes within the system. The objects include Order, Address, Order_item, Product, User, DataSource, and CategoryNode. Each object contains multiple fields that define its properties and relationships with other objects. This structured information is crucial for understanding how these objects interact within the system and for implementing or maintaining related features.

Below is a table outlining the fields and their corresponding objects.

Order

Order_item

Address

Product

User

DataSource

CategoryNode