Skip to content

Technical

TramlClient Class

The TramlClient class is the main interface for the library. The constructor receives the following parameters:

Parameter Name Type Default Value Description
app LimeApplication None An instance of the Lime CRM application
send_context SendContext None An instance of the SendContext class. If left empty it will create a send context from the config application_config
validator Validator Validator And instance of the Validator class. If left empty it will use the default regexp for email and mobile number validation
runtime_config TramlRuntimeConfig None The runtime config. If left empty it will try to load the runtime config from lime_data using the LimeApplication or fallback to a default config
application_config TramlApplicationConfig None The application config containing the test settings, API url and key to Lime Marketing. If left empty it will try to load the application config from lime_config using the LimeApplication

It is possible to use TRAML without a Lime CRM Application if a custom SendContext is supplied together with a config dict with the API info.

Basic Usage

Create a TramlClient instance by passing the LimeApplication. Configs will be resolved automatically

import limepkg_transactional_message_library.traml as traml

tc = traml.TramlClient(application)

# do stuff with traml client

Advanced Usage

You can use TramlClient without a LimeApplication and instead pass runtime and/or application config. This is done by passing TramlApplicationConfig config to TramlClient and optionally a custom SendContext.

  • By passing a custom SendContext the override and dry run settings will be picked up from the passed SendContext.
  • By passing a custom TramlApplicationConfig its possible to override all the settings otherwise picked up from the application configuration. A default send context will also be created from those settings if a SendContext wasn't passed.

Methods Available in TramlClient:

send_transactionmail_by_template

Send a single transactional email based on a template in Lime Marketing. The Email will be automatically validated to make sure that the recipient and from addresses are valid, that there is a subject and that any attachments are valid.

Parameter Name Type Description
message Email An Email model
template_id int The id of the mail template
Returns Description
TransactionMailModel A model containing the data of the sent Email message if successful

send_transactionmail

Send a single transactional email together with its HTML content. The Email will be automatically validated to make sure that the recipient and from addresses are valid, that there is a subject and that any attachments are valid.

Parameter Name Type Description
message Email An Email model
html_content string The HTML content as a string
text_content string The text content as a string
Returns Description
TransactionMailModel A model containing the data of the sent Email message if successful

send_transactionmail_batch

Send up to 100 transactional emails with raw content in one request. See Sending transactional emails in batch for details.

send_sms

Send a single transactional SMS. The SMS will be automatically validated to make sure that the recipient and from numbers are valid and that there is a text content

Parameter Name Type Description
message Sms An Sms model
text str The content of the SMS message
Returns Description
TransactionSmsModel A model containing the data of the sent SMS message if successful

send_sms_batch

Send up to 100 transactional SMS with raw text in one request. See Sending transactional SMS in batch for details.

get_mail_template_id_by_name

Get the id of an email template based on its name in Lime Marketing

Parameter Name Type Description
name string The name of the email template
Returns Description
int The id of the email template if successful

Generate a link to let the recipient add a booking to their calendar. Don't forget to add the link to the email content

Parameter Name Type Description
calendar_link CalendarLink A CalendarLink model
Returns Description
string The generated url to download the ical file

get_mergecodes_for_template

Get a list of all mergecodes in an email template

Parameter Name Type Description
template_id int Id of the mail template
include_recipient_mergecodes bool Should mergecodes in the "$$recipient.<property_name>$$" format be included. Defaults to False
Returns Description
list[MergeCodeModel] A list of MergeCodeModel

Email Class

The Email class holds all the settings for an email to be sent except the content. The content is passed to TramlClient as raw html/text or a template when sending an email. The properties for an Email are:

