

How It Works

The most common usage for TRAML is to send an email based on an event in Lime CRM. If your solution or limepkg doesn't have an event-handler already, you can add one:

$ lime-project generate event-handler

Email

Step 1: Import and initialize the library event handler

Inside your-addon-folder/event_handlers/__init__.py import the library:

import transactional_message_library.traml as traml

And at the bottom of the register_event_handler function, add the following line:

traml.register_event_handler(worker, 'my-addon')

Change my-addon to a unique name. It is important that you choose a unique name in case your solution has several add-ons using TRAML.

Step 2: Inside your eventhandler or your limeobject class, add Email instances to an empty list

emails = []

emails.append(
    traml.Email(
        sender_name='Agent X',
        sender_email='[email protected]',
        subject='Helpdesk status changed to assigned',
        recipient_name='Agent Y',
        recipient_email='[email protected]',
        template_name="standard text",
        merge_codes=dict(
            monkey='Orangutang',
            katt='Nisse'
        ),
        options=dict(  # optional parameters
            external_id='1001',
            track_openings=True
        )))

# append some more emails...

Step 3: Tell the library to send the new emails

traml.notify(application, 'my-addon', emails)

Step 4: Profit 🥇

---

Optional Parameters

It is possible to include some optional parameters when sending transactional emails. Here is a list of currently supported parameters:

Parameter Name	Default Value	Description
external_id		Bind the email message to an external id (a Marketing Activity for example).
track_openings	False	Should message openings be tracked.
track_link_clicks	False	Should link clicks be tracked.
send_datetime	None (the message will be sent ASAP)	Date and time if you want to delay the message. Type: datetime object.
attachments		Files that should be attached to the transactional email. Read more here.
reply_to		Set a reply to email address to your message.
from_name		Set a from name to your message.
from_email		Set a from email address to your message.

From name and from email

By default the SenderName and SenderEmail parameters will be used as From headers in the mailmessage in Bedrock.

If you supply your own FromName and FromEmail parameters in options dict they will be used ad From headers and SenderName and SenderEmail will instead be set for Sender headers.

emails.append(
    traml.Email(
        sender_name='Sven Svensson',
        sender_email='[email protected]',
        subject='transmail-subject',
        recipient_name='Niclas Ahlqvist',
        recipient_email='[email protected]',
        template_name="standard text",
        merge_codes=dict(
        ),
        options=dict(  # optional parameters
            track_openings=True,
            send_datetime=senddatetime,
            from_email='[email protected]',
            from_name='Esign'
        )))

The mailmessage will now be shown as:

Read more about the difference between the From and Sender headers here

Delayed message example with the send_datetime parameter

Create a datetime object with the desired date and time when the message should be sent. In this example it will be sent 9:00 the same day. If the time is in the past the message will be sent asap instead.

import datetime

today = datetime.date.today()
time = datetime.time(hour=9, minute=00)
senddatetime = datetime.datetime.combine(today, time)

emails = []
emails.append(
    traml.Email(
        sender_name='Agent X',
        sender_email='[email protected]',
        subject='Helpdesk status changed to assigned',
        recipient_name='Agent Y',
        recipient_email='[email protected]',
        template_name="standard text",
        merge_codes=dict(
            monkey='Orangutang',
            katt='Nisse'
        ),
        options=dict(  # optional parameters
            track_openings=True,
            send_datetime=senddatetime
        )))

Attach files to transactional mail

The parameter attachments in traml.Email.options takes a list of dictionaries:

[
    { "FileData": <Base64 encoded file stream>,
      "FileNameWithExtension": <filename>,
      "MimeType": <mimetype> }
]

To create an attachment dict you can use the following snippet. Limefile in this case could be a file fetched from a document record in your Lime database with

# Fetch the file to be attached from a document record
limefile = document.properties.document.fetch()

# Get a dict that can be appended to a traml.email's list of attachments
f = getAttachment(file)

def getAttachment(limefile):
    file_stream = limefile.stream
    file_stream.seek(0)
    base64_bytes = base64.b64encode(file_stream.read())
    base64_str = base64_bytes.decode("utf-8")

    ret = {"FileData": base64_str,
           "FileNameWithExtension": limefile.filename,
           "MimeType": limefile.mimetype}

    return ret

Use the traml.Email constructor and your attachments will be validated properly.

---

Send SMS With TRAML

You need to activate the SMS module in your Lime Marketing site before you can use this feature. The default limit is 5000 SMS messages/month but it is possible to increase this limit.

Follow the e-mail guide until step 3.

sms = []

sms.append(
    traml.Sms(
        text='You have to log your time in Sublime!',
        from_number='0720803134',
        destination_number='+46720803151'
        ))

# append some more sms...

Then simply:

traml.notify(application, 'my-addon', sms)

---