Email Versand

Prerequisites

You should have

• an user-account enabled for api access & App Message Builder
• an api-client
• a configured "Message Template" within the "Message Builder"
• a configured Email-Channel in your Hublify

Quick Infos

Some generic helpful infos on the App Message Builder and on sending Emails with it:

• In the Hublify App "Message Builder" you can store and manage different "Message Templates", e.g. for Emails.
• A Message Template is normally associated to a "contextual dataset / datatype" within Hublify, such as "Person", "Order", "Invoice", ...
  A message is then dynamically build (rendered / generated) for one data record and then send.
• Message Templates can be very dynamic and smart! E.g. a Message Template itself can determine its final recipient(s)!
  For example some of the standard Hublify Email Messages ...
  • "Order Confirmation" Message detects its TO-Email-recipient from the Person-record.
  • "Invoice Email" Message detects its TO-Email-recipient from either the inv-email from the invoice record or from the connected Person's email address.
• Through the Message Builder you can trigger also to send one or many Messages / Emails.
• Here we cover only how to send an Email.
  Not how to configure or develop the actual used message template. Please see other sections on those details!
• Internal technical process is actually:
  • Context-Data-Record(s) are selected from database,
  • Message-Template and -data is loaded,
  • within defined H-CMS' (HTML-)Template (twig) is rendered,
  • Special HTML/Hublify-Email-Tags (for dynamic Subject, To, Cc, .. , Attachments) are extracted / being parsed,
  • Email is being built,
  • Email is sent through configured Hublify Email Channel.

 

Sending an email

Sending a message is very easy. All you basically have to provide is:

• A criteria which one Message Template to use (most common:  "msgtpl_uuid"),
• filter-criteria ("dataset" and "filter") for which context-data-record (Person, Order, Invoice, ...) you want to send the message.

... one

In the following example is shown how an "Invoice Email" is sent to an invoice-record (... well actually to the "Person" associated to the invoice).

Request URL

https://{your hublify url}/api/eos_10/data_list_sendmessage

Request parameter

{
    "dataset": "invoice",                  // (required) Dataset-Label of "context-data".

    "filter": {                            // (required) Filter-Criteria to select the context-data-record.
        "inv_id": {
            "in": [
                "2142"
            ]
        }
    },

    "fields": [                            // (optional) Fields of dataset-record to retrieve beforehand and
        "inv_id",                          // inject into template-rendering as twig-variables.
        "inv_code",                        // These can only be fields of upper given "dataset"!
        "inv_email",
        "invoice_email",
        "inv_firstname",
        "inv_lastname",
        "personid",
        "email"
    ],

    "msgtpl_uuid": "msgtpl-999....a83003", // (required) The unique message-template-id to use & build and send.
                                           // Look this up beforehand in your App Message Builder!

    //     or alternatively a triple-filter, addressing one message template:

    "msgtpl_label": "...",                 // string (required) Using this triple is somewhat more "speaking", but
    "msgtpl_type": "...",                  // string (required) ... might be not exact enough. Depending on your numbers
    "msgtpl_context": "...",               // string (optional) ... of configured Message Templates!


    "msgtpl_dynparams": {                  // (optional) Possible properties absolutely depend on the chosen message-template!
        "to": "override@example.com",      // Many of the Hublify Standard Email Message Templates support these shown 
        "cc": "",                          // parameters: "to", "cc", "bcc", ...
        "bcc": "",
        "from": "",
        "replyto": ""
    }

}

Response

If your request was successful, you receive some aggregated data and messages.

{
    "status": true,

    "data": {
        "msg_cnt_total": 1,
        "msg_cnt_ok": 1,
        "msg_cnt_error": 0
    },

    "msg": [
        {
            "type": "ok",
            "title": "Send Email: 1",
            "text": "Vorlage \"Rechnung / Gutschrift - Kunde\"",

            "refType": "messagetemplate",
            "refId": "31",

            "subMsgs": [
                {
                    "type": "ok",
                    "title": "Email \"Gutschrift R00002137\"",
                    "text": "To: \"override@example.com\" Attachments: 1 ",
                    "refType": "invoice",
                    "refId": "2142"
                }
            ]
        }
    ]
}

Response - Error

If your request failed, you receive a message detailing the error that occurred.

{
    "status": false,
    "msg": [
        {
            "type": "ERROR",
            "text": "... SOMETHING !"
        }
    ]
}

 

... many

You can send multiple Invoice Emails at once. Just change the filter-criteria to match multiple invoice-records!