Parameter Name Type Required Default Value Description
recipient_name string Yes The name of the recipient
recipient_email string Yes The email address of the recipient
from_name string Yes The from name of the email
from_email string Yes The from email address of the email
subject string Yes The subject
scheduled_send_date datetime No None Date and time if the message is scheduled. When omitted or set to None the message will be sent ASAP
reply_to_email string No None Set a reply-to email address to the message.
sender_name string No None The name of the sender. Only for use special use cases. Read more here
sender_email string No None The email address of the sender. Only for use special use cases. Read more here
attachments List[Attachment] No [] A list of attachments
merge_codes dict No {} A dictionary containing merge codes
external_id string No Bind the email message to an external id (a Help desk id for example).
track_openings bool No False Should message openings be tracked.
track_link_clicks bool No False Should message link clicks be tracked.
exclude_totaloptouts bool No False Don't send if email is present on the total opt-out list
exclude_publicationoptouts bool No False Don't send if email is present on any publication opt-out list
exclude_previousbounce bool No True Don't send if the email has bounced previously
include_email_data_in_webhook_payload bool No False Include the sent email data in the webhook payload
headers dict No {} A dictionary for custom email MIME headers to be set when the email is sent
options dict No {} A dictionary for additional payload parameters to Bedrock. It cannot override recipient_email.

Sender Name and Sender Email

If the sender_name and sender_email parameters are used in the Email model they will be shown as "on behalf of" the from headers:

The recipient will receive an email like this:

image
Example of how on behalf of looks in Outlook email client

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

Warning

Using sender_name and sender_email is an option which you shouldn't have to use very often since it can cause deliverability problems if not used correctly. Make sure its a valid use case before using these settings. An alternative could be to set a more descriptive from_name Sven Svensson via Super Solution.

Headers

With the headers parameter it's possible to pass custom headers that will be used when the email is sent from Lime Marketing. Typical use cases can be to set priority, autoreply and in reply to and other email meta data that isnt possible to do via the Lime Marketing Bedrock API

Header keys and values must be of type string or None

The headers can be set directly on the Email class or by using the helper functions

Warning

Use headers with caution since it may have effect on the deliverability of the email

update_headers

Updates the current headers in a safe way - will overwrite existing values.

Parameter Name Type Description
headers dict New headers to update current headers with

set_autoreply_headers

Sets the headers used to mark an email as an auto reply. This is to tell receiving part to not respond with an auto reply or out of office message.

Parameter Name Type Description
headers dict New headers to update current headers with

Headers that are set. There is no "standard" way to this but the following headers are the safest.

Name Value
Auto-Submitted auto-replied
X-Auto-Response-Suppress All
Precedence auto_reply

set_in_reply_to_headers

Sets the headers to mark the email as a part of a conversation/thread. Pass the message id of which this email is a reply to

Parameter Name Type Description
message_id str The message id of the email this is a reply to. Usually formatted like <uniqueid@example.com>

Headers that are set. There is no "standard" way to this but the following headers are the safest.

Name Value
In-Reply-To Value of message_id
Reference Value of message_id

set_priority_headers

Sets the different priority headers based on importance where 1 = High, 3 = Normal and 5 = Low. Normal is the same as not setting a priority.

Parameter Name Type Description
priority EmailPriority High, Normal, Low

Headers that are set. There is no "standard" way to this but the following headers are the safest.

Name Value
Importance High|Normal|Low
X-Priority 1|3|5
X-MSMail-Priority High|Normal|Low

Saving a copy of the sent email message in Lime

By setting the include_email_data_in_webhook_payload parameter to True when sending an email you will be able to save the email content in Lime CRM. When the parameter is activated an exact copy of the email that was sent to the recipient will be included in the payload of the transactionmail.sent webhook. The email content data will be accessible in the TransactionMailContent property of the webhook payload in the form of a byte array. You can save this file as a document in Lime CRM by using the TramlEmailMessage class. Read more about its usage here.

It is important to note that opening the file or clicking any links in the file may result in link-click and opening events to be triggered, just as if the original recipient has opened or clicked the email message.

Sending transactional emails in batch

TramlClient.send_transactionmail_batch sends up to 100 transactional emails with raw content in one request to lime-marketing (transactionmail/sendbatch). Each recipient gets its own HTML and/or text content. Merge codes work exactly as in single send: put them in Email.merge_codes and lime-marketing replaces them in that recipient's content. You can therefore either send the same content to every recipient and personalise it with merge codes, or render fully personalised content per recipient yourself — or mix the two.

