Learn how to configure email node, design emails, set up custom domains, and more.
Troubleshooting Email Activity
By effectively understanding email-related issues you can ensure that your flow designs deliver a consistent experience for recipients.
This article outlines all email activity events, possible email-channel specific failures, and other generic failures you may encounter.
Understanding email activity
Each email sent through Pendula generates activity that lets you track its progress from start to finish. These activities provide valuable insights into email behaviour, such as delivery confirmation, open events, or reasons for failure.
Email activity events
-
Action started: The email node has started. It contains information about the node, its configuration, and inputs.
-
Message queued: The email has been queued for handing to the gateway. Viewing this activity will show rich details, such as the HTML of the email, sender and recipient, and optionally attachment filenames.
-
Message passed to gateway: The email has been handed to the gateway for delivery.
-
Message delivered: The email has been confirmed as delivered to the recipient.
-
Message opened: The email has been opened by the recipient.
-
Message clicked: A link in the email has been clicked. Subsequent clicks are also recorded.
-
Message rejected: The email was rejected by the gateway. Possible reasons include incorrect tenant setup.
-
Message failed: The email failed to be delivered. This occurs when the gateway attempts delivery but encounters an error. Possible reasons include invalid email address, spam filtering, full mailbox, unsubscribed/blocked, attachment size exceeded, or a bounced email.
-
Message sent: The email has been sent from the gateway to the recipient.
-
Message validation failed: The email was rejected due to an invalid format, such as a missing or incorrectly formatted email address.
-
Action ended: The email node has ended with either a 'success' or 'failure' result.
Email channel-specific failure messages
-
Invalid email address: The email address format is incorrect or missing.
-
Invalid domain: The domain in the email address does not exist or is unreachable.
-
Invalid content: The email content does not comply with acceptable standards.
-
Recipient’s mailbox full: The recipient's mailbox is full and cannot accept new emails.
-
Recipient’s mailbox unavailable: The recipient's mailbox is temporarily unavailable.
-
Content too large for recipient: The combined size of the email and its attachments exceeds the recipient’s limit.
-
Email transaction failed: A failure occurred during the email transaction process.
-
Email was cancelled: The email sending process was cancelled before delivery.
-
Expired (end of retry period): The gateway stopped retrying to send the email after the retry period ended.
-
Unauthorized to send to recipient: The sender does not have permission to send an email to the recipient.
-
Unable to connect to email server: The email server could not be reached for delivery.
-
Email has been blocked: The email was blocked due to spam or other restrictions.
-
Expired, email not processed: The email expired before it could be processed or sent.
-
Bad email sender address: The sender's email address is invalid.
-
Email address does not exist: The specified email address does not exist.
-
Attachment(s) rejected: One or more attachments were rejected and could not be processed.
-
Recipient had unsubscribed: The recipient has unsubscribed and cannot receive emails.
-
Rejected: The email was rejected during processing.
Other and generic failures
-
In error: An unspecified error occurred during the email delivery process.
-
Could not render template: The email template could not be processed for rendering.
-
Could not render document: A document attached to the email could not be rendered.
-
Could not retrieve document: A document attachment could not be retrieved from its source.
-
Input data too large: The data provided for the email exceeds acceptable limits.
-
Bad carrier configuration: Issues with carrier configuration prevented email submission.
-
Could not submit to carrier: The email could not be sent to the carrier for delivery.
-
Missing recipient contact point: The recipient's contact point is missing.
-
No suitable carrier configured: No suitable carrier is configured to handle the message.
-
Could not collect statuses from carrier: The gateway could not collect delivery statuses from the carrier.
-
Fail to deliver: A generic failure indicating the email was not successfully delivered.
By understanding these activities and their associated failure types, you can efficiently troubleshoot issues and ensure optimal email delivery.
For additional guidance, you may find these related articles helpful:
To understand how these troubleshooting tips align with activity, see What is Activity.
Working with Email
Effective email communication is essential for engaging customers and achieving business goals. This article covers best practices for writing and sending outbound emails, emphasising the use of Pendula for personalisation, design, testing, and security.
General guidelines for writing emails
- Keep subject lines concise and relevant, and use action-oriented language to encourage recipients to open the email. Avoid using all caps or excessive punctuation, which can trigger spam filters
- Focus on delivering one main message or call to action per email. Use short paragraphs, bullet points, and clear headings to make the content easy to read and understand.
- Maintain a friendly yet professional tone. Avoid using jargon or overly complex language. Tailor the tone to match your brand's voice while ensuring it resonates with your audience.
- Include a clear and conspicuous unsubscribe link in every email and honour opt-out requests promptly, adhering to legal requirements where applicable, such as the five working days timeframe in Australia. Ensure that your email header information, including the "From" and "Reply-To" addresses, is accurate and not misleading.
Personalisation with merge fields
Using merge fields in emails allows for dynamic personalisation, making messages feel more relevant and engaging to each recipient. Merge fields automatically insert specific data from your database into your email templates, such as names, order numbers, or other details.
Hello {{FirstName}},
This is a reminder for your appointment on {{AppointmentDate}} at {{AppointmentTime}}.
For more details, see Working with merge fields and Designing emails with Outbound Email node
Using the email builder
In Pendula, there are two primary methods for designing emails within the Outbound Email Node: building from scratch using an email builder with a drag-and-drop interface or utilising custom HTML code. While custom HTML offers flexibility, it may cause visual discrepancies across different email clients. For instance, background images in custom HTML may not render correctly in Outlook, which defaults to a white background unless otherwise configured. To ensure visual consistency, we recommend using Pendula's email builder.
For more details, see Outcome Email Node and Designing emails with Outbound Email node
Optimising email campaigns with A/B Testing
A/B testing is a powerful method for optimising your email campaigns by comparing different versions to see which performs better. In Pendula, you can use the Criteria Filter to implement A/B testing.
The example below demonstrates the use of a Criteria Filter in an A/B testing scenario, initiated by a form submission. The Criteria Filter divides customers into two groups based on predefined criteria. Customers who meet the criteria for Group A receive Email A. Conversely, those who do not meet the criteria for Group A and fall into Group B receive Email B.
This setup allows for a direct comparison between different marketing approaches. By analysing the results from both groups, you can determine which email version is more effective in achieving your goals, such as higher open rates or conversion rates.
For a detailed guide, see Criteria Filter and Criteria Split
Ensuring email delivery coverage
Email delivery events provide critical insights into the performance of your email communications. Key events include clicks, opens, deliveries, and bounces (with soft bounces indicating temporary issues and hard bounces indicating permanent ones).
In Pendula, the "Outcomes" tab in the Outbound Email Node allows you to configure the workflow path based on these events. The "Sent" path is followed if no failure is detected within the default 10-minute wait time or if the email is opened or clicked. The "Rejected" path is followed if a failure occurs within the wait time and can be toggled on in the node settings.
Merge fields in the subsequent nodes help track and personalise email delivery outcomes. The Outcome
field indicates whether the email was successfully delivered (success
) or failed (failure
), and the Outcome Reason
field provides specific details (e.g., opened
, failed: [reason]
, rejected
).
By configuring these outcomes and using merge fields, you ensure comprehensive email delivery coverage, effectively managing both successful deliveries and failures.
For more details, see Outcome Email Node
Email security
Ensuring email security with SPF, DKIM, and DMARC is essential for preventing spoofing and phishing attacks. SPF verifies that incoming mail comes from authorised hosts, DKIM uses cryptographic signatures to ensure email integrity, and DMARC instructs mail servers on handling emails that fail SPF or DKIM checks.
Using a custom domain allows you to configure these records, enhancing your email credibility and deliverability. With Pendula, SPF is pre-configured, DKIM involves adding CNAME records to your DNS, and DMARC requires setting up a TXT record for additional security and reporting.
For more information, see Setting up Custom Domains for secure email delivery using Pendula
Outbound email
The outbound email node sends a single email with optional attachments. There are outcomes for 'sent' and optionally 'rejected', allowing you to continue an experience even if there is a sending failure or bounce. You can learn more about this in the outcomes section below.
Configuring the action
Sender Details
- Sender name: The name that appears to recipients, identifying the sender of the message.
- From address: The email address that appears as the sender when recipients receive the email. The 'From address' must be a verified email address, or from a verified domain.
Contact Support to set up a custom From address.
Email details
- Recipient: The individual who will receive the email. Merge fields may be referenced here.
- Email subject: A brief description or summary that conveys the purpose or content of the email to the recipient. Merge fields may be referenced here.
Attachments
Uploading attachments
Use the attachments tab to manage attachments for an outbound email. This tab allows you to upload files from your local machine as attachments, and allows you to view (download) existing attachments; as well as delete them.
You can upload as many attachments as you like, however, the email design and attachment size combined must be less than 10MB to send successfully. As email size can change depending on merge fields used, you must take this into account when designing an email with attachments.
We check attachments before uploading successfully. The cases where a file will not be uploaded successfully include:
- File size too large. You must upload files less than 10MB.
- File type not supported. We support TXT, HTML, ICS, JPEG, PNG, GIF, WebM, MP4, MPEG, PDF, DOC, DOCX, XLS, and XLSX.
- File name taken. Please rename your file and upload again, or delete the existing file.
- Server unavailable. Please contact support.
Attachment indicator
On the flow canvas, outbound email nodes that have attachments are denoted by a circular blue paperclip badge on the node icon:
In the case that you finish designing your flow that has outbound email nodes with attachments, try to activate the flow, and are presented with this message:
- The following attachments are unavailable and can't be accessed...
You will need to either delete the listed attachments, or upload them again to proceed and activate the flow.
Designing email
Design your email choosing from two options. Email message bodies are limited to a maximum of 255KB, and will be rejected if the limit is exceeded.
Build from scratch
Use the email builder to design your email. This tool allows you to edit, drag, and drop content into the email canvas. The design panel includes sections for Content, Blocks, Body, and Images. You can move items around by hovering over them and using the pan icon, and you can use the redo/undo buttons to adjust your design. Once the email is built to your satisfaction, click the Save icon.
Use HTML code
If you prefer to use custom HTML code, select the HTML option and paste your code into the text field. You can preview the template before saving the node.
Export HTML
After designing an email, the HTML can be exported (downloaded) easily by clicking the 'Export HTML' button:
Note that using custom HTML may cause visual discrepancies across different email clients. Pendula recommends using the email builder for consistent visual results.
For a detailed guide on designing emails, see Designing emails for Outbound Email node.
Outcomes
The outbound email node can send recipients down different flow paths based on email delivery; we call these outcomes, and you can manage these on the Outcomes tab.
Sent
The outbound email node waits for failures for 10 minutes before a 'sent' outcome is determined. This wait time is configurable, and exists to cater for the inconsistencies in email client failure / delivery reporting.
If the email is opened or a link within is clicked by a recipient, a 'sent' outcome is determined immediately.
The experience will continue on this path if no failure notifications are received within the default wait time of 10 minutes, or immediately if the email is opened or a link is clicked. An opened or clicked email event is confirmation that the email was sent successfully.
Wait time configuration for sent path
This configurable wait time exists to monitor for any sending failures that may occur after the email has been sent to a carrier for delivery. You can change the wait time by clicking on the pencil icon. When edited, the 'Rejected' wait time will be synced too.
For example, if no sending failures occur within the wait time, the experience will continue down the 'Sent' path. If the email is opened or a link is clicked during this wait time, the experience will continue the experience down the 'Sent path'.
Configuring the wait frame for Soft Bounces
Soft bounces occur when an email cannot be delivered temporarily, often due to a full inbox or server issues. To cater for soft bounces, we recommend setting the wait time to 960 minutes (16 hours) within Pendula. This gives the carrier enough time to try sending the email again after a soft bounce, and progress an experience based on the final delivery status (Sent or Rejected). Keep in mind that if a recipient opens the email or clicks a link, the process advances along the 'Sent' path immediately.
Rejected path
The experience will either end or continue on this path (depending on its toggle settings) if a sending failure has occurred within the default wait time of 10 minutes.
If a sending failure occurs, a 'rejected' outcome is determined, and you can choose to continue the experience down the 'rejected' path; if configured.
When toggled off, the experience will end and exit the flow.
When toggled on, the Rejected path will be visible on the canvas, where you can further configure the experience on this path. You can refer to Merge fields section below to personalise experiences continuing on this path.
Wait time configuration for reject path
This configurable wait time exists to monitor for any sending failures that may occur after the email has been sent to a carrier for delivery. You can change the wait time by clicking on the pencil icon. When edited, the 'Sent' wait time will be synced too.
For example, if a sending failure occurs within the default 10 minute wait time, the experience will continue down the 'Rejected' path.
Merge field explorer
In later nodes, when viewing the available merge fields for the Conversation node in merge field explorer you can expect to see the below.
Only one outcomeReason will be displayed. For example, if your email continues on the 'Sent' path, you will see either "opened" or "success-timeout", not a combination of these outcomes.
Mergefield name | Description | Possible outputs | Definition and examples |
outcome | The final email delivery status (string) | success |
The message was sent to the carrier for delivery, and no failure notifications were received during the wait time period, OR the email was opened. |
failure |
The message failed to be sent. See outcomeReason (below) for possible reasons. The experience will continue along the Rejected path (if configured) or exit the flow. |
||
outcomeReason | The reason for a message delivery (string) | opened |
The email has been opened by the recipient. Please note different email clients and devices handle what is considered an 'opened' email differently. The experience will continue on the 'Sent' path, and skip the wait time. |
failed: [reason] |
The carrier has accepted the email message, but encountered an error while sending it to the recipient. The experience will continue along the Rejected path (if configured) or exit the flow. |
||
failed-normalization |
The recipient's email is invalid. Ensure it is present and in the correct email format. The experience will continue along the Rejected path (if configured) or exit the flow. |
||
other-error |
Another error was found while sending the email message to the recipient. The experience will continue along the Rejected path (if configured) or exit the flow. |
||
rejected |
The carrier has rejected the email. The experience will continue along the Rejected path (if configured) or exit the flow. |
||
success-timeout |
The email message was sent to a carrier for delivery, and no failure notifications were received during the wait time. The experience will continue on the 'Sent' path. |
||
validation-error |
An invalid value was found in the node. Ensure your flow error warnings have been addressed. The experience will continue along the Rejected path (if configured) or exit the flow. |
Adding a ‘View In Browser’ link to an email
Assumed knowledge
Complete overview of the Flow Builder
Designing emails with Outbound Email node
Adding a "View in Browser" link to your email template is a helpful feature that allows your recipients to view your email content in their web browser. This is particularly useful for users with email clients that may not fully support your design or for those who prefer to read their emails online.
In this article, we'll guide you through the steps to add a "View in Browser" link using a custom HTML block in Pendula.
Create or edit an existing email node in a Pendula flow
Select the flow with an email template you would like to add the browser link to, or create a new flow from the Flows homepage.
In the flow builder Canvas, open the email node settings configuration. For an existing email template, select ‘Open template’. If you’re building a new template, select the ‘Build from scratch’ option.
Add a custom HTML block and link code
In the template editor, locate the area where you want to add the "View in Browser" link. It's common to place this link at the top of the email for easy access.
While the top of the email is a common location, you can place the link anywhere it seems most appropriate for your audience.
On the right hand side of the email builder, find the ‘HTML’ content block. Drag this into the part of the template you would like the link to be.
In the custom HTML block, enter the following code snippet:
<a pendula:external-view>View this email in your browser</a>
This code creates a dynamic "View in Browser" link that Pendula will generate for each email recipient, allowing them to view the email in a web browser.
You can style the link using basic HTML and CSS to match your brand’s design. You can wrap the link element in another element for styling, or add styling directly to the <a> tag. For example:<a pendula:external-view style="color: #0073e6; text-decoration: none;">View
this email in your browser</a>
Save and test your template
After inserting the code, ensure your email template looks as expected. Click on "Save" to apply the changes made to the template.
Before sending your campaign, it’s essential to test your email by sending a test email. Open the test email in your inbox and click on the "View in Browser" link to confirm it redirects to the online version of your email.
Ensure you test the "View in Browser" link across different email clients and devices to ensure compatibility and ease of use.
By following these steps, you can effortlessly enhance the accessibility of your emails within Pendula, ensuring a seamless experience for your recipients regardless of their email client.
-
<% categories.forEach(function(category) { %>
<%= partial('partial-article-list-sections', {
id: 'category-' + category.id,
parentId: '#sidebar-navigation',
sections: category.sections,
activeCategoryId: activeCategoryId,
activeSectionId: activeSectionId,
activeArticleId: activeArticleId,
partial: partial
}) %>
<% }); %>
-
<% sections.forEach(function(section) { %>
-
<%= partial('partial-article-list-sections', {
id: 'section-' + section.id,
parentId: '#' + id,
sections: section.sections,
activeCategoryId: activeCategoryId,
activeSectionId: activeSectionId,
activeArticleId: activeArticleId,
partial: partial
}) %>
<% if (section.articles.length) { %>
-
<% section.articles.forEach(function(article) { %>
- <%= article.title %> <% }); %>
<% }); %>