from limepkg_transactional_message_library import traml

client = traml.TramlClient(app=app)

batch_emails = [
    traml.models.BatchEmail(
        email=traml.models.Email(
            recipient_name=person.name,
            recipient_email=person.email,
            from_name="Dunder Mifflin",
            from_email="noreply@dundermifflin.com",
            subject="Your order",
            external_id=str(person.id),  # optional, echoed in webhooks
        ),
        html_content=render_html(person),
        text_content=render_text(person),
    )
    for person in people
]

for chunk in traml.models.chunk_batch(batch_emails):
    result = client.send_transactionmail_batch(chunk)
    for sent in result.sent:
        ...  # sent.transactionmail_id, sent.external_id
    for not_sent in result.not_sent:
        ...  # not_sent.index, not_sent.external_id, not_sent.error_message
    for skipped in result.skipped:
        ...  # skipped.index, skipped.external_id, skipped.reason, skipped.error

Rules

Rule Detail
One call = one request send_transactionmail_batch never loops. Passing more than traml.models.MAX_BATCH_SIZE (100) raises BatchRejected before anything is sent. Use traml.models.chunk_batch(messages, size=100) to split larger sendouts.
Run it in a background task Sending thousands of emails means many requests. Loop over chunks in a task and persist the result of each chunk before the next one, so a crash never loses already-sent results.
Invalid items are skipped Each item is validated on its own. An item without html_content or text_content, or with an invalid Email (address, subject, header or attachment), is returned in result.skipped with SkipReason.INVALID, and the rest of the batch is still sent. The skipped entry carries index (the item's position in the list you passed), external_id and error (the InvalidEmail raised by validation). Validation errors are logged with only the index, external id and error type, never the address. If no item is valid, no request is made. Problems that affect the whole call still raise: too many items, invalid batch_attachments or a payload over budget.
Payload size Requests are also limited by size, not just item count. lime-marketing's wire encoding inflates content roughly 5x, so around 39 KB of average HTML per email already fills a 100-item request against the default budget. traml.models.chunk_batch splits on both count and an estimated byte budget (DEFAULT_MAX_PAYLOAD_BYTES by default, override with max_payload_bytes), and send_transactionmail_batch refuses to send a batch of two or more emails whose estimated payload exceeds that budget, raising BatchRejected with no request made — splitting fixes it. A single email over the budget is sent anyway, with a warning logged: it cannot be split, so lime-marketing gets the final say, just like single send. Each chunk is a traml.models.BatchChunk that carries the max_payload_bytes and batch_attachments it was cut with, and send_transactionmail_batch takes them from the chunk, so you give the budget to chunk_batch only and the two calls cannot disagree. Passing a different value to send_transactionmail_batch for a chunk raises ValueError. A slice of a chunk, or a new list built from one, is a plain list and carries neither. Use traml.models.estimate_batch_wire_bytes if you want to budget yourself.
Errors BatchRejected: lime-marketing answered 4xx, or the batch was refused before sending (too many items, payload too large) - nothing was sent, so fix the input before retrying. BatchOutcomeUnknown: a network error or timeout, a 5xx, or a 2xx response TRAML cannot read - some or all emails of the chunk may have been sent. Do not blindly retry the chunk (you may double-send); reconcile via webhooks/external_id instead. Both are TramlError subclasses, so catching TramlError still works.
Send context applies per recipient Sending disabled → all items in result.skipped with SkipReason.SENDING_DISABLED, no request. Dry run → non-whitelisted items in result.skipped with SkipReason.DRY_RUN; whitelisted items are sent. Override recipient is applied to each item.
HTTP 200 is not "all sent" lime-marketing answers 200 even when some emails were rejected. Those are in result.not_sent with error_message and status (an integer status code from lime-marketing). No exception is raised. A non-2xx response raises BatchRejected (4xx) or BatchOutcomeUnknown (5xx) for the whole chunk.
Attachments Email.attachments are per recipient. batch_attachments=[...] on the call are added to every email in the batch and are only transferred once per request. Putting the same file on every recipient's Email.attachments instead transfers it once per recipient - use batch_attachments for files shared across the whole batch. When you chunk, give them to chunk_batch(batch_emails, batch_attachments=shared_files) only: it reserves room for them in the byte budget, and each chunk brings them to send_transactionmail_batch(chunk).
Your BatchEmail.email is replaced Each valid BatchEmail.email is replaced by a prepared copy: profile defaults merged and, when an override recipient is configured, recipient_email replaced. The items in skipped/not_sent therefore show what was actually used. Your original Email objects are never modified. Items skipped with SkipReason.SENDING_DISABLED or SkipReason.INVALID are returned exactly as passed in.

Result models

Class Fields
BatchEmail email: Email, html_content: str \| None, text_content: str \| None
BatchResult sent: list[SentTransactionMailModel], not_sent: list[NotSentEmail], skipped: list[SkippedEmail]
NotSentEmail batch_email: BatchEmail \| None and index: int \| None (both None if the response entry could not be matched to an input item), external_id: str \| None (as echoed by lime-marketing), error_message: str, status: int \| None, raw_response: dict
SkippedEmail batch_email: BatchEmail, reason: SkipReason, index: int (position in the list you passed), external_id: str \| None, error: TramlError \| None (only set for SkipReason.INVALID)
SkipReason SENDING_DISABLED, DRY_RUN, INVALID

Tracking a batch with webhooks

TRAML does not create transactional_message limeobjects for batch sends; the consumer owns persistence. Every SentTransactionMailModel has transactionmail_id (lime-marketing's id) and external_id (whatever you passed). Both appear as TransactionMail.Id and TransactionMail.ExternalId in every transactionmail.* webhook (sent, delivered, bounced, opened, link_clicked, not_sent), so either can be used to correlate webhook events to your own objects. Set external_id to a key you own if you want to correlate without storing lime-marketing ids.

To know which input each entry in result.sent belongs to, use external_id (or recipient_email when every recipient in the chunk is unique). transactionmail_id is assigned by lime-marketing, so it cannot identify the input on its own — and when override_recipient_email is active every recipient_email is the override address.

The same attribution limitation applies to result.not_sent: entries are matched back to an input item on (recipient email, external id). When override_recipient_email is active, or a chunk contains duplicate recipients without distinct external_ids, that match can be ambiguous and NotSentEmail.batch_email will be None — TRAML cannot tell which input the entry belongs to. NotSentEmail.raw_response always carries the full response entry regardless, so nothing is lost even when batch_email is None. To keep attribution reliable, give every item in a batch a distinct external_id.

Sending transactional SMS in batch

TramlClient.send_sms_batch sends up to 100 transactional SMS with raw text in one request to lime-marketing (transactionsms/sendbatch). Each recipient gets its own text. Merge codes work exactly as in single send: put them in Sms.merge_codes and lime-marketing replaces them in that recipient's text.

from limepkg_transactional_message_library import traml

client = traml.TramlClient(app=app)

batch_sms = [
    traml.models.BatchSms(
        sms=traml.models.Sms(
            from_number="DunderMiff",
            destination_number=person.mobilephone,
            merge_codes={"{{ firstname }}": person.firstname},
            external_id=str(person.id),  # optional, identifies the item in results
        ),
        text="Hi {{ firstname }}, your order has shipped.",
    )
    for person in people
]

for chunk in traml.models.chunk_sms_batch(batch_sms):
    result = client.send_sms_batch(chunk)
    for sent in result.sent:
        ...  # sent.transactionsms_id, sent.destination_number
    for not_sent in result.not_sent:
        ...  # not_sent.index, not_sent.external_id, not_sent.error_message
    for skipped in result.skipped:
        ...  # skipped.index, skipped.external_id, skipped.reason, skipped.error

Rules

SMS batches follow the same rules as email batches for the send context, background tasks and HTTP 200 responses. The differences are:

Rule Detail
One call = one request send_sms_batch never loops. Passing more than traml.models.MAX_BATCH_SIZE (100) raises BatchRejected before anything is sent. Use traml.models.chunk_sms_batch(messages, size=100) to split larger sendouts.
No payload budget SMS text is sent as a plain string and is normally short, so a full batch of typical SMS is small. chunk_sms_batch splits on count only. TRAML does not limit the text length - Sms.max_parts only tells lime-marketing where to truncate - so keep texts SMS-sized.
Invalid items are skipped Every BatchSms needs a non-empty text, a valid from_number and a valid destination_number. An item that does not is returned in result.skipped with SkipReason.INVALID, index, external_id and error (the InvalidSms), and the rest of the batch is still sent. Items under dry run are validated too, so an invalid one is skipped as INVALID rather than DRY_RUN. If no item is valid, no request is made.
Rejected items lime-marketing rejects some items individually, for example when the sender id is not verified. Those are in result.not_sent with error_message and status; the rest of the batch is still sent.
Errors BatchRejected: lime-marketing answered 4xx, nothing was sent - fix the input before retrying. BatchOutcomeUnknown: transport failure, 5xx or an unreadable 2xx response - some or all SMS may have been sent, so do not blindly retry the chunk (you may double-send). Both are TramlError subclasses.
Your BatchSms.sms is replaced Each valid BatchSms.sms is replaced by a prepared copy: the profile sender applied and, when an override mobile number is configured, destination_number replaced. Your original Sms objects are never modified. Items skipped with SkipReason.SENDING_DISABLED or SkipReason.INVALID are returned exactly as passed in.

Result models

Class Fields
BatchSms sms: Sms, text: str
SmsBatchResult sent: list[TransactionSmsModel], not_sent: list[NotSentSms], skipped: list[SkippedSms]
NotSentSms batch_sms: BatchSms \| None and index: int \| None (both None if the response entry could not be matched to an input item), external_id: str \| None (as echoed by lime-marketing), error_message: str, status: int \| None, raw_response: dict
SkippedSms batch_sms: BatchSms, reason: SkipReason, index: int (position in the list you passed), external_id: str \| None, error: TramlError \| None (only set for SkipReason.INVALID)

Tracking an SMS batch

As with email, TRAML does not create transactional_message limeobjects for batch sends. Every TransactionSmsModel in result.sent has transactionsms_id, which appears as TransactionSms.Id in the transactionsms.sent, transactionsms.delivery.succeded and transactionsms.delivery.failed webhooks.

Give every item a distinct Sms.external_id to tell results apart. lime-marketing echoes it on every entry, so it works the same way as for email:

  • result.sent entries carry external_id, the destination_number lime-marketing stored and the text after merge codes were replaced.
  • result.not_sent entries are matched back to an input item on (destination number, external id) and carry index and external_id. When the match is ambiguous, NotSentSms.batch_sms and NotSentSms.index are None. NotSentSms.raw_response always carries the full response entry.

Without external_id, not-sent entries are matched on (destination number, text) instead, where text is your raw text before merge codes. With one shared template and merge_codes, every item has the same text. If override_recipient_mobilenumber is also active, every number is the override number too, so nothing tells the items apart and every NotSentSms.batch_sms is None. Set external_id to avoid this.

Sms Class

The Sms class holds all the settings for an sms to be sent except the content. The content is passed to TramlClient as raw text when sending an sms. The properties for an Sms are:

Parameter Name Type Required Default Value Description
from_number string Yes The sender. Either alphanumeric (allowed chars are a-z0-9åäöæøü_- and whitespace and must be 2-11 chars long) or a fully qualified mobile number (+ followed by 6-15 digits, e.g. +46701740605)
destination_number string Yes The mobile number of the recipient must be country code prefixed
scheduled_send_date datetime No None Date and time if the message is scheduled. When omitted or set to None the message will be sent ASAP
max_parts int No 10 When the content is longer than 160 chars or special unicode char are used multiple SMS messages needs to be sent to transfer the whole content. With this setting you limit the number of sms messages used but it may result in truncating the content
delivery_timeout_hours int No 24 Timeout in hours for how long the sms should try to be delivered to the recipient
external_id string No Bind the sms to an external id. Echoed in batch results, so you can tell which input each entry belongs to.
merge_codes dict No {} A dictionary containing merge codes
options dict No {} A dictionary for additional payload parameters to Bedrock. It cannot override destination_number.

The CalendarLink class holds the settings to be able to generate a calendar link that can be inserted to your Email content. The start_date and end_date parameters supports timezone offset. Example given here.

Parameter Name Type Required Default Value Description
start_date datetime Yes The start time of the calendar booking
end_date datetime Yes The end time of the calendar booking
summary str No None The title of the calendar booking
description str No None A short description to insert into the body text of the calendar booking
location str No None The location of the calendar booking
reminder_before_event int No 0 Specify how many minutes before the event the recipient should recieve a reminder
url str No None The url of the event (a Teams meeting link for example)

MergeCodeModel Class

The MergeCodeModel class represents a merge code in a mail template.

Parameter Name Type Required Default Value Description
key str Yes The raw value of the merge code in the template. Example: {{ my_code }} or $$recipient.firstname$$
property_name str The name of the corresponding recipient property in lime-marketing. Only used for $$recipient.<property_name>$$-type merge codes

TramlEmailMessage Class

The TramlEmailMessage class can be used to parse and modify the email data from the TransactionMailContent property of the transactionmail.sent webhook payload.

Parameter Name Type Required Default Value Description
data str or bytes Yes The email data

Properties

html: Access the email html content as a BeautifulSoup object. Remember to use the property setter to update the content if you modify it yourself. Raises TramlError if the message doesn't have any valid html content.

raw_string: Access the email data as a raw unformatted string.

defects: Access possible parsing errors from the email data.

content_type: Get the content type of the message from the message headers.

model_as_formatted_string

Returns the email data as a formatted string. If you want to save the message to disk you should use this method.

create_lime_file

Returns a lime_file.File with the message data and the message's subject as the filename. The file will have an .eml extension. A subject that would make the filename longer than Lime's limit of 128 characters, where an emoji counts as two, is shortened, and a message without a subject gets the filename email.eml. Slashes and backslashes become dashes, control characters such as tabs become spaces, the invisible characters Lime rejects, such as a byte order mark or a bidi override, are removed, repeated spaces become one, and trailing dots and spaces are removed. The full subject is still in the file's content.

remove_opening_tracking_from_email

Modifies the email content to remove the opening tracking. Use this before saving the data if you do not want to trigger an open event when viewing the message in Lime.

remove_linkclick_tracking_from_email

Modifies the email content to remove the linkclick tracking. Use this before saving the data if you do not want to trigger a linkclick event when viewing the message in Lime.

Example usage:

# transactionmail.sent webhook endpoint
from limepkg_transactional_message_library.traml import TramlEmailMessage

def create_document_from_transactionmail_sent_payload(payload):
    byte_data = payload["TransactionMailContent"]
    traml_model = TramlEmailMessage(data=byte_data)
    # remove the opening tracking before saving the file
    # to not trigger a false opening event when viewing the message
    traml_model = traml_model.remove_opening_tracking_from_email()
    file = traml_model.create_lime_file()
    document: LimeObject = self.application.limetypes.document()
    document.properties.type.set_by_key("email")
    repo: FileStorage = document.properties.document.get_file_repo()
    s_file = repo.save(file)
    document.properties.document.attach(s_file)
    return document

Utils Module

The utils module contain helpers methods to help out with reoccurring tasks.

create_attachment_from_document()

Creates an TRAML attachment by getting the lime_file from the document Lime Type object

Parameter Name Type Description
document lime_type.LimeType An lime document object with a document lime_file property
Returns Description
Attachment A prepared TRAML attachment containing the lime_file data, file name and mime type

create_attachment_from_lime_file()

Creates an TRAML attachment from a lime_file.File

Parameter Name Type Description
lime_file lime_file.File An lime_file object
Returns Description
Attachment A prepared TRAML attachment containing the lime_file data, file name and mime type

Testing

When using TRAML it's likely that you have tests that test some logic which will trigger a TRAML email or sms to be sent. Of course, you don't want them to be sent for real and also not cause errors due to lack of configuration. This example shows how you can mock the Bedrock class sending emails or sms to Lime Marketing and assert that the correct emails and sms should have been sent.

import limepkg_transactional_message_library.traml as traml
import pytest
from unittest.mock import MagicMock
import datetime
import random


@pytest.fixture
def mock_traml_cfg(monkeypatch):
    app_cfg = traml.models.TramlApplicationConfig(
        api_key="00000000-0000-0000-0000-000000001337",
        api_url="https://example.com/bedrock/api/",
    )

    attr_name = "limepkg_transactional_message_library.config.traml_config.get_traml_application_config"
    monkeypatch.setattr(attr_name, MagicMock(return_value=app_cfg))

    runtime_cfg = traml.models.TramlRuntimeConfig()
    attr_name = "limepkg_transactional_message_library.config.traml_config.get_traml_runtime_config"
    monkeypatch.setattr(attr_name, MagicMock(return_value=runtime_cfg))

@pytest.fixture
def mock_bedrock(monkeypatch):
    mock_bedrock = MagicMock()
    class_name = "limepkg_transactional_message_library.traml.bedrock.Bedrock"
    monkeypatch.setattr(class_name, MagicMock(return_value=mock_bedrock))

    def email_to_response(*args, **kwargs):
        email: traml.models.Email = kwargs["email"]

        def _get_json():
            return {
                "TransactionMailId": random.randint(1, 1000),
                "RecipientName": email.recipient_name,
                "RecipientEmail": email.recipient_email,
                "FromName": email.from_name,
                "FromEmail": email.from_email,
                "SenderName": email.sender_name,
                "SenderEmail": email.sender_email,
                "ReplyTo": email.reply_to_email,
                "ExternalId": email.external_id,
                "Subject": email.subject,
                "TrackOpenings": email.track_openings,
                "TrackLinkClicks": email.track_link_clicks,
                "LinkBaseUrl": "",
                "ExcludeTotalOptouts": email.exclude_totaloptouts,
                "ExcludePublicationOptouts": email.exclude_publicationoptouts,
                "ExcludePreviousBounce": email.exclude_previousbounce,
                "IncludeEmailDataInWebhookPayload": email.include_email_data_in_webhook_payload,
                "IsInternalMail": False,
                "CreationDate": datetime.datetime.now(),
            }

        mocked_return_value = MagicMock()
        mocked_return_value.status_code = 200
        mocked_return_value.json = _get_json
        mocked_return_value.ok = True
        return mocked_return_value

    def sms_to_response(*args, **kwargs):
        sms: traml.models.Sms = kwargs["sms"]
        text: str = kwargs["text"]

        def _get_json():
            return {
                "TransactionSmsId": random.randint(1, 1000),
                "DestinationNumber": sms.destination_number,
                "FromNumber": sms.from_number,
                "MaxParts": sms.max_parts,
                "ScheduledSendTime": sms.scheduled_send_date,
                "Text": text,
                "DeliveryTimeoutHours": sms.delivery_timeout_hours,
                "CreationDate": datetime.datetime.now(),
            }

        mocked_return_value = MagicMock()
        mocked_return_value.status_code = 200
        mocked_return_value.json = _get_json
        mocked_return_value.ok = True
        return mocked_return_value

    def get_template(*args, **kwargs):
        name: str = kwargs["name"]

        def _get_json():
            return {"Name": name, "Id": random.randint(1, 1000)}

        mocked_return_value = MagicMock()
        mocked_return_value.status_code = 200
        mocked_return_value.json = _get_json
        mocked_return_value.ok = True
        return mocked_return_value

    mock_bedrock.send_transactional_mail.side_effect = email_to_response
    mock_bedrock.send_transactional_mail_by_template_id.side_effect = (
        email_to_response
    )
    mock_bedrock.send_transactional_sms.side_effect = sms_to_response
    mock_bedrock.get_mailtemplate_by_name.side_effect = get_template

    return mock_bedrock


def test_mail_sent(limeapp, mock_bedrock, mock_traml_cfg):
    # do stuff that trigger traml email/sms being sent
    # mymodule.notify_gillyweed_thieves()

    # this is what I expect should have been sent
    expected_email = traml.models.Email(
        from_name="Sirius Black",
        from_email="sirus.black@hogwarts.wiz",
        subject="Regarding my stolen Gillyweed",
        recipient_name="Harry Potter",
        recipient_email="harry.potter@hogwarts.wiz",
    )

    expected_sms = traml.models.Sms(
        from_number="Hogwarts", destination_number="+46704001337"
    )

    tc = traml.TramlClient(limeapp)

    template = tc.get_mail_template_by_name("Important information")

    sent_mail_template = tc.send_transactionmail_by_template(
        message=expected_email, template_id=template.id
    )

    sent_mail_content = tc.send_transactionmail(
        message=expected_email,
        html_content="html content",
        text_content="text content",
    )

    sent_sms = tc.send_sms(message=expected_sms, text="Return the gillyweed now!")

    assert sent_mail_template.recipient_email == expected_email.recipient_email
    assert sent_mail_content.recipient_email == expected_email.recipient_email
    assert sent_sms.destination_number == expected_sms.destination_number

    # assert bedrock sent email with the correct parameters
    mock_bedrock.send_transactional_mail_by_template_id.assert_any_call(
        email=expected_email, template_id=template.id
    )

    # assert bedrock sent email with the correct parameters
    mock_bedrock.send_transactional_mail.assert_any_call(
        email=expected_email,
        html_content="html content",
        text_content="text content",
    )

    # assert bedrock sent sms with the correct parameters
    mock_bedrock.send_transactional_sms.assert_any_call(
        sms=expected_sms, text="Return the gillyweed now!"
    )

    # use assert_called_with or assert_called_once_with to assert that the LAST 
    # or ONLY request to bedrock was that one

TransactionMail Webhooks

You can see a list of all available Transactionmail webhooks here: https://app.bwz.se/bedrock/example/webhook#events

Tracking sent transactional messages

The Transactional message (transactional_message) limetype included in TRAML can be used to track the status of sent transactional messages. It is possible to use a different limetype as long as it contains all the required properties. When using the "Send transactional message" automation step, a limeobject will automatically be created when the message has been sent to lime-marketing. When using TRAML in a python customization, you can manually create a tracking limeobject with the try_create_transactionmail_limeobject method found in the traml.tracking module.

transactional_message properties

Field Name Type Name (en) Required Default Value Description
transactionmail_id int transactionmail_id x ID of the message in lime-marketing
subject str Subject x Message subject
from_name str From name x Sender name
from_email str From email x Email address of sender
recipient_name str Recipient name x Recipient name
recipient_email str Recipient email x Email address of recipient
send_status option Status x empty Message status

send_status options

Key Name (en) Default
empty ' ' x
sent Sent
not_sent Not sent
delivered Delivered
opened Opened
link_clicked Link clicked

traml.tracking module

The tracking module contains methods to create limeobjects based on the response from lime-marketing when a transactional message has been sent

try_create_transactionmail_limeobject

Creates a limeobject from the send_transactionmail* response based on the limetype configured as the "Transactionmail" in Lime Admin. The send_status property will be set to sent

Parameter Name Type Description
sent_model traml.models.SentTransactionMailModel A model containing the data of the sent Email message
application LimeApplication Current Lime Application
Returns Description
traml.tracking.TransactionMail or None A model representing the created limobject if it was created successfully. Otherwise None.