# Getting started with Ubiquity Get set up, learn the platform, and send your first campaign. Ubiquity is a marketing automation platform that helps you use your data to deliver more relevant customer experiences. Get started by setting up your account, learning how the platform works, and sending your first campaign. This section guides you through the key steps to get up and running quickly. Start with the onboarding checklist, or explore the documentation to learn more about specific features. Need some help with Ubiquity? Or interested to learn more about how it works? Click [here](https://comms.ubiquity.co.nz/surveys/8j3g0vxv81gn3fbl13h44gdcx803vwh4sd8vqlv6q22jkmbmp7k4nxpt8nc0) to register for online drop-in training now.
:window:Platform overviewLearn how Ubiquity works and how everything fits together.
:list:Onboarding checklistFollow the steps to get set up and ready to send.
:message:Your first campaignCreate and send your first campaign.
:user:User managementManage users and control account access.
:gear:Account configurationSet up your account settings and preferences.
:check:Acceptable use policyUnderstand what Ubiquity can and cannot be used for.
:lock:Access and authenticationManage user access and authentication.
:pager:Security and trustOverview of Ubiquity’s approach to security.
:universal-access:Privacy policyLearn how your data is handled and protected.
:timer:Service levelsHow Ubiquity monitors the platform and prioritises incidents.
:window-restore:Data backup and recoveryHow your data is protected and recovered in the event of an outage.
:clipboard-list:Platform TrainingRegister for a complementary training session or book bespoke.
# Platform overview Learn how Ubiquity works and how everything fits together. Ubiquity is a cloud-based marketing automation and communications platform that helps organisations manage customer data, create personalised content, and deliver communications across multiple channels from one place. It is designed to help teams send the right message to the right person at the right time, using real customer data and local support. At its core, Ubiquity brings together data, audience management, content creation, and message delivery. Customer, transactional, and behavioural data can be centralised in one platform, then used to segment audiences, personalise communications, automate journeys, and measure performance. Ubiquity supports multi-channel engagement across email, TXT/SMS, push, social and online experiences. It also includes inbound data capture tools such as forms, surveys and event registration, helping you collect information directly from your audience and use it within your communications and workflows. Security and reliability are core to how Ubiquity is designed and operated. The platform is ISO/IEC 27001:2022 certified, reflecting a structured and audited approach to managing information security. We apply a security-by-design approach across the platform to ensure customer data is handled appropriately and the service remains stable and dependable. Alongside the platform itself, Ubiquity provides local support and expertise to help you get the most from your customer communications. Our team works closely with you to ensure the platform fits your needs and continues to deliver value over time.
A diagram showing how UbiQuity connects data sources — including CRM/Billing, Website, DWH, and Mobile App — through data integration methods such as API, Connectors, and Manual Import into a central Database and Transactional Records store. Data capture tools including Forms, Events, Surveys, and SMS feed into the same database. From there, outbound channels — Email, Push, SMS, and Social — send communications to customers, with behavioural and response data feeding back into the database. Other channels including Direct Mail, Website, and Digital Signage are shown as optional outputs.

How Ubiquity connects your data, outbound channels, and customer capture tools in one platform.

# Onboarding checklist Follow the steps to get set up and ready to send. ### Overview Onboarding with UbiQuity is a guided process designed to set you up for long-term success. Rather than a self-service setup, you’ll work closely with a UbiQuity Marketing Automation Consultant, who will guide you through each stage, from initial discovery through to your first campaign and beyond. The process is flexible and tailored to your organisation, depending on your data, goals, and current marketing automation capabilities. *** ### What to expect Your onboarding will typically move through the following stages: * **Discovery:** Understanding your current setup, data, and marketing goals * **Setup:** Configuring your account, data, and core platform features * **First deployment:** Launching your first campaign with guidance and support * **Handover:** Transitioning to your team for ongoing use *** ### Your onboarding checklist Use the checklist below to understand what’s involved and what may be required from your side. #### 1. Discovery and planning Work with your UbiQuity consultant to define your approach * Provide an overview of your current systems and data sources * Outline your marketing goals and key use cases * Confirm which channels you plan to use (e.g. email, SMS) * Align on how your data should be structured in UbiQuity #### 2. Data preparation Ensure your data is ready for import and use * Prepare your core contact data (e.g. customers, subscribers) * Identify any additional datasets (e.g. transactions, events) * Confirm how records should be uniquely identified (e.g. email or customer ID) * Review data quality (duplicates, missing fields, inconsistencies) #### 3. Account and platform setup Your UbiQuity team will configure your environment * Account creation and access setup * User creation and permissions * Database configuration * Initial data import #### 4. Sending domain and email setup Set up your email infrastructure to ensure deliverability * Provide your sending domain details * Complete DNS configuration (e.g. CNAME records) * Enable email authentication (e.g. DKIM) * Align on sending practices to protect reputation #### 5. Templates and assets Create the building blocks for your campaigns * Set up branded email templates * Configure forms, surveys, or layouts if required * Review and approve initial designs #### 6. Initial configuration (if applicable) Depending on your requirements, additional setup may include * Automated journeys or campaign * Data integrations or connectors * Preference centres or subscription management #### 7. First campaign Launch your first campaign with guidance * Work with your consultant to prepare your first send * Validate data, audience, and content * Execute your first campaign (often with UbiQuity support) * Review results and confirm everything is working as expected #### 8. Handover and ongoing use Transition to your team for day-to-day usage * Confirm key users and platform ownership * Ensure at least one “super user” is established * Provide training and guidance for ongoing use * Align on next steps and future use cases *** ### Important notes **Onboarding is tailored**\ The exact process will vary depending on your organisation’s size, data, and requirements. **Data drives success**\ Well-structured, clean data is the most important factor in a successful onboarding. **Guided, not self-service**\ Your UbiQuity consultant will support you throughout and you’re not expected to do this alone. # Your first campaign A step-by-step guide to creating and sending your first email campaign in UbiQuity. UbiQuity's Email module is the best place to start. Before sending your first campaign, make sure your database is configured for email and you have contacts ready to send to — see First Time Setup if you haven't done this yet. Once you're set up, there are a few different ways to send depending on what you need. *** ### Creating your first email [**Mailouts**](/documentation/channels/email) — The simplest place to start. Create a one-off email, target the right contacts using filters, and schedule your send. [**Automated Mailouts**](/documentation/channels/email/creating-an-automated-mailout) — If you want emails to send automatically based on dates or contact data — such as a welcome email or a birthday message — set up an Automated Mailout. Not sure which to use? Start with a standard Mailout to get familiar with the platform, then explore Automated Mailouts once you're comfortable. *** ### Other channels and tools Once you're familiar with email, UbiQuity has a range of other tools to help you engage with your contacts. * [**Forms**](/documentation/data-capture/forms) — Capture contact data and trigger follow-up emails * [**Surveys**](/documentation/data-capture/surveys) — Collect responses and trigger communications based on answers * [**Events**](/documentation/data-capture/events) — Manage event registrations and send event-related communications * [**TXT**](/documentation/channels/txt) — Send one-off or automated TXT messages to contacts in your database * [**Push**](/documentation/channels/push) — Send push notifications to users of your mobile app # User management Manage users and control account access. ### Overview User management in UbiQuity allows you to control who has access to your account and what they can do within the platform. You can create users, assign permissions, and manage access levels to ensure the right people have the right level of control — whether they’re building campaigns, managing data, or administering the platform. {% hint style="info" %} **Note:** Only users with **Super User** access can manage users and permissions. {% endhint %} *** ### Managing users User management is available within your Users section in account settings, where Super Users can view and manage all users associated with your organisation. From here, you can: * View all active users * Add new users * Edit existing users * Deactivate users who no longer require access *** ### Adding a new user To create a new user: * Navigate to the account you wish to add them to * Go to the Users section in your account settings * Select **Create New User** * Enter the user’s details (e.g. name, email address, mobile) * Assign the appropriate permissions * Create the user The user will then be sent an email with first-time login instructions. This will enable them to access UbiQuity based on the permissions assigned. If you have enabled two-factor authentication, they will need their mobile phone to log in. Accounts are structured in folders. If the user already has a login to the parent account then you can copy a user from a parent account. The user can then access multiple UbiQuity accounts with a single email address and password. ![](/files/bdEAymxIHyg2JaLkA44w) If the user was created in a child account and you need them to have access to other accounts that are not under that child account then you'll need to delete the user and create them in the parent account. Once they are in the parent they can be added to as many child accounts as needed. Permissions are set for each user individually for each account they have access to. *** ### Editing users You can update a user’s details or permissions at any time. This includes:
Email AddressUsed for logging into UbiQuity and must be unique for each UbiQuity user. This is the email address that we will email if the user needs to reset their password and also the email address that email previews will default to sending to.
First NameUsed in various locations through UbiQuity such as in the top right corner to tell you who you're currently logged in as.
Last NameUsed in various locations through UbiQuity such as in the top right corner to tell you who you're currently logged in as.
Mobile NumberUsed for Two Factor Authentication which adds extra security when logging into UbiQuity. If you change your mobile number then UbiQuity may send you a new code next time you log in.
Home AccountThe account that you will be automatically logged into when logging into UbiQuity. It's a good idea to set this to the account you use most often.
Changes take effect immediately. *** ### Deactivating users When a user no longer requires access, they should be deactivated rather than deleted. Deactivating a user: * Removes their access to the platform * Preserves historical activity and audit data * Helps maintain security and compliance *** ### Permissions and access control Permissions define what each user can see and do within UbiQuity. These may include access to: * Campaign creation and sending * Data and database management * Forms, surveys, and events * Reporting and analytics * Administrative settings You can assign permissions based on each user’s role within your organisation. The full list of available permissions are below. #### **Database Permissions** | Database administrator | Full database control | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Create, edit and delete database fields | | | View contacts |

Users without this permission can still view contacts when previewing email templates, surveys and events

| | Add and edit contacts |

Requires view contacts permission

| | Delete contacts |

Requires view contacts permission

| #### **Forms Permissions** | Form administrator |

Full forms control including:

| | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Insert form links throughout UbiQuity | | #### **Emails Permissions** | Email administrator | Full email control | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create, edit and delete mailouts and view reports | | | Send mailouts |

Requires create mailouts permission

| | Create, edit and delete automated mailouts and view reports | | | Send automated mailouts |

Requires create automated mailouts permission

| | Create, edit and delete email templates | | #### **Surveys Permissions** | Survey administrator |

Full survey control plus:

| | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create, edit and delete surveys and triggered emails | | | Activate and deactivate surveys |

Requires create survey permission

| | View and download responses and create, edit and delete reports | | | Insert survey links throughout UbiQuity | | #### **Events Permissions** | Event administrator | Full event control | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Create, edit and delete events and triggered emails | | | Activate and deactivate events |

Requires create event permission

| | View and download registrations, and view reports | | | Insert event links throughout UbiQuity | | #### **TXT Programmes Permissions** | TXT administrator | Full TXT control | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create, edit, archive and delete programmes | | | Activate and deactivate programmes |

Requires create programme permission

| | Create, edit and delete TXT outs and view reports | | | Send TXT outs |

Requires create TXT out permission

| | Create, edit and delete automated TXT outs and view reports | | | Send automated TXT outs |

Requires create automated TXT out permission

| | View programme messages and reports | | #### **Push Permissions** | Push administrator | Full push control | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Create, edit and delete apps | | | View devices | | | Create, edit and delete notifications | | | Send notifications |

Requires create notification permission

| | Create, edit and delete automated notifications | | | Send automated notifications |

Requires create automated notification permission

| | Create, edit and delete notification templates | | #### **Campaigns Permissions** | Campaign administrator |

Full Campaign control, including:

| | ---------------------- | ------------------------------------------------------------------------------------------- | #### **Layouts Permissions** | Layout administrator |

Full Layout control, including:

| | -------------------- | --------------------------------------------------------------------------------------- | #### **Social Permissions** | Social administrator |

Full Social control, including:

| | -------------------- | ------------------------------------------------------------------------------------------------ | *** ### Super Users Super Users have elevated access and are responsible for managing users and permissions within your account. They can: * Create and manage users * Assign and update permissions * Control access to key areas of the platform * Create API keys for developers to use {% hint style="info" %} **Best practice:**\ Ensure you have at least one, and ideally a small number of trusted Super Users within your organisation. {% endhint %} *** ### Best practices To keep your account secure and well managed: **Limit Super User access**\ Only assign Super User permissions to trusted users who require it **Use named user accounts**\ Avoid shared logins to maintain accountability **Review access regularly**\ Periodically check that users and permissions are still appropriate **Deactivate unused accounts**\ Remove access promptly when users leave or no longer need access *** ### Security considerations User access is a key part of your overall platform security. Ensure that: * Strong passwords are used * Two-factor authentication (2FA) is enabled if your account does not have SSO enabled * Access is granted on a least-privilege basis *** ### Need help? If you need help managing users or understanding permissions, contact your UbiQuity consultant or support team. # Account configuration Settings and configuration options for your UbiQuity account. Most of these are managed by account admins or the UbiQuity team. Account configuration covers the technical setup that underpins how your UbiQuity account sends and tracks communications. Some settings can be managed directly by account admins, while others require the UbiQuity team to configure on your behalf. *** ### Registered domains A registered domain is the sending domain your UbiQuity account uses to send emails — for example, `email.yourcompany.co.nz`. Setting up a registered domain ensures your emails are correctly authenticated and improves deliverability. All new clients are required to configure a set of DNS records with their DNS provider before UbiQuity can send emails on their behalf. The same process applies to existing clients setting up an additional sending domain. UbiQuity will provide the specific DNS record values for your domain. The records you will need to configure are as follows. #### DKIM (DomainKeys Identified Mail) DKIM adds a digital signature to your outgoing emails, allowing receiving mail servers to verify that the email genuinely came from you and has not been tampered with in transit. Three DKIM CNAME records are required per sending domain. #### DMARC (Domain-based Message Authentication, Reporting & Conformance) DMARC tells email providers how to handle messages that fail authentication checks — for example, whether to reject or quarantine them. It also provides reporting on messages sent from your domain. A single DMARC TXT record is required. #### Custom MailFrom (SMTP / Return-Path) The Custom MailFrom record changes the technical sender address used behind the scenes, so all parts of the email appear to come from your domain rather than the underlying sending service. This supports DMARC alignment and improves deliverability. A CNAME record is required. #### DNS records summary Once UbiQuity provides your specific values, you will need to create the following records with your DNS provider: | What | Type | Name | Value | | --------------- | ----- | -------------------------------------------------- | --------------------------------------------- | | DKIM | CNAME | `ubiquity-dkim1._domainkey.email.yourdomain.co.nz` | Provided by UbiQuity | | DKIM | CNAME | `ubiquity-dkim2._domainkey.email.yourdomain.co.nz` | Provided by UbiQuity | | DKIM | CNAME | `ubiquity-dkim3._domainkey.email.yourdomain.co.nz` | Provided by UbiQuity | | DMARC | TXT | `_dmarc.email.yourdomain.co.nz` | `v=DMARC1; p=reject; pct=100; fo=1; ri=3600;` | | Custom MailFrom | CNAME | `smtp.email.yourdomain.co.nz` | Provided by UbiQuity | Contact UbiQuity to begin the process of registering a sending domain for your account. *** ### Custom host headers By default, tracked links, View Online links, and form, survey, and event URLs in your UbiQuity emails use a UbiQuity domain. A custom host header replaces this with a branded domain of your choosing — for example, `email.yourcompany.co.nz` instead of `engage.ubiquity.co.nz`. Setting up a custom host header requires two additional DNS records to be created with your DNS provider. #### Host Header (CNAME) A CNAME record that points your custom subdomain to the UbiQuity platform. UbiQuity maps the request to the correct account internally based on your account settings. #### SSL/TLS Certificate An SSL/TLS certificate encrypts the connection and proves the domain is legitimate, ensuring visitors are communicating with the real site securely. A CNAME validation record is required to issue the certificate. UbiQuity manages SSL/TLS certificates on behalf of clients through ACM (Amazon Certificate Manager). #### DNS records summary | What | Type | Name | Value | | ------------------- | ----- | ------------------------ | ------------------------------ | | Host Header | CNAME | `email.yourdomain.co.nz` | `custom.engage.ubiquity.co.nz` | | SSL/TLS Certificate | CNAME | Provided by UbiQuity | Provided by UbiQuity | Custom host headers are configured entirely by the UbiQuity team once the DNS records are in place. Contact UbiQuity to get started. *** ### Single Sign-On (SSO) UbiQuity supports Single Sign-On via OpenID Connect (OIDC), allowing your users to log in to UbiQuity using your organisation's existing identity provider. SSO configuration requires setup on both your side and UbiQuity's side. Contact UbiQuity to discuss enabling SSO for your account. *** ### Alternate Contact Service Messaging (ACSM) Alternate Contact Service Messaging allows you to send service messages to a contact other than the one who generated the interaction. This is useful in situations where a third party needs to receive communications on behalf of the original contact. A common example is group accommodation bookings — the person managing the booking would typically receive all service messages, rather than each individual whose booking is being managed. ACSM allows those messages to be sent directly to the relevant individual instead. ACSM can send to either an email address for a database contact or a relevant transactional row. Once enabled for your account, an additional **To** field appears on the Content and Preview screen of the email creation process. This field defines the alternate contact the message will be sent to, linked to the original contact via a secondary email field in the database or an additional transactional row. ACSM requires setup by the UbiQuity team. Contact UbiQuity if you would like to enable this for your account. # Acceptable use policy Guidelines for using UbiQuity responsibly, including permitted use and prohibited activities. This Acceptable Use Policy outlines how UbiQuity can be used responsibly and safely. By using UbiQuity, you agree to use the platform in a way that complies with applicable laws and does not negatively impact other users, systems, or the platform itself. *** ### Responsible use You must use UbiQuity in a lawful and responsible manner. This includes: * Complying with all applicable laws and regulations * Respecting the privacy and rights of individuals * Ensuring you have appropriate permission or consent to contact recipients * Using accurate and truthful information in your communications * Maintaining the security of your account and access credentials *** ### Prohibited use You must not use UbiQuity to: * Send unsolicited, misleading, or spam communications * Distribute malicious code, viruses, or harmful content * Send content that is unlawful, abusive, defamatory, or deceptive * Attempt to gain unauthorised access to any system, account, or data * Probe, scan, or test the vulnerability of the platform or related systems * Interfere with or disrupt the performance, integrity, or security of the platform * Use the platform in a way that could damage UbiQuity’s infrastructure or reputation * Impersonate another person or organisation, or misrepresent your identity *** ### Data and consent You are responsible for ensuring that: * You have a lawful basis to collect, use, and process personal data * All data is handled in accordance with applicable privacy and data protection laws * Recipients have provided appropriate consent where required * Opt-out and unsubscribe requests are honoured promptly * Data uploaded to the platform is accurate and up to date *** ### Platform integrity and security You must not use UbiQuity in a way that places unreasonable load or risk on the platform. This includes: * Attempting to bypass system limits, controls, or security measures * Using automated processes in a way that disrupts normal platform operation * Introducing any material that may compromise system performance or security *** ### Enforcement We may monitor and investigate any suspected misuse of the platform. Where necessary, this may result in: * Suspension or restriction of access * Removal of content or data * Termination of accounts in serious or repeated cases We may also take further action where required to comply with legal or regulatory obligations. *** ### Updates This policy may be updated from time to time to reflect changes in legal requirements, platform capabilities, or usage patterns. # Access and authentication Manage user access and authentication to keep your UbiQuity account secure. ### User access Access to UbiQuity is managed through individual user accounts. We recommend: * Creating a unique account for each user * Avoiding shared logins * Removing access promptly when a user no longer requires it This ensures accountability and reduces the risk of unauthorised access. *** ### Roles and permissions UbiQuity allows you to control what users can see and do within the platform. Use roles and permissions to: * Limit access to only what each user needs * Restrict sensitive actions (such as sending campaigns or managing data) * Support internal governance and approval processes *** ### Authentication Users sign in to UbiQuity using secure authentication methods. Depending on your setup, this may include: * Single Sign-On (SSO) using your organisation’s identity provider * Standard username and password authentication with two-factor authentication {% hint style="info" %} **SSO (via OpenID Connect) is recommended for improved security and centralised access management.** {% endhint %} *** ### Two-factor authentication (2FA) For non-SSO accounts, two-factor authentication adds an extra layer of security by requiring a second verification step when signing in. When enabled, users must provide: * Something they know (their password) * Something they have (such as a code from an authenticator app) We recommend enabling 2FA for all users to reduce the risk of unauthorised access, especially for accounts with elevated permissions. *** ### Password security If using standard authentication, ensure strong password practices: * Use long, unique passwords * Avoid reusing passwords across systems * Update passwords if there is any suspicion of compromise *** ### Best practices * To maintain a secure environment: * Enable SSO if possible * For non-SSO accounts, enforce 2FA for all users * Regularly review user access and permissions * Remove inactive or unused accounts * Apply the principle of least privilege # Security and trust Overview of UbiQuity’s approach to security. Security and reliability are core to how UbiQuity is designed and operated. This page provides a high-level overview of our approach. For full and up-to-date details, refer to our Security page on the UbiQuity website. ### Our approach We build and operate UbiQuity with a security-first mindset, covering infrastructure, application design, and day-to-day operations. This includes: * Protecting data in transit and at rest * Enforcing strong authentication and access controls * Monitoring systems for performance, reliability, and security risks * Regularly updating and patching infrastructure * Designing features with security and risk management in mind *** ### Compliance and standards UbiQuity follows recognised security practices and frameworks to ensure customer data is handled appropriately and securely. *** ### Availability and reliability We design the platform to be stable and resilient, with monitoring and processes in place to quickly identify and respond to issues. *** ### Learn more For detailed information about our security practices, infrastructure, and policies, see: This is the source of truth and is kept up to date as our platform evolves. # Privacy policy Learn how your data is handled and protected. UbiQuity is committed to protecting your data and handling personal information responsibly and securely. This page provides a high-level overview of how we approach privacy. Our full Privacy Policy, including detailed information about how we collect, use, store, and protect data, is maintained on our website. *** ### How we approach privacy We design and operate UbiQuity with security and privacy in mind. This includes: * Protecting data in transit and at rest * Applying access controls to ensure only authorised users can access data * Monitoring and maintaining our systems to meet security and compliance requirements * Supporting customers in meeting their own privacy and compliance obligations *** ### Where to find the full policy For complete and up-to-date information, please refer to our full Privacy Policy: # Service levels How UbiQuity monitors the platform and prioritises incidents. The core UbiQuity platform is monitored 24/7 for outages and targets 99.9% uptime, outside of scheduled maintenance windows. UbiQuity operates in a shared tenancy environment, where resources are shared across multiple clients. A priority system ensures fair and efficient use of these resources. Incidents are prioritised as follows: *** ### SLA Targets | **Priority** | **Name** | **Resolution Target** | | ------------ | -------- | --------------------- | | P1 | Critical | 4 business hours | | P2 | High | 8 business hours | | P3 | Medium | 5 business days | | P4 | Low | By agreement | Resolution targets are measured during business hours (9am–5pm, Monday–Friday). *** ### P1 - Critical Issues causing complete service disruption for all clients, leading to full system outages or data breaches. Immediate attention is required as the situation impacts access to, or critical functionality of, the UbiQuity platform. *Examples: The platform is down for all users, database connection is lost, significant security threat.* *** ### P2 - High Significant functionality is impacted, or significant performance degradation is experienced, however the platform and database are still accessible or workarounds are available. The issue affects a large portion of clients and requires quick resolution to prevent escalation. *Examples: API calls are failing for all clients using this functionality, all scheduled emails are not rendering or sending, all external-facing forms displaying an error message.* *** ### P3 - Medium A non-critical issue impacting individual clients or specific features, without completely halting operations. It may affect productivity but does not require immediate action. *Examples: Slow loading times for a report function, reduced email sending rate, caching issues.* *** ### P4 - Low Minor bugs that do not affect daily operations. These will be added to the backlog for resolution in future releases or maintenance windows. *Examples: Cosmetic issues or improved user experience for existing functionality.* *** ### Resolution tracking All incidents are investigated regardless of priority level. For P1 and P2 incidents, UbiQuity conducts a formal post-incident review (PIR) process. This includes a structured analysis of the incident's cause, impact, and resolution, as well as any actions taken to prevent recurrence. A formal PIR document is produced and is available to affected clients on request. To request a copy, contact your account manager. # Data backup and recovery How UbiQuity protects your data and ensures it can be recovered in the event of an outage. In the event of an outage, UbiQuity has robust backup procedures in place to ensure your data is protected and quickly recoverable. *** ### Regular data backups Data is backed up regularly to minimise the risk of data loss. Backups are retained for seven days, allowing restoration to any point within the past week. The backup strategy includes full, incremental, and differential backups to ensure comprehensive data protection. *** ### Secure storage All backup data is encrypted to ensure its security. Backups are stored in secure offsite locations to protect against physical damage or localised disasters. *** ### Monitoring and alerts UbiQuity systems are continuously monitored 24/7 to detect issues promptly. In the event of any anomalies, the team is immediately alerted to take corrective action. *** ### Rapid recovery UbiQuity aims to restore data within a predefined timeframe to minimise downtime (Recovery Time Objective). The goal is to ensure restored data is as recent as possible, reducing the amount of data lost in any given incident (Recovery Point Objective). *** ### Testing and validation Backup and recovery processes are tested regularly to ensure they work effectively. After each test restore, data is validated to confirm its integrity and completeness. *** ### Support during an outage The UbiQuity support team is available to assist during an outage and throughout the recovery process, providing regular updates and guidance on the status of data recovery. *** ### Compliance UbiQuity holds ISO 27001 certification for its Information Security Management System (ISMS), demonstrating a structured and audited approach to managing information security risks. Our backup procedures are implemented within this framework, following industry best practices to ensure the highest level of data protection and recovery. # Contact us Get help from the UbiQuity support team by email or live chat. There are two ways to get in touch. Use whichever suits you. *** ### Email Email us at . This is the best option for anything that needs a detailed reply, or when you want to attach screenshots, files, or examples. To help us get you an answer faster, try to include: * A clear description of what you're trying to do * What you expected to happen, and what happened instead * The name of the account, campaign, form, audience, or import you're working with * Any screenshots or error messages *** ### Live Chat If you're logged in to UbiQuity, you can chat with us directly using the live chat button in the bottom corner of the screen. Live chat is good for quick questions and getting pointed in the right direction. If your question turns out to be more involved, we may follow it up by email so we can give it proper attention.
A screenshot of the purple live chat icon shown when logged in to UbiQuity.

When logged in, click the purple chat icon to use live chat.

# Documentation overview Browse the platform by topic or find step-by-step guides for common tasks. ### Find what you need The UbiQuity documentation is organised around the key areas of the platform, so you can get to the right information quickly - whether you're setting something up for the first time, learning how a feature works, or completing a specific task. Use the sidebar to navigate by topic, or search if you already know what you're looking for. *** ### How the docs are structured * **Basics** - Core platform concepts including Content & Preview, Media Manager, Filters, Channels, and Templates. * **How To** - Step-by-step guides for common tasks such as creating emails, forms, surveys, and events, importing data, sending emails, and activating campaigns. * **Channels** - Guidance specific to each channel UbiQuity supports: Email, TXT, and Push. * **Data Capture** - Everything related to capturing data through Forms, Surveys, Events, and Layouts, plus guidance on finding your form and survey data. * **Data & Integrations** - Covers how to bring data into UbiQuity, including Imports, Connectors, and the API, with guidance on choosing the right integration method. * **Audience Management** - Managing your database, filtering audiences, handling Opt Outs, and working with GNA (Gone No Address). * **Keep Learning** - Additional resources including Training and the UbiQuity Blog. *** ### Not sure where to start? If you're new to UbiQuity, head to the [**Getting Started**](https://docs.ubiquity.co.nz/) section. # Content & Preview Add and preview your content before sending, across email, TXT, and push. ### Overview Content & Preview is the step in the send wizard where you add and configure the content of your communication - and check how it will look before it goes out. It appears as a named step across mailouts, TXT outs, and push notifications. What you can configure within it varies by channel, but the purpose is the same: get your content right and verify it before sending. *** ### Where Content & Preview applies Content & Preview is available in the following areas of UbiQuity: * **Mailouts** - Set sender details, add HTML and text content, and preview your email * **Automated Mailouts** - Configure and preview content for recurring scheduled sends * **TXT Outs** - Write and preview your TXT message content * **Push Notifications** - Build and preview push notification content *** ### How it works Within Content & Preview, you add the content for your send and then use the preview tools to check it before committing. **Adding content** varies by channel. For email, this means selecting your template and editing article blocks. For TXT and push, it typically means composing your message directly. **Previewing** lets you check your content in two ways. You can view a generic preview of the content as-is, or preview it as a specific contact from your database - which resolves any merge fields and shows how the message will appear for that person. You can also send preview emails to yourself or your team for testing before the actual send goes out. # Media Manager Store, organise, and manage images and files used across your emails, landing pages, forms, and other content in UbiQuity. ### Overview The Media Manager is your central library for all files used within UbiQuity. You can upload, organise, and reuse assets such as images, documents, and other media across the platform. This helps keep your content consistent and avoids needing to upload the same file multiple times. *** ### Accessing the Media Manager There are several ways to access the Media Manager: 1. Via the top navigation bar within UbiQuity.
2. Via the icon in any copy editor section across all modules.
3. On a call to action (button)
4. Within any image tab.
*** ### Uploading Files To upload a file: 1. Open the Media Manager 2. Select the **Upload** button
3. Choose your file(s) from your computer Once uploaded, files are immediately available to use across the platform. *** ### Supported file types Common supported file types include: * Images (e.g. JPG, PNG, GIF) * Documents (e.g. PDF) * Videos (eg. MP4) If a file type is not supported, the upload will be blocked. *** ### Organising Files Keeping your Media Manager organised will make it much easier to find and reuse assets. You can: * Create folders to group related files * Move files between folders * Rename files and folders for clarity A clear folder structure is recommended, for example: * Campaign 1 * Campaign 2 * Brand assets * Templates * General images
*** ### Using Files Files stored in the Media Manager can be used across multiple areas of UbiQuity. For example: * Insert images into emails and templates * Add images to landing pages and forms * Link to hosted files (e.g. PDFs) When selecting a file in editors, you can browse and choose directly from the Media Manager. *** ### Deleting Files To delete a file: 1. Either: 1. To delete an individual file, hover over the file and click the Trash bin icon in the bottom left corner 2. To delete multiple files at the same time, tick the file(s) and select **Delete Selected** 2. Confirm the action by typing **ACCEPT** and clicking **Delete file**
Deleted files will no longer be available anywhere in UbiQuity. If a file is already being used (e.g. in an email or page), removing it may result in broken images or links. *** ### Best Practices To keep your Media Manager easy to use: * Use clear and consistent file naming * Organise files into logical folders * Avoid uploading duplicate files * Regularly review and remove unused assets *** ### Troubleshooting * **File won’t upload**\ Check that the file type is supported and the file size is within limits. * **Can’t find a file**\ Use folders and naming conventions to locate files quickly. * **Image not displaying**\ Confirm the file still exists and has not been deleted or replaced. # Filtering Filter your audience to make sure the right contacts receive the right communications, across every part of the UbiQuity platform. ### Overview Filtering lets you target the right contacts at the right time - making your communications more relevant, more effective, and less likely to reach people they shouldn't. Across UbiQuity, filtering is available in multiple areas of the platform. Rather than sending to your entire database every time, filters let you define exactly who should receive a communication or be included in a workflow - based on contact data, previous send results, or other interactions your contacts have had with UbiQuity. *** ### Where filtering is available Filtering appears throughout UbiQuity and works slightly differently depending on the context. The areas where you can apply filters include: * **Database** - Filter contacts and transactional records directly within your database view * **Forms** - Apply filters to control which contacts receive a form-triggered email * **Mailouts & Automated Mailouts** - Restrict email sends to a specific subset of your audience * **Surveys** - Control who receives a survey-triggered email based on filter criteria * **Events** - Filter contacts for event-triggered email communications * **Push notifications** - Apply filters to push-triggered email sends Each of these areas has its own filtering interface, but the underlying logic is consistent across all of them. *** ### How filtering works Filters are built from **conditions** - rules based on fields in your contact or transactional data, the results of previous sends, or other interactions your contacts have had with UbiQuity. You can combine multiple conditions using **AND** or **OR** logic: * **AND** - every condition must be true for a contact to be included. For example, *Country = New Zealand* AND *Segment = Customer* would only include contacts who are both based in New Zealand and tagged as a Customer. * **OR** - at least one condition must be true for a contact to be included. For example, *Country = New Zealand* OR *Segment = Customer* would include anyone in New Zealand, plus any Customers regardless of location. Once you've built a filter you want to reuse, you can save it using the **Save Filter** option and apply it again in future. *** ### Managing saved filters You can manage your saved filters in the **Database** module. This allows you to delete, rename or update the content of saved filters within your account, regardless of where in UbiQuity they were initially created. *** ### Where to go next For guidance on filtering within a specific part of the platform, refer to the relevant section of this documentation: * Filtering in the Database - *see* [*Database*](/documentation/audience-management/database) * Filtering in Forms - *see* [*Forms*](/documentation/data-capture/forms) * Filtering in Mailouts - *see* [*Email*](/documentation/channels/email) * Filtering in Surveys - *see* [*Surveys*](/documentation/data-capture/surveys) * Filtering in Events - *see* [*Events*](/documentation/data-capture/events) * Filtering in Push Notifications - *see* [*Push*](/documentation/channels/push) # Channels Understand the different ways UbiQuity can send messages to your audience, and choose the right channel for your campaign. ### Overview UbiQuity supports three outbound channels for communicating with your contacts: Email, TXT, and Push. Each channel has different strengths depending on your message type, audience, and engagement goals.
ChannelBest for
EmailRich content, newsletters, and detailed communications
TXTShort, time-sensitive messages with high open rates
PushReal-time alerts and re-engagement for app or web users
*** ### [Email](/documentation/channels/email) Email is the most versatile channel in UbiQuity. It supports rich content including images, layouts, and personalisation, making it well suited for newsletters, promotional campaigns, transactional messages, and anything that benefits from a designed template. Common use cases include: * Promotional and marketing campaigns * Newsletters and regular updates * Transactional or triggered communications :point\_right: See [Email](/documentation/channels/email) for full details on setting up and sending email campaigns. *** ### [TXT](/documentation/channels/txt) TXT allows you to send short text messages directly to a contact's mobile number. Because TXT is delivered to the device itself, it tends to achieve high open rates and is particularly effective for time-sensitive or high-priority communications. Common use cases include: * Appointment reminders and confirmations * Urgent alerts or time-limited offers * Follow-ups to email campaigns :point\_right: See [TXT](/documentation/channels/txt) for full details on sending TXT messages. *** ### [Push](/documentation/channels/push) Push notifications allow you to send real-time messages to users who have opted in through a mobile app. They are useful for re-engaging users and delivering timely, contextual updates without relying on email or SMS. Common use cases include: * Real-time alerts and updates * Re-engagement campaigns for lapsed users * Time-sensitive announcements :point\_right: See [Push](/documentation/channels/push) for full details on setting up and sending push notifications. *** ### Choosing the right channel If you're unsure which channel to use, consider: * **How much content do you need to include?** Email supports rich layouts; SMS and Push are better for brief messages. * **How urgent is the message?** SMS and Push are better suited to time-sensitive communications. * **Where is your audience?** Push requires users to have opted in via an app or browser, while SMS requires a valid mobile number. In many cases, channels work best in combination - for example, sending an email campaign followed by an SMS reminder to non-openers. # Templates Create and manage reusable templates to speed up campaign creation and ensure consistency. Templates define the design, layout, and sender configuration of your emails. You create a template once and reuse it across mailouts - updating the content for each send while keeping the structure consistent. Your account can have as many templates as you need. A common approach is to maintain a master template for general communications, with variations for specific types of sends - such as newsletters, transactional messages, or event invitations. *** ### Managing templates Email templates are managed under **Email > Email templates**. From here you can create new templates, search and sort your existing templates, and set default templates for your account. **New template** creates a new template from scratch. You step through the template setup before entering the editor. **Set default templates** designates which template is used by default when creating a new mailout. You can still select a different template when setting up a specific send. Each template in the list shows its created and last modified date. Use the three-dot menu on any template to access edit, copy, and delete options. UbiQuity can create or customise a template for your account if needed - contact UbiQuity to discuss your requirements. *** ### What a template controls Your template sets the overall structure and configuration of your email, including: * **Sender details** - From name, From email address, Reply name, and Reply email address * **Subject line and pre-header** - The subject and preview text recipients see before opening * **Design** - Fonts, colours, logo placement, and spacing * **Content block structure** - The layout and arrangement of article blocks within the email * **Opt-out link** - Every **marketing** template must include an opt-out link. UbiQuity sets this up automatically in most cases When you create a mailout, you select a template and edit content within it. Changes made to a mailout's content do not affect the underlying template. *** ### EasyEdit UbiQuity's email templates are called EasyEdit templates - a block-based editor that lets you build professional, responsive emails without writing code. EasyEdit templates are optimised for desktop, tablet, and mobile, and can be configured with colour schemes, font settings, logo areas, and customisable content blocks. Custom HTML templates are also supported for accounts with access to a web developer. *** For full documentation on building and editing email templates - see [Email Templates](/documentation/channels/email/email-templates). # Access How to log into UbiQuity ### Logging into UbiQuity Go to [engage.ubiquity.co.nz](https://engage.ubiquity.co.nz/) or use the login button on the top right hand side of your screen ![](https://resources.ubiquity.co.nz/Images/login.jpg) To log in to UbiQuity you will need to enter your **Email Address** and **Password:** * if you have not been active in the platform for 24 hours or * if you clicked ‘Logout’ in your previous session or * if you close you browser or * if your IP address changes\* As an additional layer of security **Two-Factor Authentication** (2FA) is also enforced across the platform. UbiQuity will send a 6 digit code via SMS to your mobile phone. ![](https://resources.ubiquity.co.nz/Images/2fa30days.jpg) To save you having to enter the code every time you log in, you can choose to “remember this browser for 30 days". You’ll still enter your Email Address and Password each time you log in, but you won’t be asked for a 2FA code again on that same browser during the 30-day period. You will need to enter the **2FA code**: * if you clicked ‘Logout’ in your previous session or * if you switch to a different browser or * if you entered the wrong password or * if you have changed your mobile number In some cases, 2FA can be disabled for individual users if required either temporarily or permanently although we do not recommend this. Please [contact us](https://resources.ubiquity.co.nz/Contact) if you need any help. *** ### Logging into UbiQuity with SSO Enterprise Single Sign on (SSO ) means you access UbiQuity using your existing company email and password rather than an entire new credential. When logging on via SSO the process starts exactly the same. Go to [engage.ubiquity.co.nz](https://engage.ubiquity.co.nz/) or use the login button on the top right hand side of your screen ![](https://resources.ubiquity.co.nz/Images/login.jpg) However, once you have entered your email address you will be redirected to your login screen for your company's identity provider. No need for UbiQuity's 2FA - your company's enterprise-level security does all the heavy lifting. # Creating an email/form/survey/event/TXT Find the right starting point for creating mailouts, TXT outs, push notifications, forms, surveys, and events in UbiQuity. Use UbiQuity to send content across email, TXT, and push, and to capture data through forms, surveys, and events. Each channel or tool has its own creation wizard that steps you through the setup. *** ### Mailouts A mailout is a one-off email sent to contacts in your database. The creation wizard steps you through building your content, selecting links to track, filtering your audience, removing duplicates, and scheduling the send. Before you can send a mailout, your database must be configured for email. → [Creating a Mailout](/documentation/channels/email/creating-a-mailout) *** ### Automated Mailouts Automated Mailouts send on a recurring schedule based on date-based conditions in your contact data - for example, five days after a purchase date or two days before a subscription expires. The setup is similar to a standard mailout, a recurrence schedule, and an activation step. The mailout will not run until it has been activated. → [Creating an Automated Mailout](/documentation/channels/email/creating-an-automated-mailout) *** ### TXT Outs A TXT Out is a one-off outbound TXT message sent to contacts in your database. You can personalise messages using merge fields and track links for reporting. If your message is a marketing message, include a STOP opt-out instruction in the content. Before sending a TXT Out, your account must be set up for TXT and your TXT Programme must be configured for TXT Outs. → [Creating a TXT Out](/documentation/channels/txt/creating-a-txt-out) *** ### Automated TXT Outs Automated TXT Outs send on a recurring schedule based on date fields in your contact data. The setup follows the same steps as a standard TXT Out, with the addition of a When Filter and a recurrence schedule. The TXT Out will not run until it has been activated. → [Creating an Automated TXT Out](/documentation/channels/txt/creating-an-automated-txt-out) *** ### Push Notifications Push notifications are sent to devices with your app installed. You can target all registered devices or filter to a specific segment. The creation wizard covers content, filtering, and scheduling. Before sending a push notification, your app must be registered with UbiQuity. → [Creating a Notification](/documentation/channels/push/creating-a-notification) *** ### Automated Notifications Automated Notifications send push notifications on a recurring schedule triggered by date-based conditions in your contact data - useful for lifecycle messaging such as birthday notifications, welcome sequences, or subscription reminders. The setup follows the same steps as a standard notification, with the addition of a When Filter, a recurrence schedule, and an activation step. → [Creating an Automated Notification](/documentation/channels/push/creating-an-automated-notification) *** ### Forms Forms let contacts submit information that is written directly to your database. At creation, you choose a form type - Subscribe, Update, or Subscribe/Update - which controls how submitted data is handled. You can change the form type after creation. Before creating a form, make sure your database fields are set up, as the form pulls from these. → [Creating a Form](/documentation/data-capture/forms/creating-a-form) *** ### Surveys Surveys collect structured responses from contacts. A new survey is created with no questions or pages - you build these out after creation using the Survey Dashboard, which also provides tools for testing and deploying your survey. → [Creating a Survey](/documentation/data-capture/surveys/creating-a-survey) *** ### Events Events provide a registration form with a unique URL that contacts use to sign up. When creating an event you set an event date and a date that registrations close on. Both can be updated at any time after creation. → [Creating an Event](/documentation/data-capture/events/creating-an-event) # Importing data Get your contacts and data into UbiQuity quickly using a CSV file - no technical setup required. ### Overview Importing is the simplest way to get data into UbiQuity. If you have a list of contacts in a spreadsheet, you can upload it directly into your database in a few steps using the import wizard. You do not need any technical knowledge to run an import. The wizard guides you through each step, and most imports take just a few minutes to complete. *** ### What you will need Before you start, make sure you have: * Your data saved as a **CSV file**. If your data is in Excel, open it and save it as CSV before importing. Excel files (.xls or .xlsx) are not accepted. * **Column headings** in the first row of your file. These do not need to match your UbiQuity field names exactly - you will match them up during the import. * A **clean, consistent dataset**. UbiQuity checks data against your field types during the import, so things like invalid email addresses or incorrectly formatted mobile numbers will be rejected. *** ### How to import your contacts 1. Go to **Database > Import Contacts** 2. Click **Import Contacts** and select your file 3. Work through the wizard, mapping your columns to the correct fields in your database 4. Choose your update type - if you are not sure, select **Append/Update**, which will add new contacts and update existing ones 5. Review the summary and type **ACCEPT** to run the import 6. Check the results - any rows that could not be imported will be available to download and fix The whole process typically takes just a few minutes for most files. *** ### A few things to know **Existing contacts won't be duplicated.** UbiQuity uses a matching field - usually email address - to check whether a contact already exists before adding them. If they do, their record is updated rather than duplicated. **Some rows may be rejected.** This usually happens because of formatting issues in the data - a missing @ in an email address, or a mobile number missing its leading zero. You can download the error list at the end of the import and fix and re-import those rows. **The error file is only available for 7 days.** If rows were skipped, download the error file promptly so you can review and fix them. *** ### Also want to import transactional data? If you need to import purchase history, service records, or other data linked to your contacts, UbiQuity supports this too. See [Importing Transactions](/documentation/data-and-integrations/imports/importing-transactions) for a full guide. *** ### Want the full detail? For a complete step-by-step walkthrough of the import wizard including all options and troubleshooting, see [Importing Contacts](/documentation/data-and-integrations/imports/importing-contacts) in the Data & Integrations section. # Sending an email Build, test, and send email campaigns with confidence, including key checks before sending. UbiQuity offers several ways to send email depending on your use case - from one-off campaigns to automated lifecycle emails and transactional messages. All email sending is managed through the Email module. *** ### Before you send Make sure your account is ready before sending your first email. See First Time Setup for details on configuring your database for email. *** ### Ways to send email **Mailouts** - The standard way to send a one-off email campaign to contacts in your database. You step through a wizard to build your content, apply filters to target the right contacts, and schedule your send. Best for newsletters, announcements, and regular campaigns. **Automated Mailouts** - Set up emails that send automatically on a recurring schedule, triggered by date-based conditions in your contact data. Best for lifecycle messaging such as birthday emails, renewal reminders, and welcome programmes. **Transactional Targeted Mailouts** - Send emails driven by records in a transactional database rather than your contacts database. Best for keeping customers informed as their request or account moves through a process - for example, sending a status update each time a record changes. **Service Messaging** - Send critical service communications to contacts even if they have opted out of marketing emails. Best for essential notifications such as order confirmations, appointment reminders, and password resets where delivery is required regardless of marketing preferences. **Advanced Scheduling** - Two additional scheduling options for automated mailouts. Event-based scheduling triggers a send when an API import with a matching tag completes. Personalised email scheduling sends to each contact at a specific time defined in a date and time field in your database. # Activate Set up and manage automated or triggered communications based on customer behaviour. Before an automated send or triggered communication will run, it needs to be activated. Activation is the final step in the setup wizard across several areas of UbiQuity. Once activated, the dashboard updates to show reporting and a history of runs. The send will continue to run on its configured schedule or trigger until you deactivate it. To make changes after activation, deactivate first, edit, then reactivate. *** ### Activating your send Activate is the often the final step in the setup wizard. Before activating, review your settings - once active, some fields are locked until you deactivate. Use **Run Now** where available to trigger the send immediately outside of its regular schedule. The Activate option appears when you hit Finish on the final step of the wizard, as well as on the Dashboard screens. While the exact placement varies by area, the button looks the same throughout UbiQuity.

Here is an example of an Activate button appearing on the Automated Mailout Dashboard screen.

*** ### Where Activate applies * Automated Mailouts * Automated TXT Outs * Automated Notifications * Forms and triggered emails * Surveys and triggered emails * Events and triggered emails # Email Create, manage, and send email campaigns, including design, personalisation, and tracking. Email is UbiQuity's primary channel. From one-off mailouts to automated lifecycle campaigns, the email module gives you the tools to create fully branded, personalised emails and send them to the right people at the right time. Emails are built using EasyEdit templates - UbiQuity's template system that lets you create professional, responsive emails without needing to write code. If you have a web designer or developer, they can also build custom HTML templates for your account. Because email is managed alongside your other channels in UbiQuity, you can segment your audience using the same database contacts and filters you use for TXT and push notifications. *** ### What you can do with Email * Send one-off mailouts to your database contacts * Set up automated mailouts triggered by dates or contact data * Send transactional and service emails based on database or transactional records * Run A/B subject line tests on both one-off and automated mailouts * Track link clicks, open rates, and email client data through mailout reports * Create multi-article emails with personalised content for different contacts *** ### In this section * First Time Setup - Configure your database before sending your first email * Email Templates - Build and manage email templates using EasyEdit * Mailout Folders - Organise your mailouts and create folder-level filters and reports * Mailouts - Create and send a one-off mailout * Automated Mailouts - Set up mailouts that send automatically on a schedule * Transactional Targeted Mailouts - Drive emails from transactional database records * Service Messaging - Send critical service communications to contacts regardless of marketing opt-out status * Advanced Scheduling - Event-based and personalised email scheduling options * A/B Subject Testing - Test subject lines on one-off and automated mailouts * Mailout Reports - View and interpret mailout performance data * Share to Social - Let recipients share email content to social networks * Email Delivery and Statuses - Understand how emails are delivered and what each status means * Building Optimised Emails - Best practices for responsive, cross-client email design * Interactive Emails - Add interactive elements to your email campaigns # First Time Setup Configure your UbiQuity account before sending your first email. Before you can send emails through UbiQuity, you need to complete two steps: configure your database for sending email, and make sure you have contacts in your database to send to. *** ### Configure your database Your database needs to be set up with the correct fields for email sending before any mailouts can go out. This includes fields for managing opt-outs and bounce handling. Follow the database configuration guide to complete this setup. If your account has already been configured for email, you can skip this step. *** ### Add contacts to your database You will need contacts in your database before you can send a mailout. Contacts can be added in four ways: * **Subscribe form** - set up a web form that adds contacts when they sign up * **File import** - upload a contact list using the import process * **Connectors** - add contacts into your database using a connector * **API** - add contacts programmatically via the UbiQuity API Once your database is configured and you have contacts in place, you are ready to create your first mailout. See Mailouts to get started. # Email Templates Build and manage email templates using UbiQuity's EasyEdit template system. Email templates are the design and structure of your emails. In UbiQuity, templates are built using EasyEdit - a template system that lets you create professional, responsive emails by adding and editing article blocks without writing code. If you have a web designer or developer, they can also write custom HTML for a template directly. EasyEdit templates are optimised for desktop, tablet, and mobile by default. They can be built with colour selectors, font settings, logo areas, and customisable content blocks - similar to a CMS. UbiQuity can build a custom EasyEdit template for your account. Contact UbiQuity to discuss your requirements. *** ### To and Reply fields The header section of your email template is where you set the sender details and subject line. | Field | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | From Email | The email address the email appears to come from. Contact UbiQuity to set up a custom From Address. | | From Name | The friendly name shown in the recipient's inbox, e.g. *UbiQuity Marketing*. | | Reply Email | Where replies are sent if the recipient clicks Reply, e.g. [*marketing@example.com*](mailto:marketing@example.com). | | Reply Name | The friendly name shown when the recipient clicks Reply. | | Subject | The subject line of the email. | | Pre-header | Preview text that appears before the email is opened. Well-written pre-header text can significantly improve open rates. |
A screenshot of the header options available in each Email Templates

The header options available in each Email Templates

*** ### Merging fields Merge fields let you personalise email content with data from your UbiQuity database. Wherever you see the **Insert Merge Field** icon in the content editor, you can merge in a field. Click **Insert Merge Field** to open the Merge Field Selector. Expand the relevant node to find the field you want, then click **Add** to insert it. Merged fields appear as `[Database.Field Name]` in the editor. Use the **Preview** button to test how merge fields appear for a specific contact. If a contact has no value for a merged field, the field returns blank. To handle this gracefully - for example showing *"Hi there"* instead of *"Hi "* - you can use an IF statement in ESL (Engage Scripting Language). If you are adding merge fields to a triggered email (from a Form, Survey, or Event) rather than a mailout, you can merge in fields specific to that Form, Survey, or Event rather than database fields.
A screenshot of the Insert Merge Field icon shown next to fields such as Subject.

The Insert Merge Field icon shown next to fields such as Subject.

A screenshot of the Insert Merge Field button in the content editor.

The Insert Merge Field button in the content editor.

*** ### Insert UbiQuity Link Use the **Insert UbiQuity Link** function to insert a link to a UbiQuity Form, Survey, or Event into your email template.
A screenshot of the Insert Merge Field button in the content editor.

The Insert UbiQuity Link button in the content editor.

*** ### Opt Out Link Every email template must contain a link to a Form that includes your database Opt Out field. This is required before you can send a mailout. UbiQuity will set this up automatically in most cases - if it does not, you will need to: 1. Create an Update Web Form 2. Click **Edit Fields and Validation** 3. Add the **Opted Out** field 4. Save the form 5. Use the **Insert Link** function in your template to add the opt-out link When the mailout is sent, recipients can click the link to set their Opted Out field to Yes. They will automatically be excluded from future mailouts. If you are sending to a group that does not require opt-out management, this requirement can be turned off - contact UbiQuity to arrange this. *** ### Article filters Each article block in an email template can have a filter applied to control its visibility. This lets you show different content to different contacts within a single email, without needing to set up separate mailouts. Click **Edit article** and expand the filter section to apply filters. Article filters can be based on database fields, transactional data, and other contact interactions in UbiQuity.
A screenshot of Article Filters which can be used to control who can see specific articles.

Use Article Filters to control who can see specific articles.

*** ### Images and PDFs The Media Manager is available wherever you can add or edit content. Use it to insert images and link to PDFs or other documents. To upload files, click the tile or drag files onto it. You can upload multiple files at once. To resize an image after inserting it, right-click the image and select **Image Properties**. Keep image file sizes below 200KB where possible, and no larger than 500KB. Large images are slow to render and can affect the email experience. *** ### Attaching files Attaching files directly to emails is generally not recommended - attachments can be stripped by corporate firewalls, add significant bandwidth, and cannot be reported on in UbiQuity. The preferred approach is to upload the file to the Media Manager and insert it as a link. The file is only downloaded when the recipient clicks the link, which is faster and trackable. #### Personalised attachments UbiQuity supports personalised attachments - unique files attached to each individual email. This is useful for sending personalised quotes, invoices, tax receipts, or statements. Personalised attachments must be enabled on your account by UbiQuity before use. UbiQuity does not generate the files itself - the documents must be hosted at an external URL, and UbiQuity calls that URL with the relevant merge fields to retrieve the correct file for each contact. | Field | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Description | A label used within UbiQuity to identify the attachment type, e.g. *Tax Receipt*. | | Attachment URL | The URL where the attachment is hosted, with merge fields to identify the correct file per contact. For example: `https://example.com/id=[Database.ID].pdf` | | Friendly Filename | The name the file will be given when attached to the email, e.g. *Tax Receipt for \[Database.First Name]*. Do not include the file extension — this is pulled from the file itself. | | Send Without Attachment | If checked, the email will send even if no attachment is found for a contact. If unchecked, emails without a valid attachment will not send. | *** ### Previewing a template Use the preview function to see how merge fields will appear for a specific database contact. You can select multiple contacts and send preview emails to your inbox - one email per selected contact. An address book is available if you preview frequently. *** ### Text and HTML versions Every email is made up of two parts: an HTML version (with images, fonts, and formatting) and a plain text version. Some older email clients cannot display HTML and will show the text version instead. UbiQuity automatically adds a View Online link to the text version, so recipients using a text-only client can click through to the HTML version in their browser. You generally do not need to edit the text version, but you can update it using the tabs in the editor. *** ### [Default Template](/documentation/channels/email/email-templates/default-template) Every UbiQuity account comes with a default email template - a base EasyEdit template that is pre-configured and ready to use. The following pages document this default template in detail. * [Default Template](/documentation/channels/email/email-templates/default-template) - introduction to the default template * Field Types - The field types available when editing your template * Base Settings - Template-wide settings for fonts, colours, and layout * Article Blocks - How to add, edit, and manage article blocks * Layout Breakdown - Detailed guide to each of the nine article layouts # Default Template An introduction to the default template. Every UbiQuity account comes with a Default Easy Edit template — a base EasyEdit template that is pre-configured and ready to use. The following pages document the Default Easy Edit template in detail. **Field Types**\ Email Easy Edit offers a variety of field types to customise your email content. Understanding these field types is crucial for creating engaging and dynamic emails. Here are the primary field types you will encounter. **Base Settings**\ The settings section allows you to configure various aspects of your email. These settings ensure that your email aligns with your branding and communication goals. **Article Blocks**\ Article blocks are the building blocks of your email content. They allow you to structure your email in a visually appealing and organised manner. **Layouts**\ Layouts provide predefined structures for your email, making it easier to design professional-looking emails quickly. You can choose from various layouts to suit your content needs. By understanding and utilising these field types, settings, article blocks, and layouts, you can create compelling and effective emails that resonate with your audience. Dive into the following sections for detailed instructions and tips on using each feature to its fullest potential.
A screenshot of the default Easy Edit template available in all accounts.

The default Easy Edit template available in all accounts.

# Field Types A breakdown of the field types in the default template. While using this template, you will come across multiple field types. This is a breakdown of each field type and how to use them correctly. ### Text

The article name field.

1. Text box to enter copy 2. This button allows you to select a merge field from UbiQuity (e.g. a database field) *** ### Link
A screenshot of the image link field.

The image link field.

1. Dropdown to select your link type, this can be URL, email or anchor (tel: coming soon) 2. Text box to enter said link 3. This button allows you to select from a Ubiquity link, this can be view online, form, survey or event link. 4. This button links to the Media Manager where you can link to an image or other asset (e.g. .pdf or .doc) that you have stored in UbiQuity *** ### CK Editor Here is where you will put your copy for the article. Here is the breakdown for all the toolbars attached to the CK Editor.
ToolbarsImage

Text formatting

  1. Make text bold
  2. Make text italic
  3. Change text colour - *see notes below
  4. Remove styling
  5. Ordered list
  6. Bullet list
Text formatting
* When it comes to changing the text colour, you have the option to enter your brand colours via HEX code. Select the colour button, then click more colours then enter your hex code (be sure to include the ‘#’).Colour picker

Text alignment

  1. Left
  2. Centre
  3. Right
  4. Justified
Text alignment

Links

  1. Link – you highlight and add a link to your copy.
  2. Remove link
  3. Anchor link – you can add an anchor point to your email and add the link to that anchor point somewhere else in the email.
Links

Miscellaneous 1

  1. Media Manager – while you can use this to insert an image, it is recommended to use an image-based layout (unless it’s going to sit in its own paragraph, e.g. a signature) or to link to a document or PDF.
  2. Table – *see notes below
  3. Insert special character
  4. Paste copy as plain text - this is handy when pasting copy from sources that could have styling attached to the text (e.g. website or word). This option will remove any styling applied to the copy.
  5. Paste copy from word, this will remove all styling that could be pulled across from word.
Miscellaneous 1

* When inserting a table, it is recommended that it’s a simple table (2-3 columns max) and for it to be resized to be 100% wide (this is to help it rescale on mobile)

Click on the advanced tab and change the 500 to 100% in the style text field.

Table options

Paragraph

Here you can change whether you are using a paragraph (normal) or headings. You can set the default sizes for paragraph and Heading 1-3 in the template options.

Paragraph

Font

This a list of email safe fonts (meaning that readers of the email should have these fonts installed on their device). It is not recommended you use these fonts and to set your font in the template options.

Font

Size

Here you can change the font size. You should set your main font sizes in the template options and only use this to resize a one-off paragraph (e.g. terms and conditions).

Size

Mergeable's

  1. Insert a merge field (e.g. database field)
  2. Insert a UbiQuity link
  3. Share to social. You can share this article or email to Facebook, X or LinkedIn.
Mergables

Miscellaneous 2

  1. Spellcheck
  2. Expand – this will expand the CK editor to full screen
  3. Source – this will show you the HTML code the CK editor creates (you can also write your own HTML/CSS in here
Miscellaneous 2
*** ### Colour picker
A screenshot of the background colour option.

The background colour option.

1. Colour swatch - this also opens a colourpicker window\* to select a colour 2. Hexcode: you can manually type in your hexcode if you have it. \*Colour picker window – where you can select a colour directly, enter RGB or the hexcode. Hit ‘Set’ to save.
A screenshot of the colour picker.

The colour picker option.

*** ### Image If there currently isn’t an image you can hit the + icon and add the image, this will take you to the Media Manager.
A screenshot of the add image option.

The add image option.

Once an image has been selected you will see the options/details below
A screenshot of the options that show once an image has been added.

The options that show once an image has been added.

1. Image thumbnail 2. Alt text (it is best practice to add this so your content is accessible to all users ie. vision impaired) 3. Image width 4. Image height 5. Remove image 6. Change image 7. Aspect ratio locked (this keeps the image in proportion). The max image width will change depending on the spacing selected. If the image is too wide an error will display at the top of the dialogue box.
A screenshot of the error message that shows if your image is too wide.

The error message that shows if your image is too wide.

### Radio select
A screenshot of the radio select option.

The radio select option.

Single select to set options/settings for the template or article. *** ### Checkbox select
A screenshot of the checkbox select option.

The checkbox select option.

Like the radio select, checkbox select is used to show/hide other article options or set settings in the article block. *** ### Slider
A screenshot showing an example of a slider.

An example of a slider.

Allows you to set a numeric value setting, e.g. spacing or font size. Move the dot left/right to change the value. *** ### Elements Block
A screenshot of an elements block.

An elements block.

An elements block is a field that houses multiple fields, that allows you to have multiple of the same element (e.g. CTA button) in one article. You can add, copy and delete an element item using the buttons on the right. If this field is not required, just delete each element using the buttons. # Base Settings The settings available within the template. ### Template options These are settings like font size, main text colour etc. Open ‘Template Options’ – this is located at the top left corner of the email.
A screenshot of the template options button.

The template options button.

There are a few tabs to go through *** ### Tab: Header Title: This is the title that will show in the browser tab if the email is viewed online. Favicon: This is the icon that will show next to the title in the browser tab. ![The page title and favicon.](https://resources.ubiquity.co.nz/Images/template-options-header.jpg) *** ### Tab: Fonts [Click here](https://resources.ubiquity.co.nz/home/using-engage/email/building-optimised-emails#typography-fonts) to find out about fonts for email. This template allows you to choose your main body font and headings (if different). If you want to use a custom font (a non-email-safe font) you will need the URL to your font-face file (this will most likely be a file that ends with .css). It will show text that looks like this, if viewed in the browser.
Font-face css

Font-face CSS

Talk to your website/design team about your brand’s font and if font-face CSS is available. Google also have fonts available for free. First confirm you want to use a custom font for your email
Custom font options

Custom font options

You can copy/paste the font file URL into the template options field
URL to font file

URL to font file

If using a Google font, check the Google font field to automatically add the preconnect files to help load the font files faster.
Google font option

Google font option

Next, you need to determine your font family options. (These are the font names). The standard fonts will be the email-safe font options, Arial, Helvetica, sans-serif (the most common font family).
Font family standard

Font family standard

If using a custom font you will list the font family in the custom fields.
Font family custom

Font family custom

*** ### Tab: Copy colours Here you set your default body copy/text and link colours. You set a dark and light colour option. You will then be able to select which colour option is best when creating your article and what background colour is chosen. You can choose your colours either by the colour picker, HEX code or RGB. ![Colour picker](https://resources.ubiquity.co.nz/Images/template-options-color-picker.jpg) *** ### Tab: Desktop font sizes Here you set the default font size you want the main body copy and the headings 1-3 on desktop. You can set the space underneath the paragraphs and headings. Font sizes and spacing are set in pixels. Recommended font sizes are preselected. You can move the slider left/right to select your desired font size/spacing. ![Font sizes](https://resources.ubiquity.co.nz/Images/template-options-font-sizes.jpg) *** ### Tab: Mobile font sizes Mobile font sizes work the same way as the desktop tab but are only applied if the email is viewed on a mobile device. You can set them to be the same as the desktop if you wish to keep the body/headings the same size. *** ### Tab: Mobile spacing This is the spacing around each article and will be only applied if the email is viewed on a mobile device. The spacing will also only apply if the article itself has desktop spacing and the exclude mobile spacing isn’t checked. The desktop spacing settings are done in the article settings. ![Mobile spacing](https://resources.ubiquity.co.nz/Images/template-options-mobile-spacing.jpg) *** ### Tab: Background This tab sets the background colour that is outside the email. ![Background colour](https://resources.ubiquity.co.nz/Images/template-options-background.jpg) *** ### Tab: View online/Customer info With the view online you can choose to show/hide it and select the text colour.
View online

View online

Customer info is an optional text box if you wish to have any extra copy that sits alongside the view online text. You can choose if it sits left or right of the view online text or centre if choose to hide the view online text and select the copy colour.
Customer info

Customer info

# Article Blocks Understanding the options in article blocks. ### Article buttons The article buttons are how we create, edit and delete article blocks (email content) in the email. Here is the breakdown of each button function
Article blocks

Article blocks

Buttons will sit at the top right of the associated article. 1. Add a new article block. The article will be added underneath the current article. 2. Edit article. This will open the article editor to edit the content. 3. Copy article. This will copy the article and add it underneath the current article. 4. Delete article. Don’t be afraid of this button. You are only removing the content, not the ability to add that article again if needed. 5. Reorder articles. It doesn’t matter which article you click this button on; a list of all the articles will pop up and you can drag/drop them in the order you desire.
Reorder articles

Reorder articles

1. The first text field in the article block that has a value (This is what the field 'Article name' is for) 2. Layout type *** ### Layouts When adding or editing an article, along the top of the dialogue box there is a dropdown to select the article layout type. There are nine different layouts to choose from. The layouts will show different fields depending on what that layout requires.
Article layouts

Article layouts

*** ### Filter With each article, you can add a filter that will enable the article to only show if it matches that filter. The filter works the same way as mailout filters.
Article filters

Article filters

# Layout Breakdown A breakdown of the different fields/tabs. ### Tabs As stated on the previous page, there are 9 layouts to choose from. Depending on the layout, the tabs and fields will be different. However, the ‘Settings’ and ‘Spacing’ tabs are the same on all layouts. However, on the ‘Settings’ tab, a couple of fields will switch out depending on an image or text-based layout. This pages provides a breakdown of the fields and how/what they are used for. *** ### Tab: Settings **Article name**\ Text-based field. This field is to name the article which then helps when re-ordering articles if needed. **Anchor point** (Logo or Banner layout only)\ This field allows you to add an anchor point to an image article layout. Please only use letters and numbers with no spaces. **Background colour**\ Sets the background colour for the article block. You can either click on the colour swatch to open the colour picker or type in the hex code (make sure there is a # to set the colour correctly).
The background colour options.

The background colour options.

**Default text colour** (copy-based layouts, not Logo or Banner layouts)\ This article is to set the main copy colour from the options you set in the ‘Template Options’. You will either choose your light or dark option depending on the background colour you have chosen. **Do you want to add a separator at the bottom of this article?**\ This will add a separator line underneath your article. Selecting ‘yes’ will show another field below to select the separator line colour.
A separator line.

A separator line.

**Separator Colour**\ Shows if the above field has been ticked ‘yes’. Use the colour picker to select a colour. **Do you want to add a separator gap at the bottom of this article?**\ This will add a gap at the bottom of your article of the main background colour. Selecting ‘yes’ will show another field below to set the height of the gap.
A gap between articles.

A gap between articles.

**Gap height**\ Shows if the above field has been ticked ‘yes’. Use the slider to select the gap height. ### Tab: Spacing This tab is where you set the spacing around the article. You can move the slider left/right to set the spacing for each edge. The spacing is set in 5px increments. If you set the spacing to 0 for any edge, the mobile spacing will not be applied for that edge.
Article spacing options.

Article spacing options.

If you wish to keep the spacing selected on mobile you can turn off the mobile spacing settings (set in the template options) at the bottom of the tab. Just check ‘yes’.
Article mobile spacing.

Article mobile spacing.

### Layout: Logo
Logo sample.

Logo sample.

#### **Tab: Logo**
Logo tab.

Logo tab.

**Logo**\ Insert your logo image here. **Image alignment**\ Align the logo left, center or right. If also using logo 2 the alignment doesn’t apply, and Logo aligns left and Logo 2 aligns right. **Logo link**\ Link your logo image **Link friendly name**\ Help with link tracking in the mailout. #### **Tab: Logo 2** **Logo 2**\ Insert your logo image here. **Logo link 2**\ Link your logo image **Link friendly name 2**\ Help with link tracking in the mailout. ### Layout: Banner Example of a banner full width (no spacing)
Example of a banner full width (no spacing).

Example of a banner full width (no spacing).

Example of a banner with spacing.

Example of a banner with spacing.

#### **Tab: Image** **Image desktop**\ Insert banner image. Max image width is based on the spacing settings. **Image mobile**\ Insert a mobile image if applicable. If not required leave blank the and desktop will scale to fit mobile screens. **Image alignment**\ If the image uploaded doesn’t fit full-width of the email, you can change the alignment on where you want the image to sit in the article. **Image link**\ You link the image if you wish to do so. **Link friendly name**\ Help with link tracking in the mailout. ### Layout: Copy + navigation ![Copy and navigation](https://resources.ubiquity.co.nz/Images/layout-copy-nav.jpg) #### **Tab: Copy** **Copy**\ Here you will insert your intro copy. Copy will wrap around navigation if long enough. #### **Tab: Navigation** **Nav style**\ Choose between the navigation sitting on a solid background colour or have an outline. **Solid/Outline colour**\ Choose the colour of navigation box/outline. **Nav alignment**\ Choose if the navigation sits on the left or right. **Navigation**\ Add to the navigation. Using the navigation element block, you can add each nav item. If linking to other parts of the email, it is recommended that you set up those articles first, add an anchor point to the article, then come back to add that article to the navigation. Breakdown of navigation element block\ **Text:** Link copy\ **Text colour:** Colour of link copy\ **Link:** The link\ **Link friendly name:** If using a url, this will help with link tracking
Navigation element block.

Navigation element block.

### Layout: Navigation bar
Navigation layout.

Navigation layout.

#### **Tab: Navigation** **Font size**\ Use the slider to select the font size. **Navigation**\ This is the same field from the copy + navigation layout and works the same way. Each navigation item is separated by a pipe ‘|’ ### Layout: Text only
Text only layout.

Text only layout.

#### **Tab: Copy** **Copy**\ Using the CK Editor you can insert your article copy, style the headings and change colours etc. If you want to link to this article via the navigation, you can an anchor tag here. Place the cursor where you want the anchor tag (We recommend at the very beginning) and hit the anchor icon in the options.
Anchor tutorial.

Anchor tutorial.

#### **Tab: CTA** **CTA layout**\ If you plan to have more than 1 CTA (call to action) button, you can choose to display the buttons either horizontally or vertically. NB: if chosen horizontal, there is so much space (as the buttons won’t break onto a new line) and the button copy can break onto two lines and the buttons could push out the width of the email. **CTA alignment**\ Choose if you want the buttons aligned left, center or right. **Call to action**\ This field is another Element block field which allows you to add multiple CTA’s. Breakdown of the Call to action article field\ **Button text:** Copy for the button\ **Button link:** Button url\ **Button text colour:** Select the button text colour\ **Button background/outline colour:** Select base colour\ **Button style:** Select either if the button is solid colour or an outline\ **Button corners:** Select to either have square, curved or round button edges\ **Link friendly name:** If using a url link this helps with link tracking ### Layout: Image side/Image flush/Image wrap All three image/text based layouts use the same fields, except the image wrap article, which doesn’t use the ‘Image vertical alignment’ field. The difference between the layouts is the how each layout is displayed in the email. **Layout Image side:** displays with the ability to add spacing all around the article (top, bottom, left and right), the CTA’s are sit underneath the copy and display vertically.
Layout image side.

Layout image side.

**Layout Image flush:** display the image hard against the edge and the spacing settings are applied around the copy and CTA’s. CTA’s are also sit underneath the copy and display vertically.
Layout image flush.

Layout image flush.

**Layout Image wrap:** Like the Image side layout, however this layout is recommended if there is a lot of copy which in turn will wrap around the image. The CTA’s sit underneath the copy and can be displayed either vertically or horizontally.
Layout image wrap.

Layout image wrap.

#### **Tab: Copy** **Copy**\ This is the same field as the ‘Text only’ layout and the same principles apply. #### **Tab: Image** **Image desktop**\ Insert image. Max image width is set to 2/3 of the allocated space. **Image mobile**\ Insert image if you wish to display a different image than desktop (e.g. you might want to use a more landscape image vs portrait image that you may have used on desktop). Leave blank if not required.\ ![Image desktop vs mobile](https://resources.ubiquity.co.nz/Images/article-image-mobile.jpg) **Image alignment**\ Display image either on the left or right side. **Image vertical alignment**\ Set the vertical alignment (top, middle or bottom) if the image shorter than the copy. If copy is shorter than the image the copy will vertically align to the middle. **Image link**\ If you wish to link your image. We recommend that you do link the image if you are also going to have a CTA. Recommend linking to the same place as the first CTA. Leave blank if not required. **Link friendly name**\ If using a url link this helps with link tracking #### **Tab: CTA** This tab uses the same fields as the ‘Text only’ layout and the same principles apply. ### Layout: Footer ![Footer layout.](https://resources.ubiquity.co.nz/Images/layout-footer.jpg) #### **Tab: Logo** **Logos**\ Use an element block field to enable you to use up to three logos. Breakdown of the Logos element block fields\ **Logo:** Insert image. Max image width of the logo is 200px.\ **Link:** You can link your logo\ **Link friendly name:** To help with web tracking #### **Tab: Copy/Links** **Font size**\ Select the font size you wish the footer copy to be. We recommend selecting a font size that is slightly smaller than your main body copy. **Copy**\ Uses the CK Editor as other layouts and same principles apply. We recommend center aligning the copy as every other field in the footer layout is aligned to the center. **Footer links**\ This is an element block to allow you to add multiple links horizontally to the footer. We recommend placing your unsubscribe/opt out link here if the email is a marketing email. The links are separated by a pipe ‘|’. Breakdown of fields\ **Text:** Link copy\ **Text colour:** Link copy colour\ **Link:** Where your links goes\ **Link friendly name:** To help with link tracking #### **Tab: Social** **Social**\ Another element block where you can add the social icons and links you use. Breakdown of the fields\ **Icon:** Insert social icon image. Max image width is 30px.\ **Link:** Link to your social page\ **Link friendly name:** Helps with link tracking # Mailout Folders Organise your mailouts into folders, apply folder-level filters, and run reports across multiple mailouts. Every mailout in UbiQuity lives inside a Mailout Folder. Use folders to group similar mailouts together — for example, by campaign type, audience, or opt-in category. > **Note:** If you delete a Mailout Folder, all mailouts inside it will also be deleted. *** ### Mailout Folder filters You can apply a filter to a Mailout Folder so that it is automatically applied to every mailout created within that folder. This is particularly useful when you have multiple opt-in fields in your database — for example, *Opted In Marketing*, *Opted In Newsletter*, and *Opted In Product Updates*. By creating a folder for each communication type and setting the appropriate filter on each folder, you ensure the right contacts are always targeted without having to re-apply the filter each time. Example setup: * Create a folder called *Marketing Emails* with a filter of *Opted In Marketing = Yes* * Create an Update Form with the *Opted In Marketing* field on it * Add the link to that form in the email templates used for marketing sends * When a recipient clicks the opt-out link and sets *Opted In Marketing = No*, they will automatically be excluded from future mailouts in that folder You can still apply additional filters at the individual mailout level on top of the folder filter. *** ### Mailout Folder reports Folder-level reports let you view and compare performance across multiple mailouts in the same folder. When creating a report, select the mailouts you want to include. You can change which mailouts are included after the report is created using the **Modify Report** option. Folder reports include: * An **Overview** page showing combined stats across all included mailouts * A **Comparison** page for side-by-side comparison of individual mailout performance — useful for subject line testing and campaign analysis * A dropdown to view the individual report for each mailout Reports can be shared via a link. Anyone with the link can view the report without logging in to UbiQuity. No personally identifiable information is shown. The link is not published anywhere — access requires knowing the URL. # Creating a Mailout Create and send a one-off email mailout to your database contacts. A mailout is a one-off email send to contacts in your UbiQuity database. Before you can send a mailout, your database must be configured for email. See First Time Setup if this has not been done. The quickest way to create a new mailout is to copy a previous one. Copying a mailout brings across the full email template and any filters that were applied — you simply step through the wizard and make your changes. When you create a mailout you are taken to the **Mailout Dashboard**. UbiQuity saves your progress each time you click **Back** or **Next**, and you can also click **Save** to return later. Click **Confirm** to jump directly to the confirmation step at any time. Once the mailout is scheduled, the dashboard updates and the mailout can no longer be edited — but you can pause, cancel, and view reports from there. *** ### Content and Preview Content and Preview is where you build the email content. See Email Templates for details on editing and previewing templates. *** ### Track Links UbiQuity scans your email template and lists all links. Check the boxes next to the links you want to track. Tracked links are reported on in the mailout report and can also be used for filtering and segmenting contacts based on click behaviour. Tracking a link changes the URL in the email. By default, tracked links appear as `http://engage.ubiquity.co.nz`. Custom link domains can be set up for your account — contact UbiQuity to arrange this. **Friendly Names** — click **Get Friendly Names** and UbiQuity will fetch the page title for each link automatically, making reports easier to read. **Link Personalisation** — UbiQuity automatically personalises links that belong to your own UbiQuity account. You can choose to depersonalise specific links if you need to share content externally without recipient-specific data appended. **Google Analytics** — add UTM tags to your links if you are using Google Analytics on your website. Log in to Google Analytics to view visit data from your mailout. **Text version links** — if your email has links in the text version, you can choose to track these as well. *** ### Filter Filter your database to target a specific segment of contacts. You can filter by: * Database contact fields * Results from previous mailouts * Interactions with other UbiQuity channels such as TXT messages and push notifications If a filter has been set on the Mailout Folder, it will be applied automatically in addition to any filters you set here. #### AND and OR conditions **AND** — all conditions must be true for a contact to be included. *Example: Country = New Zealand AND Segment = Customer includes only contacts who are customers in New Zealand.* **OR** — either condition can be true for a contact to be included. *Example: Country = New Zealand OR Segment = Customer includes all contacts in New Zealand plus all customers, regardless of country.* #### Automatically excluded contacts Contacts flagged as **GNA (Gone No Address)** and contacts who are **Opted Out** are automatically excluded from all mailouts. See [Email Delivery and Statuses](/documentation/channels/email/email-delivery-and-statuses) for more detail on GNA and opt-out management. *** ### Dedupe The Dedupe screen lets you exclude duplicate contacts from the mailout. Select the field or fields that indicate a duplicate — UbiQuity will randomly select which duplicate to exclude. Dedupe is not a substitute for good database hygiene. To prevent duplicates entering your database in the first place, set Unique Fields under **Database > Edit Database Fields**. *** ### Schedule and Confirm You can choose to prepare the mailout now or at the time of sending. | Option | Behaviour | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Prepare now | Filters and contact data are applied immediately. Changes to your database after this point will not affect the mailout. | | Prepare at send time | Filters and contact data are applied at the scheduled send time, reflecting your database as it is then. Note: preparation takes a little time, so emails may not send at exactly the scheduled time. | To spread a send over a time window, set both a start and end time — UbiQuity will distribute the sends between the two times. If the mailout invites recipients to contact a call centre, consider scheduling at an hourly rate to manage incoming call volume. The **Confirm** screen shows a summary of all mailout settings. It also runs an **Authentication Audit** to check that the From Address is correctly configured for spam filter compliance and that bounced messages will be returned to UbiQuity for processing. Contact UbiQuity if you see any warnings. *** ### Pre-send Checklist We recommend prior to sending a mailout that you go through the pre-send checklist to make sure that everything has been double checked. {% file src="/files/6WzlxCixHSqX8JAZYBhj" %} We also strongly recommend that you do a live email test send to yourself and/or other stakeholders to ensure that everything is working correctly for your email. *** ### Pausing and cancelling Once a mailout has been scheduled, you can pause or cancel it from the Mailout Dashboard, provided not all emails have been delivered. * **Pause** — stops sending. You can resume the mailout or reschedule the remaining emails to send at a later time. * **Cancel** — stops the mailout entirely. To resend to the remaining contacts, create a new copy of the mailout and filter for contacts from the original mailout whose message status is *Cancelled*. # Creating an Automated Mailout Set up mailouts that send automatically on a recurring schedule based on dates or contact data. Automated Mailouts let you send emails to contacts based on lifecycle events or date-based triggers - without manually sending each time. Common uses include: * Sending a birthday email * Following up five days after a purchase with a survey link * Notifying a contact before their subscription expires * Sending welcome programme emails Automated Mailout filters work similarly to standard mailout filters, with additional options for date-based conditions - for example, *5 days after Sign-up Date*. When you create an Automated Mailout you are taken to the **Automated Mailout Dashboard**. The mailout will not run until it has been activated. Use **Run Now** to trigger it immediately at any time. *** ### Content and Preview Build the email content in the same way as a standard mailout. See [Email Templates](/documentation/channels/email/email-templates) for details. *** ### Track Links Select the links to track in the same way as a standard mailout. See [Creating a Mailout - Track Links ](/documentation/channels/email/creating-a-mailout#track-links)for details. *** ### Filter The filter works similarly to a standard mailout filter. #### Automatically excluded contacts Contacts flagged as **GNA** or who are **Opted Out** are automatically excluded. See [Email Delivery and Statuses](/documentation/channels/email/email-delivery-and-statuses) for details. *** ### Dedupe Works the same as for a standard mailout, but duplicates are calculated at the time the Automated Mailout runs rather than at setup. *** ### Recurrence Set how often the Automated Mailout should run - for example, daily, weekly, or monthly. *** ### Activate The Activate screen shows a projected target count - the number of contacts expected to be included when the mailout next runs. This is a projection only, as data may change before the run date. Once activated, the dashboard updates to include reporting and a run history. Deactivate the mailout to make changes. *** ### Pre-send Checklist We recommend prior to sending a mailout that you go through the pre-send checklist to make sure that everything has been double checked. {% file src="/files/6WzlxCixHSqX8JAZYBhj" %} We also strongly recommend that you do a live email test send to yourself and/or other stakeholders to ensure that everything is working correctly for your email. *** ### Mailout Projections Once active, the **Mailout Projections** section shows how many emails are expected to send on future dates. Click a date to see which contacts would be included, and click a contact to preview how merge fields will appear for them. Projections are based on current data and may differ from actual sends if your database changes before the scheduled date. *** ### Mailout Report See [Mailout Reports](/documentation/channels/email/mailout-reports) for details on viewing and interpreting Automated Mailout reports. # Transactional Targeted Mailouts Send emails driven by records in your transactional database rather than your contacts database. Transactional Targeted Mailouts allow you to trigger emails based on records in a transactional database rather than using your contacts database as the source. This makes it possible to send a separate, personalised email for each transaction a contact has — not just one email per contact. A common use case is keeping customers informed as a request moves through an internal process. For example, as a customer's application for power, phone, insurance, or internet moves through stages — *received*, *allocated*, *actioned*, *completed* — a transactional record can be added at each stage, triggering a personalised update email at each step. This kind of proactive communication reduces unnecessary contact centre load. > **Note:** Transactional Targeted Mailouts require setup by the UbiQuity team before use. Contact UbiQuity if you are interested in this feature. *** ### Setting up a Transactional Targeted Mailout A Transactional Targeted Mailout can be used as part of either a one-off or automated email campaign. To enable it, you must have a transactional database set up within your UbiQuity account. 1. Create a mailout in the usual way — see Mailouts or Automated Mailouts 2. On the Mailout Details screen, toggle **Do you want to send emails for every transaction?** to active 3. Select the transactional database you want to use as the source *** ### Filtering The filtering screen for a Transactional Targeted Mailout works differently to a standard mailout filter. Instead of showing one row per contact, it shows one row per transactional record — so a single contact may appear multiple times if they have multiple records. When building a filter, the first available fields are those specific to the selected transactional table. You can still filter on other areas of UbiQuity, but transactional fields are shown first to make it clear you are working with a transactional source. This structure allows you to filter on a specific status or stage, or to use dynamic content within a single email that adapts based on the transactional record. *** ### Dedupe Deduplication is not available for Transactional Targeted Mailouts. This is intentional — a single contact may legitimately receive multiple emails, one for each transactional record that matches the filter. *** *** ## Service Messaging *Send critical service communications to contacts even if they have opted out of marketing emails.* Service messaging — sometimes called transactional messaging — allows you to send essential communications to your customers in real time, regardless of their marketing opt-out status. These are messages your customers need to receive, such as: * Order or application confirmations * Appointment reminders * Password resets * Status updates on a request or application * Insurance notifications * Dispatched documents or tickets Unlike marketing emails, service messages are triggered by a customer action or business event rather than a campaign schedule. > **Note:** Service Messaging requires setup by the UbiQuity team. Contact UbiQuity to discuss your requirements. *** ### How it works Service messages in UbiQuity are triggered from your transactional or relational database. As a customer record updates — for example, as an application moves through stages — UbiQuity can trigger the relevant service email at each step. Because these are service communications rather than marketing messages, they are sent even if the contact has opted out of marketing emails. This is consistent with the intent of opt-out legislation, which is designed to protect consumers from unwanted marketing rather than from service-critical communications. *** ### Use cases **Customer-facing:** * Application, payment, or order confirmations * Password resets and account notifications * Status updates on an application, order, or payment **Operational:** * Service call or appointment confirmations * Notifications for dispatched documents or tickets * Progress updates as requests move through internal workflows *** ### Sending service messages via other channels Service messages are typically sent by email, but UbiQuity also supports sending them via TXT or push notification if those channels are more appropriate for your audience. # Service Messaging Send critical service communications to contacts even if they have opted out of marketing emails. Service messaging — sometimes called transactional messaging — allows you to send essential communications to your customers in real time, regardless of their marketing opt-out status. These are messages your customers need to receive, such as: * Order or application confirmations * Appointment reminders * Password resets * Status updates on a request or application * Insurance notifications * Dispatched documents or tickets Unlike marketing emails, service messages are triggered by a customer action or business event rather than a campaign schedule. > **Note:** Service Messaging requires setup by the UbiQuity team. Contact UbiQuity to discuss your requirements. *** ### How it works Service messages in UbiQuity are triggered from your transactional or relational database. As a customer record updates — for example, as an application moves through stages — UbiQuity can trigger the relevant service email at each step. Because these are service communications rather than marketing messages, they are sent even if the contact has opted out of marketing emails. This is consistent with the intent of opt-out legislation, which is designed to protect consumers from unwanted marketing rather than from service-critical communications. *** ### Use cases **Customer-facing:** * Application, payment, or order confirmations * Password resets and account notifications * Status updates on an application, order, or payment **Operational:** * Service call or appointment confirmations * Notifications for dispatched documents or tickets * Progress updates as requests move through internal workflows *** ### Sending service messages via other channels Service messages are typically sent by email, but UbiQuity also supports sending them via TXT or push notification if those channels are more appropriate for your audience. # Advanced Scheduling Schedule emails based on external events or individual contact date and time fields. UbiQuity offers two advanced scheduling options for Automated Mailouts: event-based scheduling and personalised email scheduling. Both extend the standard recurrence options to give you more precise control over when emails are sent. *** ### Event-based mailout scheduling Event-based scheduling triggers an Automated Mailout when a specific event occurs within UbiQuity. Currently, this is limited to triggering based on a completed API import with a custom tag. This removes the need to build external processes to anticipate when an import will happen and then trigger a send afterwards. Instead, you import your contacts via API with a custom tag, and when the import completes, UbiQuity automatically triggers any activated Automated Mailouts that are configured to look for that tag. **Example use case:** You want to send emails to customers at a time when call centre volumes are low. Import contact data via API at a quiet time, and any matching event-based mailouts will trigger automatically once the import finishes. > **Note:** Event-based mailout scheduling requires setup by the UbiQuity team. Contact UbiQuity if you are interested in this feature. #### Importing with a custom tag To trigger an event-based mailout, your API import must include a custom tag. When the import is complete and the tag is processed, UbiQuity evaluates all activated event-based mailouts and triggers any that match the tag. See the UbiQuity API documentation for details on importing contacts with a custom tag. #### Configuring an event-based mailout Event-based scheduling is configured on the **Recurrence** screen of an Automated Mailout: 1. On the Recurrence screen, toggle **Do you want to send regular emails when an event happens within UbiQuity?** to active 2. Enter the custom tag that will be present in the API import > The custom tag is case-sensitive and must be an exact match, including spaces. Once activated, the mailout will trigger automatically whenever a matching API import is completed. *** ### Personalised Email Scheduling Personalised Email Scheduling lets you send emails to individual contacts at a specific date and time stored in their database or transactional record. This allows you to personalise not just the content of an email, but when it is delivered. For example, if you know a group of VIP contacts are most likely to engage with emails first thing in the morning, you can store their preferred send time in a database field and use that to schedule their emails individually — Contact A at 9:00am, Contact B at 9:30am — all from a single mailout. > **Note:** UbiQuity will make every effort to deliver emails as close as possible to the scheduled time, but exact delivery cannot be guaranteed due to external factors such as system load and throughput. > **Note:** Personalised Email Scheduling requires setup by the UbiQuity team. Contact UbiQuity if you are interested in this feature. #### Requirements * Personalised Email Scheduling can only be used as part of an Automated Mailout * Your contact or transactional database must include a **Date and Time** field containing the desired send time for each contact * Contacts without a complete Date and Time value will not be scheduled to receive an email #### Configuring Personalised Email Scheduling On the **Recurrence** screen of an Automated Mailout, select **Send emails using a date and time field to determine scheduling**. This enables the Personalised Email Scheduling configuration. #### The 24-hour window Personalised Email Scheduling operates on a 24-hour window. Each day at the configured **Scheduling Start Time**, UbiQuity schedules all filtered contacts whose Date and Time field value falls within the next 24 hours. Those contacts are then ordered and sent at their individual scheduled times. > If the Scheduling Start Time is changed to run again later the same day, there is a risk of duplicate messages being sent to the same contact. # A/B Subject Testing Test two subject lines against each other to find the most effective one for your audience. A/B Subject Testing lets you send two different subject lines to segments of your contact list and automatically — or manually — select a winner to send to the remainder. It is available for both one-off mailouts and automated mailouts. *** ### One-off mailouts #### Adding subject lines In the **Content and Preview** screen of an unsent mailout, click **Add another subject line** below the subject line field. Add your second subject line — merge fields can be used in both versions. You can delete the second subject line at any time before sending if you decide to revert to a single subject. When previewing the mailout, both subject lines are shown. When sending a preview email, you are asked to specify which version to send. #### Setting segments and winning criteria Once both subject lines are saved, go to the **Schedule and Testing** screen. The page title updates to reflect that A/B testing has been detected. **Test segments** Drag the A/B testing slider to set the proportion of your contacts who will receive each test version. The range is 5% to 30% in 5% increments. The remaining contacts will receive the winning version once it is determined. You can also choose a 50/50 split — in this case all contacts receive one of the two versions and there is no winning version send. **Winning criteria** Choose whether the winner is determined by the highest **read rate** or the highest **click-through rate**. Set the testing time period — UbiQuity defaults to one day, but this can be set to between 1–23 hours or 1–5 days. Both read rate and click-through rate are calculated from delivered emails, not total recipients. If both versions perform identically, UbiQuity defaults to Version A as the winner. You can also select **Manually selected** as the winning criteria if you want to combine metrics or apply your own judgement when choosing a winner. > A 50/50 split does not have a winning version. You will only be able to schedule the mailout, not set winning criteria. #### Scheduling and confirming The schedule and send rate apply to both the initial test send and the winning version send. The Confirm screen shows a summary including the test splits, recipient counts, winning criteria, and the estimated timing for both phases of the send. #### Sending and selecting a winner When your A/B test is confirmed, both versions are sent simultaneously. As soon as the testing period ends, UbiQuity automatically sends the winning version to the remaining contacts. To manually select a winner at any point during sending, click **Select Winning Version** on the Mailout Dashboard. Select your preferred version and confirm — the remaining contacts will be sent that version immediately. You can override an automatically determined winning version using this button, provided the winning version send has not yet begun. #### Reporting The standard mailout report is extended with an A/B testing section below the overview. This includes: * Total reads and clicks for each version * A chart tracking results over the testing period * A **statistical significance** indicator showing how confident you can be in the result **Statistical significance** measures whether the difference in performance between the two versions is large enough to be meaningful rather than random. UbiQuity uses a 95% confidence threshold: * **Significant** — you can be confident the winning subject line made a difference * **Questionable** — there is likely a relationship, but the sample size may be too small to be certain * **Not significant** — the test cannot confidently conclude one subject line performed better The Mailout Folder Report is also extended to include both subject lines in the comparison section. *** ### Automated mailouts #### Creating a test In the **Content and Preview** screen of any Automated Mailout (sent or unsent), click **New subject line A/B test**. Give the test a name (used for reporting only — not visible to recipients) and add your second subject line. #### Segments and winning criteria Automated Mailout A/B tests use a fixed 50/50 split. This is because Automated Mailouts send all emails in a batch at the same time, leaving no window to delay the winning version. Automated Mailouts also typically send to smaller batches, making uneven splits impractical. Set the winning criteria — **highest read rate** or **highest click-through rate** — on the **Recurrence and Testing** screen. #### How a winner is selected Before selecting a winner, UbiQuity checks for both statistical significance and a minimum sample size (threshold). The thresholds are based on global read and click rates for Automated Mailouts. Until both conditions are met, the mailout continues sending both versions 50/50. Once a winner is confirmed, UbiQuity sends only the winning version from the next run onwards. **Selecting a winner manually** After the Automated Mailout has run at least once, a **Select as winner now** option appears in Content and Preview. Select the winning version and confirm — the mailout will send only that version from the next run. You can use this to override the automated selection at any time. #### Active vs inactive tests A test is **inactive** until the Automated Mailout runs for the first time after the test is saved. While inactive, the test name and subject lines can be edited. Once the mailout runs, the test becomes **active** and the subject lines, test name, and winning criteria are locked. To change these, you must end the test and create a new one. #### Ending a test Click **End test** on the Content and Preview screen to end an active test before a winner is selected. You will be asked to confirm. The subject line with the higher read or click rate at that point will be kept, and the report will reflect that no winner was formally selected. > Ending a test early means incomplete results. If you run the same subject lines again, you must give the test a new name and stats reset to zero. #### Reporting The Automated Mailout report is extended with an A/B testing section showing current and previous tests. Contact history records which version each contact received. You can also filter on A/B versions across all areas of UbiQuity. *** ### Tips for effective A/B testing * **Have a clear goal** — decide in advance what success looks like before you send * **Choose the right winning criteria** — reads and clicks are not always the best measure; consider what action you actually want contacts to take * **Give the test enough time** — rushing a test to meet a deadline can result in inconclusive data * **Be patient with smaller lists** — statistical significance takes longer to reach with smaller audiences * **Keep testing** — a single successful subject line is a starting point, not a destination * **Think long-term** — use A/B test insights to improve all your communications, not just the current campaign # Mailout Reports View and interpret the performance data for your mailouts. Once a mailout has been scheduled, the Mailout Report becomes available on the Mailout Dashboard. *** ### One-off mailout report The report is divided into five sections: **Details** Metadata for the mailout: name, send date, subject line, and pre-header text. **Overview** A summary of delivery, read, and click performance: * Emails delivered vs bounced * Read count and rate * Unique and total link clicks Click into any segment to view the contacts in that group. This creates a database filter that can be downloaded. **Links clicked** Performance data for each link in the mailout. Click into segments to view contacts who clicked a specific link or who did not click anything. Database filters are created automatically. **Email clients** A breakdown of which email clients were used to read the email, grouped into: * Desktop applications (e.g. Outlook, Thunderbird) * Webmail (e.g. Gmail, Yahoo) * Mobile (e.g. iPhone, Android) * Other (clients that could not be identified) A narrative can be added to each section using the **Edit** button. Sections can be collapsed and expanded. *** ### Automated mailout report Select a date or date range to view the performance of the Automated Mailout over that period. The same report sections and functionality as the one-off mailout report are available for the selected time range. **Removed links** — a separate section appears under Tracked Links for any links that have been removed from newer versions of the Automated Mailout. **Activity for the first day** A graph of email interactions over the first 24 hours. Use this to understand when your contacts engage with your emails. For longer-term analysis, create additional filters in the database. #### Mailout Report FAQs
How accurate are open or read rates? Email open rates across the industry have become increasingly inflated due to the widespread use of email security and threat-protection systems. Many corporate email platforms, including Microsoft 365 and Google Workspace and others, automatically scan incoming emails by opening messages and pre-checking links before the email reaches the recipient. These automated security processes are often recorded by email marketing platforms like UbiQuity as opens, even when the recipient has not yet viewed the message themselves. As a result, open rates are no longer considered a fully reliable measure of audience engagement, particularly for B2B campaigns where recipients are often protected by enterprise-grade email security systems. While open rates can still provide a broad indication of email deliverability and visibility, metrics such as click-through rates, website visits, form submissions, replies, and conversions generally provide a more accurate picture of genuine recipient engagement. For this reason, we recommend evaluating campaign performance using a combination of engagement metrics rather than relying solely on open rates.
Does Apple Mail Privacy Protection impact read rates? Since Apple introduced Mail Privacy Protection (MPP) in iOS 15, emails opened on Apple Mail are pre-loaded on proxy servers, which means they register as opened regardless of whether the recipient actually reads them. This inflates open rates for contacts using Apple Mail. Where open rate accuracy is important, focus on click-through rate as a more reliable metric, and consider segmenting your report by email client.
# Email Delivery and Statuses Understand how UbiQuity delivers emails and what each message status means. ### How emails are delivered Every email sent by UbiQuity is digitally signed using DKIM, which helps receiving mail servers verify the email is legitimate and improves deliverability. UbiQuity will also attempt to send emails using TLS encryption if the receiving mail server supports it. If not, the email is sent unencrypted. If a recipient marks an email as spam, UbiQuity automatically opts them out. This is handled through industry feedback loops that UbiQuity is enrolled in. *** ### Message statuses After sending a mailout, the **Mailout Recipients** screen shows a status for each message. Statuses can update for several days after a mailout is sent as delivery receipts come back from servers.
StatusMeaningCommon examplesWhat happens next
ScheduledUbiQuity is preparing the email or attempting delivery.Mailout still processing. Recipient inbox may be full. Carrier connectivity issues.UbiQuity will attempt to send or retry up to 12 times with increasing intervals.
PendingEmail is processed and queued for delivery.Often a temporary status. May indicate an A/B test where the winning version has not yet been selected.The email will be delivered or move to another status.
Soft-bounceUbiQuity was unable to deliver after exhausting retries.Inbox full. Destination server misconfigured. DNS timeout.The email will not be sent.
ErrorUbiQuity failed to process part of the email.Dynamic attachment could not be generated.The email will not be sent.
CancelledThe entire mailout was cancelled.A user cancelled the mailout from the dashboard.The email will not be sent.
Hard-bouncePermanent delivery failure.Mailbox does not exist. Domain not found (likely a typo).Missing merge field data in the From address.The email will not be sent. The contact is automatically set to GNA and excluded from future mailouts.
DeliveredUbiQuity has successfully delivered the email to the recipient's mail server.—The contact should receive the email.
*** ### Opt-outs and GNA Each contact in your database has two flags that determine whether they can receive emails: **Opted Out** and **GNA (Gone No Address)**. #### GNA If a contact receives a hard bounce from any mailout within UbiQuity, their GNA flag is set to Yes. They are then excluded from all subsequent mailouts. The GNA flag cannot be manually reset. The only way to remove it is to update the contact's email address — either manually, by import, or via the API. Changing the email address resets the GNA flag and the contact will start receiving emails again. #### Opted Out Contacts who have clicked an opt-out link in an email and set their Opted Out field to Yes will not receive future mailouts. You can manually change the Opted Out flag for a contact, but only do so if you have a valid reason — sending emails to opted-out contacts is against the law and can harm your sender reputation. > **Important:** Do not delete GNA or opted-out contacts from your database to work around these restrictions. Leave them in UbiQuity and allow UbiQuity to manage exclusions for you. Deleting and re-importing contacts can seriously damage your deliverability. Note that GNA and opted-out contacts will still receive triggered emails from Forms, Surveys, and Events as triggered emails are classified as service messages. These exclusions apply only to mailouts and automated mailouts. # Building Optimised Emails Best practices for creating emails that display correctly across devices and email clients. Email optimisation is the practice of ensuring your emails display and function correctly across all the major email clients, apps, and devices — without compromising design or usability. Both custom and default UbiQuity EasyEdit templates are built to be responsive and optimised for most tablets, mobiles, and email clients out of the box. *** ### How responsive emails work UbiQuity email templates use **Media Queries** — a CSS standard that allows styles to adapt based on the screen size, resolution, and orientation of the device. When a recipient opens the email, if their device matches a media query, the appropriate styles are applied. For example, a media query might specify that on screens narrower than 600px, images stack vertically instead of sitting side by side. *** ### What an optimised email looks like | Device | Expected behaviour | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | Desktop | Email centred with background colour and margins. Images full-size and correctly aligned. | | Tablet | Similar to desktop with slightly reduced margins. Images retain size. Alignment unchanged in portrait and landscape. | | Mobile | Email padding removed. Images and content stack in vertical panels. Header, footer, and content images re-aligned. Footer links and social icons stacked. | *** ### Email client types How an email renders depends not just on the device, but on the email client being used. There are three main categories: **Email apps** — downloaded or pre-installed apps (e.g. Apple Mail, Gmail mobile app). The operating system and version can affect rendering. **Desktop clients** — software installed on a computer (e.g. Outlook, Apple Mail on Mac). Also affected by OS version. **Web-based clients** — accessed via a browser (e.g. Gmail, Yahoo, Outlook.com). These often strip custom CSS and apply their own styles. *** ### Fonts Fonts are one of the most important design elements in email, as they need to render consistently across clients and devices. Many email clients block images by default, so recipients often see text before anything else — making font choice and fallback stacks important. **Email-safe fonts** are fonts that are installed on most devices across Windows and Mac. Always specify a fallback font stack ending with a generic category. Example: `{ font-family: Helvetica, Arial, sans-serif; }` **Recommended email-safe fonts:** *Serif:* Courier, Courier New, Georgia, Times, Times New Roman *Sans-serif:* Arial, Arial Black, Tahoma, Trebuchet MS, Verdana **Custom fonts** Custom fonts are supported on a limited number of email clients. For clients that do not support them, UbiQuity will fall back to the email-safe font you have configured. Custom fonts are supported on: | Client | Supported | | -------------------------------- | --------- | | Apple iOS (iPhone/iPad) | Yes | | Android (default email client) | Yes | | Apple Mail (desktop) | Yes | | Microsoft Outlook | No | | Microsoft Outlook for Mac | No | | Gmail (desktop and mobile app) | No | | Outlook (desktop and mobile app) | No | | Yahoo | No | *** ### Testing tips * Always test across more than one device and email client * Use your mailout report to identify the email clients most used by your audience — focus testing effort there * Make sure the very last change is tested before sending, even small tweaks can affect rendering * Keep a working version of your template as a control for comparison * Never forward an email when testing — email clients modify emails when forwarding, which distorts the rendering * Test the View Online link in mobile browsers as well as apps # Interactive Emails Add interactive elements to your email campaigns to increase engagement. Interactive emails allow recipients to engage with content directly in their inbox — without needing to visit a separate landing page. Using CSS and HTML techniques, you can add movement, navigation, and input to your emails. Interactive emails are more complex to build than standard emails and require support from the UbiQuity team. Contact UbiQuity to discuss what is possible for your campaigns. *** ### What you can do with interactive emails * **Accordions and menus** — group information into collapsible sections * **CSS animations** — add movement and motion to your template * **Carousels** — let recipients scroll through a gallery or product range * **Embedded video** — allow video to be played directly in the email * **Animated GIFs** — draw attention with motion (*note: GIFs are not supported in Outlook versions prior to 2019*) * **In-email forms** — capture information entered directly into the email, such as NPS scores or survey responses *** ### Compatibility Interactive elements are supported on a limited number of email clients. For unsupported clients, a fallback version of the email must be provided so that all recipients have a functional experience. | Client | Supported | | -------------------------------- | --------- | | Apple iOS (iPhone/iPad) | Yes | | Samsung (default email client) | Yes | | Apple Mail (desktop) | Yes | | Microsoft Outlook | No | | Microsoft Outlook for Mac | No | | Gmail (desktop and mobile app) | No | | Outlook (desktop and mobile app) | No | | Yahoo | No | Before building an interactive email campaign, check the proportion of your database using supported clients — this will help determine whether interactive elements are worth the additional investment and whether the fallback experience is sufficient for your audience. *** ### Fallback emails Because some recipients will open your email in a client that does not support interactive elements, a fallback version of the email must be created alongside the interactive version. The fallback is a standard email using similar content and assets. In some cases this is a simple swap of assets. In others, the layout or content may need to be adjusted for the fallback to make sense on its own. *** ### Tracking Tracking for interactive emails is currently limited to external URL links and the View Online link. Events within the email — such as scrolling, entering fields, or clicking interactive elements — are not tracked directly. Responses captured in-email (such as survey answers) can be passed to a UbiQuity Survey to record and report on. # TXT Send targeted TXT messages to your contacts directly from UbiQuity — from simple one-off sends to multi-step automated programmes. UbiQuity TXT is a fully featured TXT messaging channel built into the UbiQuity platform. You can send one-off TXT Outs to your database contacts, set up automated TXT Outs triggered by date-based conditions, or build multi-step inbound TXT programmes that respond to messages your contacts send in. Because TXT is managed alongside your other channels in UbiQuity, you can segment your audience using the same database contacts and filters you use for email and push notifications. You can also combine channels — for example, sending a TXT when an email bounces. UbiQuity TXT uses dedicated shortcodes registered with all carriers in New Zealand. The UbiQuity team will work with you to get your shortcode set up before you can start sending. *** ### What you can do with TXT * Send one-off TXT Outs to contacts in your UbiQuity database * Set up automated TXT Outs that trigger based on dates or contact data * Build inbound TXT programmes with multi-step workflows and conditional logic * Capture data via TXT — including email addresses and survey responses * Track link clicks within TXT messages * Manage opt-outs automatically using the STOP process *** ### Supported regions UbiQuity TXT supports New Zealand mobile numbers via shortcodes registered with all NZ carriers. If you need to send to international numbers, an international long code is required — contact UbiQuity to arrange this. *** ### TXT and the law TXT messaging in New Zealand is governed by the Unsolicited Electronic Messages Act 2007, administered by the Department of Internal Affairs. You are responsible for ensuring your TXT communications comply with all applicable legislation. See TXT Message Guidelines for a summary of key requirements. *** ### Using the TXT API If you prefer to integrate programmatically, the UbiQuity API supports sending and receiving TXT messages. Once your account is set up for TXT, contact UbiQuity to register your endpoint. Inbound messages will be passed through to your endpoint, and you can send messages via the API. See the UbiQuity API documentation for details. *** ### In this section * TXT Message Guidelines — Compliance requirements for TXT messaging in New Zealand * TXT Concepts — Shortcodes, keywords, programmes, and the STOP process * TXT Programmes — Set up and build inbound TXT programmes * Sending a TXT Out — Create and send a one-off TXT Out to your database * Automated TXT Outs — Schedule TXT Outs based on dates or contact data * View Messages — View message history and understand delivery statuses # TXT Message Guidelines Understand the compliance requirements for sending TXT messages in New Zealand. Before sending TXT messages through UbiQuity, it is important to understand the legal requirements that apply. TXT messaging in New Zealand is regulated under the Unsolicited Electronic Messages Act 2007. This page summarises the key requirements - for full details, refer to the Department of Internal Affairs resources linked at the bottom of this page. *** ### Message types There are two main categories of TXT message, each with different requirements. **Service / Transactional messages** are sent in response to a relationship or transaction with the recipient. Examples include appointment reminders, renewal notices, and delivery updates. **Marketing messages** are promotional in nature. Examples include sale announcements and promotional offers. Because the requirements differ between these two types, we recommend using a separate shortcode for each type of communication. See TXT Concepts for more on shortcodes. *** ### Opt-in requirements For marketing TXT messages, you must have explicit opt-in consent from the recipient. This means: * The opt-in must be a separate, unticked checkbox - not bundled with other consent * It must be clearly labelled, for example: *"I consent to receive promotional offers via TXT"* * The TXT opt-in should be separate from any email marketing opt-in If your TXT programme is initiated by the recipient texting in - for example, a radio promotion asking customers to text a shortcode - this inbound message constitutes implicit consent. *** ### Required message content There are minimum content requirements depending on the message type. **Service messages must include:** * The sender's name within the message body * The message *"Standard TXT charges apply"* if the shortcode is not zero-rated **Marketing messages must include:** * The sender's name within the message body * A clear opt-out instruction at the end of the message, for example: *"Opt-out: reply STOP"* * The opt-out channel must match the outbound channel - you cannot direct TXT recipients to email to opt out *** ### TXT length A single TXT is a message of **up to** 160 characters. If your message goes over 160 characters then the TXT will be split into parts made up of **153 characters.** This is not a limitation from UbiQuity but an industry standard. This means that messages will be charged as follows: up to **160** characters = 1 TXT\ up to **306** characters = 2 TXT\ up to **459** characters = 3 TXT with each increase of 153 characters adding an additional TXT send cost The contact will see any message over one part as a single TXT within their device. *** ### Further reading For full guidance on TXT/SMS regulations in New Zealand, refer to the Department of Internal Affairs: * [Commercial electronic messaging for businesses](https://www.dia.govt.nz/Spam---Commercial-electronic-messaging-in-New-Zealand) * [Frequently asked questions: TXT](https://www.dia.govt.nz/Spam-Frequently-Asked-Questions#tex) # TXT Concepts Understand the key concepts behind UbiQuity TXT before setting up your programmes and sends. This page explains the core building blocks of UbiQuity TXT - shortcodes, keywords, programmes, and the STOP opt-out process. Understanding these will help you set up and manage your TXT activity correctly. *** ### Shortcodes A shortcode is the number your contacts will send TXT messages to and receive TXT messages from - for example, 3611. UbiQuity will set up your shortcode and register it with all TXT carriers in New Zealand. A single shortcode can be shared across multiple TXT programmes, provided those programmes have similar content. If you plan to send different types of TXT communication - for example, both service messages and marketing messages - you should use separate shortcodes to remain compliant with NZ legislation. See [TXT Message Guidelines](/documentation/channels/txt/txt-message-guidelines) for more detail. Once your shortcode is assigned to your UbiQuity account and your user has the appropriate permissions, you are ready to start using TXT. {% hint style="info" %} **Note:** It is common to receive occasional random or misdirected inbound messages on a shortcode. These can be ignored. {% endhint %} *** ### International long codes If you need to send TXT messages to international mobile numbers, you will need an international long code set up on your account. Contact UbiQuity to arrange this. *** ### Keywords When an inbound TXT message arrives, UbiQuity uses the first word of the message - the keyword - to route it to the correct TXT Programme. For example, a message starting with *SUBSCRIBE* will be routed to the TXT Programme configured with the keyword *SUBSCRIBE*. Any additional content after the keyword (such as an email address) is also available to the programme for processing. For each shortcode, you can have one keywordless programme. Any inbound messages that do not start with a recognised keyword will be routed to this programme. Keywords must be alphanumeric, contain no spaces, and be between 1 and 50 characters. *** ### TXT Programmes A TXT Programme is a workflow that handles inbound TXT messages. When a message arrives with a matching keyword, the programme runs its steps in sequence. Some programmes complete in a single step - for example, replying with a recipe or a piece of information. Others involve multiple steps and wait for further inbound messages before continuing. When a programme is waiting for a follow-up message, the mobile number is locked to that programme for 24 hours or until the end of the workflow is reached. No keyword is required for subsequent messages in the same workflow - UbiQuity knows which programme that number is engaged with. TXT Programmes can also be configured to send outbound TXT Outs to your database contacts. See TXT Programmes for full details on setting up and building a programme. *** ### The STOP process When you send marketing TXT messages, recipients must be able to opt out by replying STOP. UbiQuity manages this automatically. How STOP messages are handled depends on whether a keyword is included: * **"STOP"** (no keyword) - UbiQuity cannot determine which specific programme the contact is opting out from, so all TXT opt-in fields for that shortcode are set to No across the entire UbiQuity database. The contact will be excluded from all future TXT Outs on that shortcode. * **"STOP \[keyword]"** (with keyword) - Only the opt-in field for the specific TXT Programme associated with that keyword is set to No. The contact will be excluded from future TXT Outs for that programme only. If a mobile number appears more than once in your database, every matching contact record is updated. # TXT Programmes Set up and build TXT programmes to handle inbound messages and send TXT Outs to your database. A TXT Programme is the foundation of UbiQuity TXT. Programmes manage inbound TXT messages using a workflow of steps, and can also be configured to send outbound TXT Outs to contacts in your UbiQuity database. Before you can use TXT, the UbiQuity team will need to enable the TXT module on your account and set up your shortcode. Once that is done, you are ready to create your first programme. *** ### Creating a TXT Programme When creating a new TXT Programme, you will be prompted to choose a programme type: | Option | Description | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Send TXTs to my database | Configures the programme to send TXT Outs to contacts in your UbiQuity database. Requires a database opt-in field to manage STOP requests. | | Provide a TXT subscription service | Allows contacts to subscribe by texting in the keyword. Adds or updates the contact in your database and sets their opt-in field to Yes. Also enables TXT Outs to these contacts. | | Collect email addresses | Accepts an inbound TXT containing the keyword followed by an email address (e.g. *SUBSCRIBE* [*john@example.com*](mailto:john@example.com)). Validates the email address and adds or updates the matching contact in your database. | | Build my own inbound programme | Starts with a blank workflow for you to build from scratch. | *** ### Programme settings Any inbound TXT message starting with your configured keyword will trigger this programme. For time-based promotions, you can set an optional start and/or end date. If the message arrives outside these dates, the programme will run the steps defined in the **Too Early** or **Too Late** workflow instead of the standard flow. If you are using the UbiQuity API to send TXT messages and want delivery receipts, enter your endpoint URL in the **API Message Status URL** field. UbiQuity will return the message ID, status, and timestamp for each message sent via the API. *** ### Building the workflow When an inbound TXT arrives with the matching keyword, the programme runs its workflow steps in sequence. You build the workflow by dragging widgets onto the canvas. #### Receive and Process This is always the first widget in a workflow. It waits for an inbound TXT message to arrive and can optionally validate the content. The keyword is automatically stripped from the incoming message. The remaining content is available positionally — the first word after the keyword is position 1, the second is position 2, and so on. You can assign variable names to these positions for use in later widgets. #### Send TXT Sends a TXT message to the contact. You can use merge fields to personalise the message, including any variable names assigned in the Receive and Process widget. #### Database Lookup Checks whether a matching record exists in your UbiQuity database. You specify which database field to match against and what value to compare it to. If a match is found, the widget is successful and the workflow continues down the success path. #### Database Update Updates or adds a record in your UbiQuity database. Inbound TXT messages do not automatically update the database - you must use this widget to write any data. Set the **Update Type** to: | Option | Behaviour | | ---------- | ----------------------------------------------------------------------- | | Add | Adds a new contact to the database. | | Update | Updates an existing contact. Use Match Criteria to identify the record. | | Add/Update | Adds the contact if they do not exist; updates them if they do. | If your database has mandatory fields (such as email address), an attempt to add a contact without those fields will fail. Database rules are managed under **Database > Edit Database Fields**. If your database rules are restrictive, you may want to create a separate UbiQuity account for TXT. #### Web Request Calls a URL when the workflow reaches this step. By default, UbiQuity makes the request in the background and immediately moves to the next step. You can optionally wait for a response and then branch based on success or failure (anything other than a 200 response is treated as a failure). This widget can be used to call any URL, including the UbiQuity API. #### Conditional Branching Routes the workflow to different steps based on conditions you define. You can branch on database fields, values received in the TXT message, or variable names assigned earlier in the workflow. *** ### Tracking links You can track links included in your TXT Programme for reporting purposes, and to use link click data for targeting future TXT Outs. When a link is tracked, it is converted to a shortened URL in the outgoing message. By default, shortened URLs begin with *t.uq.nz*. This can be customised to use your own domain - contact UbiQuity to arrange this. If you do not want a link to be shortened or tracked, untrack it on the Track Links screen. Untracked links will display as entered and will not appear in click reports. Use **Get Friendly Names** to automatically fetch the page title for each link, making reports easier to read. If your website uses Google Analytics, you can also append tracking codes to links from this screen. *** ### Configuring for TXT Outs To send TXT Outs from a TXT Programme, the programme must be configured for TXT Outs. This can be done during the create wizard or at any time afterwards. Configuring for TXT Outs requires you to select or create a database opt-in field. When a contact replies STOP, UbiQuity sets this field to No and excludes the contact from future TXT Outs for this programme. If you allow UbiQuity to create the field, it will be named after the TXT Programme. You can set up steps in the workflow so that a contact texting in automatically sets this field to Yes. For more detail on how STOP messages are handled, see TXT Concepts. # Creating a TXT Out Create and send a one-off TXT message to contacts in your UbiQuity database. A TXT Out is a one-off outbound TXT message sent to contacts in your UbiQuity database. Before you can send a TXT Out, your account must be set up for TXT and your TXT Programme must be configured for TXT Outs. See [TXT Programmes](/documentation/channels/txt/txt-programmes) for details. *** ### Content and Preview Content and Preview is where you write your TXT message. You can insert merge fields to personalise the message using contact data from your database. If your TXT Out is a marketing message, include a STOP opt-out instruction at the end - for example, *"Opt-out: reply STOP \[keyword]"*. Whether this is required depends on the type of message being sent. See TXT Message Guidelines for guidance. Use the preview function to check how merge fields will appear for specific database contacts before sending. *** ### Filter The filter screen lets you target a specific segment of your database contacts. You can filter by: * Database contact fields * Results from previous TXT Outs * Interactions with other UbiQuity channels such as mailouts and push notifications #### AND and OR conditions **AND** - all conditions must be true for a contact to be included. *Example: Country = New Zealand AND Segment = Customer includes only contacts who are customers in New Zealand.* **OR** - either condition can be true for a contact to be included. *Example: Country = New Zealand OR Segment = Customer includes all contacts in New Zealand plus all customers, regardless of country.* #### Automatically excluded contacts Some contacts are always excluded from TXT Outs regardless of your filter: * Contacts flagged as **GNA (Gone No Address)** - contacts are marked GNA automatically when a TXT message hard bounces. The TXT GNA field in the database is updated accordingly. * Contacts who have **opted out** of TXT communications for this programme. *** ### Track links You can track links included in your TXT Out for reporting and future targeting. Tracked links are converted to shortened URLs in the outgoing message. By default these begin with *t.uq.nz*, but this can be customised to your own domain. If you do not want a link to be shortened or tracked, either untrack it on the Track Links screen, or insert the URL without the *https\://* prefix (e.g. [*www.example.com*](http://www.example.com) instead of [*https://www.example.com*](https://www.example.com)). In either case the link will not be tracked and click data will not be available. Use **Get Friendly Names** to fetch the page title for each link automatically. If your website uses Google Analytics, you can append tracking codes to links from this screen. *** ### Dedupe The Dedupe screen lets you remove duplicate contacts from your TXT Out. Select the field or fields that indicate a duplicate - UbiQuity will send only one message per unique value for those fields. To prevent duplicates from entering your database in the first place, you can set Unique Fields on your database under **Database > Edit Database Fields**. *** ### Schedule and Confirm You can choose to prepare the TXT Out now or at the time of sending. | Option | Behaviour | | -------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Prepare now | Filters and contact data are applied immediately. Changes to your database after this point will not affect the TXT Out. | | Prepare at send time | Filters and contact data are applied at the scheduled send time, reflecting your database as it is then. | The maximum send rate for TXT Outs is 30,000 messages per hour. If you choose to send all messages immediately, UbiQuity will default to this maximum rate. If you choose to send at an hourly rate, it must be set to 30,000 or fewer per hour. # Creating an Automated TXT Out Set up TXT Outs that send automatically on a recurring schedule, triggered by date-based conditions in your contact data. Automated TXT Outs let you send TXT messages to contacts based on dates or lifecycle events — without having to manually send each time. Common uses include: * Sending a birthday TXT * Following up with a contact a set number of days after a purchase * Notifying a contact before their subscription expires * Sending a welcome TXT when a contact joins, with follow-ups one and two weeks later *** ### Creating an Automated TXT Out When you create an Automated TXT Out you are taken to the Automated TXT Out Dashboard. From here you can step through the wizard: 1. **Content and Preview** 2. **Filter** 3. **Dedupe** 4. **Recurrence** 5. **Activate** An Automated TXT Out will not run until it has been activated. Once activated, the dashboard updates to include reporting and a history of runs. To make changes, deactivate it first. Use **Run Now** to trigger the Automated TXT Out immediately outside of its schedule. *** ### Content and Preview Content and Preview works the same way as for a standard TXT Out. Write your message, add merge fields, and include a STOP opt-out instruction if required. Use the preview function to check merge fields against database contacts. See TXT Message Guidelines for guidance on when a STOP message is required. *** ### Filter The filter for an Automated TXT Out works similarly to a standard TXT Out filter, with the addition of a **When Filter**. #### When Filter The When Filter lets you target contacts based on date fields using relative operators, for example: * *5 days after Purchase Date* * *2 days before the anniversary of Birthdate* **Anniversary options** ignore the year part of a date. This means the Automated TXT Out will send each year on the correct day and month, regardless of the year in the database. The Filter and the When Filter work together as an **AND** condition — both must be true for a contact to be included. *Example: Filter — City = Auckland, When Filter — 2 days before the anniversary of Birthdate. This will only send to contacts in Auckland, two days before their birthday.* Use the preview function to test your filter logic by selecting a date and clicking **Refresh**. #### Automatically excluded contacts As with standard TXT Outs, contacts flagged as **GNA** or who have **opted out** are automatically excluded. Contacts are marked GNA when three consecutive TXT messages to their mobile number fail to deliver. *** ### Dedupe The Dedupe screen removes duplicate contacts from each run of the Automated TXT Out. Duplicates are calculated at the time the Automated TXT Out runs, not when it is set up. Select the field or fields that indicate a duplicate. To prevent duplicates in your database, set Unique Fields under **Database > Edit Database Fields**. *** ### Recurrence Set how often the Automated TXT Out should run — for example, daily, weekly, or monthly. *** ### Activate Once you are satisfied with your setup, activate the Automated TXT Out. The dashboard will update to show reporting and a run history. To make changes after activation, deactivate the Automated TXT Out first, then edit and reactivate. *** ### TXT Out Projections Once your Automated TXT Out is active, the **TXT Out Projections** section shows how many messages are expected to be sent on future dates. Click on a date to see the projected send count for that day. Projections are estimates based on current data. The actual number sent may differ if your database changes before that date. # View Messages View all inbound and outbound TXT messages for your UbiQuity account and understand delivery statuses. Go to **TXT > View Messages** to see all TXT messages sent to and from your UbiQuity account. Click on any message to see the full content. Note that only inbound messages matching a keyword for a TXT Programme in your account will appear here. Random or misdirected messages that do not match a keyword will not show up. If you have sent TXT Outs, you can also view TXT history at the contact level by opening a database contact and viewing their contact history. *** ### TXT statuses The Status column on the View Messages screen shows the current delivery status of each message. Statuses can sometimes update for a few days after a TXT Out has been sent as delivery receipts come back from carriers.
StatusMeaningCommon examplesWhat happens next
ScheduledUbiQuity is preparing the message for delivery or attempting to deliver it.The TXT Out is still being processed. The recipient's inbox may be full. UbiQuity may be having trouble reaching the carrier.UbiQuity will either send the message successfully or attempt to resend.
PendingUbiQuity has processed the message and it is queued for delivery.—The message will be delivered or move to another status.
Soft-bounce / Transient FailureUbiQuity was unable to deliver the message and the retry schedule has been exhausted.The recipient's inbox is full. The handset has insufficient funds. The carrier is experiencing temporary issues. UbiQuity is experiencing temporary issues.The message will not be sent.
ErrorUbiQuity has failed to process part of the TXT.UbiQuity is unable to find a phone network for the recipient's number.The message will not be sent.
CancelledThe entire TXT Out has been cancelled.A user cancelled the TXT Out using the Cancel button on the TXT dashboard.The message will not be sent.
Hard-bounce / Permanent FailureUbiQuity has failed to process the message or received a permanent failure from the carrier.Number unreachable — the phone may be roaming or the shortcode may be blocked. The carrier rejected the message. A required merge field contained a blank value.The message will not be sent. The contact will be automatically flagged as GNA and excluded from future TXT Outs.
DeliveredUbiQuity has successfully submitted the message to the carrier for delivery.—The contact should receive the message.
ReceivedUbiQuity has successfully received this message. Applies to inbound TXTs and STOP requests only.——
# Push Send targeted push notifications to your mobile app users directly from UbiQuity. UbiQuity Push lets you send notifications directly to users of your mobile app. If you have an iOS or Android app connected to UbiQuity, you can send targeted, personalised push notifications to your app users — even when the app is closed. Push notifications are managed alongside your other channels in UbiQuity, which means you can segment your audience using the same database contacts and filters you use for email and SMS. You can also link app users to database contacts to take advantage of multi-channel messaging — for example, sending a push notification if an email bounces. *** ### What you can do with Push * Send one-off notifications to all app users or a filtered segment * Personalise messages using database contact fields * Set up automated notifications that trigger based on dates or contact data * Register multiple apps against a single UbiQuity account * Link app users to database contacts for cross-channel messaging *** ### Supported platforms UbiQuity Push supports iOS and Android apps. *** ### In this section * [Apps](/documentation/channels/push/apps) — Register and manage your apps in UbiQuity * [Connecting Your App](/documentation/channels/push/connecting-your-app) — Developer guide for integrating your app with UbiQuity * [Notification Templates](/documentation/channels/push/notification-templates) — Create reusable templates for your notifications * [Notifications](/documentation/channels/push/creating-a-notification) — Create and send a push notification * [Automated Notifications](/documentation/channels/push/creating-an-automated-notification) — Set up notifications that send automatically on a schedule or trigger *** ### A note on permissions App users control their own notification settings at the device level. On iOS, users can choose whether to allow notifications from an app and how alerts are displayed. Android works similarly, with notification settings managed within the app or device settings. UbiQuity sends the notification to the device — whether it is shown to the user depends on the permissions the user has set. Notifications can appear even when the app is closed or the device is locked, as long as the user has notifications enabled. # Apps Register and manage your mobile apps in UbiQuity before sending push notifications. In UbiQuity, an app corresponds to a mobile app you have developed that is installed on your users' devices. Before you can send push notifications, your app needs to be registered in UbiQuity. You can register multiple apps against a single UbiQuity account. Each notification you send is associated with a specific app, and only devices registered for that app will be available to target when you set up your filter. *** ### Registering an app Registering an app in UbiQuity requires setup by the UbiQuity team. Contact UbiQuity to get your app registered. Once your app is registered, you will be able to: * Send notifications to users who have the app installed * View registered devices for that app * Link app users to database contacts for segmentation and personalisation *** ### Managing apps Once an app is registered, it will appear in your UbiQuity account and can be selected when creating a notification. > **Note:** If you delete an app, all notifications associated with that app will also be deleted. For information on how to integrate your app with UbiQuity from a development perspective, see Connecting Your App. # Connecting Your App A developer guide for integrating your mobile app with the UbiQuity API to enable push notifications. To send push notifications through UbiQuity, your mobile app needs to be integrated with the UbiQuity API. This involves adding API calls to your app code and ensuring your app is set up to receive push notifications. This page is intended for developers integrating a mobile app with UbiQuity. *** ### Overview Your developers will need to: 1. Add API calls that register the device with UbiQuity each time the app is opened 2. Ensure the app is set up to display push notifications when they arrive Once your app has been set up and registered with UbiQuity, you will be able to send push notifications to users who have the app installed. For API reference documentation, see the UbiQuity API docs under `/push`. *** ### Recommended API calls Each time your app is opened, call: ``` POST /push/apps/{appID}/registrations/{deviceToken} ``` Calling this on every app open ensures the device is registered even if a previous call failed. If the app is uninstalled, call the API to unregister the device from UbiQuity. #### Linking to a database contact The registration endpoint includes an optional `referenceID` parameter. This is the GUID of a UbiQuity database contact. Linking a device registration to a database contact unlocks the full segmentation and personalisation capabilities of UbiQuity — you can filter and target push notifications using all the data available against that contact, including results from mailouts, TXT messages, surveys, and events. If you register a device without linking it to a database contact, you can still send push notifications, but segmentation and merge field personalisation will be limited. #### Optional data fields You can also pass optional fields `data1`, `data2`, and `data3` when registering a device (for example, a name or email address). These make it easier to identify registered devices in UbiQuity, which would otherwise appear as a list of IDs. #### Transactional data You can pass data about how the app is being used via UbiQuity Transactional Tables. This lets you store relational information against a database contact — for example, recording when a specific feature is used — and then filter and segment on that data when sending notifications. *** ### Device tokens Device tokens are used to uniquely identify each device within UbiQuity. A stable device token should be maintained for each device to prevent the same device being registered multiple times. | Platform | Recommended approach | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | iOS | Use `identifierForVendor` or a custom ID generated with `NSUUID`. Store the ID in Keychain to prevent it changing if the app is uninstalled and reinstalled. | | Android | Use `ANDROID_ID`. | *** ### Push tokens To send push notifications to a device, the device must first register with Apple or Google's servers. Those servers return a secure token that is used to route notifications to that device. UbiQuity refers to this as the **push token**. Each platform uses a different name for this token: | Platform | Name | | -------- | --------------- | | iOS | Device Token | | Android | Registration ID | Note that push tokens can change. This is why UbiQuity uses your own device token (described above) as the stable identifier for each device, rather than relying on the push token. # Notification Templates Create and manage reusable templates to save time when building push notifications. Notification templates let you save notification content that you can load and reuse when creating a push notification. Templates are optional but useful if you send similar notifications regularly. *** ### Content The content field is the message that will appear on the user's device. You can use merge fields to personalise the message — for example, inserting the recipient's name. If your app registrations are linked to UbiQuity database contacts, you can merge any available database fields into your notification content. *** ### iOS settings | Field | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sound | The sound that plays when the notification is received. The sound file must be saved in your iOS app bundle. Include the file extension. If not specified, or if the file is not found, the default alert sound plays. | | Action Button Text | The label on the action button when the notification appears as an alert. Not shown in banner format. Used as a localisation key if the app supports multiple languages. Defaults to "View". | | Launch Image | The image shown before the app opens when a user taps the action button. Must be saved in the iOS app bundle. If not specified, the system falls back to a previous snapshot, the app's launch image, or the iOS default. | *** ### Android settings | Field | Description | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Collapse Key | A key used to group similar messages when the device is offline, so only the most recent message is delivered when the device comes back online. Up to four collapse keys are allowed per app. Required if setting a Time to Live value. | *** ### Custom data Custom data lets you pass additional key-value pairs through to your app when a notification is received. Your app can be coded to read these values and change its behaviour accordingly. For example, you could define an `action` key with possible values such as `competitionResults` or `latestNews`. When a user taps the notification, the app reads the `action` value and navigates to the relevant screen rather than the default home screen. Custom data is highly flexible and allows you to get more out of your push notifications by driving behaviour within your app. *** ### Character limits Both iOS and Android have limits on the total size of a push notification payload. | Platform | Limit | | -------- | ---------------- | | iOS | 2,048 characters | | Android | 4,096 characters | The character count includes all sections of the notification — not just the message content. Changes to iOS settings, Android settings, or custom data will all increase the character count for the relevant platform. The count may increase by more than the number of characters you type. This is because UbiQuity includes additional formatting code in the payload sent to the device. For example, adding a single character to the iOS sound field increases the character count by six. If a notification exceeds the limit, the content will be trimmed automatically to fit within the limit for each device type. *** ### Previewing a template Use the preview function to see how merge fields will appear for a specific registered device. Select a device type (iOS or Android) to preview only the sections relevant to that platform. Use the character count alongside the preview to check that messages are not too long once data is merged in. # Creating a Notification Create, schedule, and send a push notification to your app users. Use Notifications to send a push notification to devices with your app installed. You can target all registered devices or filter to a specific segment. Before sending a notification, your app must be registered with UbiQuity. See Apps for details. *** ### Creating a notification When you create a notification you are taken to the Notification Dashboard. From here you can step through the notification wizard: 1. **Content and Preview** 2. **Filter** 3. **Schedule and Confirm** UbiQuity saves your progress at each step, so you can come back and continue working on a notification at any time. You can also click **Confirm** to jump directly to the confirmation step. *** ### Content and Preview Content and Preview is where you build the notification content. You can write the message, apply iOS and Android settings, and add custom data. For details on the content fields available, see Notification Templates. The same fields apply when building a one-off notification. *** ### Filter The filter screen lists all devices registered for the selected app. If devices were linked to database contacts when registered, you will also see the associated contact data. You can filter by: * Registered device fields * Database contact fields * Results from previous notifications * Interactions with other UbiQuity channels such as mailouts and TXT messages * Survey or event responses (if sent via UbiQuity Mail or TXT) A contact may have multiple devices registered. Filtering for a contact will return all devices associated with that contact. #### AND and OR conditions **AND** — all conditions must be true for a contact to be included. *Example: Country = New Zealand AND Segment = Customer includes only contacts who are customers in New Zealand.* **OR** — either condition can be true for a contact to be included. *Example: Country = New Zealand OR Segment = Customer includes all contacts in New Zealand plus all customers, regardless of country.* *** ### Schedule and Confirm You can choose to prepare the notification now or at the time of sending. | Option | Behaviour | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Prepare now | Filters and contact data are applied immediately. Changes to your database after this point will not affect the notification. | | Prepare at send time | Filters and contact data are applied at the scheduled send time, reflecting your database as it is then. | If you are sending a notification that invites recipients to contact a call centre, consider scheduling at an hourly rate to help manage incoming traffic volume. *** ### Pausing and cancelling Once a notification has been scheduled, you can pause or cancel it from the Notification Dashboard, provided not all messages have already been delivered. The notification report shows how many messages were delivered. # Creating an Automated Notification Set up push notifications that send automatically based on a schedule or date-based triggers. Automated Notifications let you set up push notifications that send automatically on a recurring schedule, triggered by date-based conditions in your contact data. *** ### When to use Automated Notifications Automated Notifications are useful for time-based or lifecycle messaging, for example: * Sending a birthday notification * Notifying a contact before their subscription expires * Sending a welcome notification when a device is first registered, with follow-ups one week and two weeks later *** ### Creating an Automated Notification When you create an Automated Notification you are taken to the Automated Notification Dashboard. From here you can step through the wizard across the following sections: 1. **Content and Preview** 2. **Filter** 3. **Recurrence** 4. **Activate** An Automated Notification will not run until it has been activated. Once activated, the dashboard updates to include reporting and history. To make changes, deactivate the notification first. Use **Run Now** to trigger the Automated Notification immediately outside of its schedule. *** ### Content and Preview Content and Preview works the same way as for a standard notification. See Notification Templates for details on the available content fields. *** ### Filter The filter for an Automated Notification works similarly to a standard notification filter, with the addition of a **When Filter**. #### When Filter The When Filter lets you target contacts based on date fields, using relative operators such as: * *5 days after Sign-up Date* * *2 days before the anniversary of Birthdate* **Anniversary options** ignore the year part of a date. This is useful for recurring annual events like birthdays — you compare only the day and month, so the notification sends each year on the right date. The Filter and the When Filter work together as an **AND** condition — both must be true for a contact to be included. *Example: Filter — City = Auckland, When Filter — 2 days before the anniversary of Birthdate. This will only send to contacts in Auckland, two days before their birthday.* You can preview your filter and When Filter against your registered devices by selecting a date and clicking **Refresh**. *** ### Recurrence Set how often the Automated Notification should run — for example, daily, weekly, or monthly. *** ### Activate Once you are satisfied with your setup, activate the Automated Notification. The dashboard will update to show reporting and a history of runs. *** ### Notification Projections Once your Automated Notification is active, the **Notification Projections** section shows how many notifications are expected to be sent on future dates. Click on a date to see the projected send count for that day. Projections are estimates based on current data. The actual number sent may differ if your database changes before that date. # Finding your form/survey/event data Forms, surveys, and events each store data differently in UbiQuity. This page explains where to find what you are looking for. When you use forms, surveys, and events in UbiQuity, the data from each is stored and accessed in different ways. Understanding where to look saves time and helps you get more out of the platform. *** ### Form Data Form submissions feed directly into your UbiQuity database. When someone submits a Subscribe or Subscribe/Update form, they are added to or updated in the database as a contact. You can find their record in the Database section and view their submission history under their contact history. To see all contacts who have completed a form, use the **Advanced Filter** in the Database. Click **Advanced Filter**, expand **Forms**, find the relevant form and expand it, then expand **Header** and click **Form Completed**. Set the condition to `is true` and click **OK**.
A screenshot showing how to filter for all contacts who have completed a specific form.

How to filter for all contacts who have completed a specific form.

This will return all contacts who have completed your form, whether they were new contacts or updates to existing ones. To narrow this down to contacts who were specifically added to your database via a particular form, click **Advanced Filter** in the Database, then expand **Database**, find and expand **System Fields**, and click **Source**. Add a filter such as `Source = YOURFORMNAME` — this will return only contacts whose database record was created from that specific form.
A screenshot showing how to use the Source field to filter for contacts added to your database via a specific form.

How to use the Source field to filter for contacts added to your database via a specific form.

Each form also has a basic report which is accessible from the Form Dashboard, showing submission activity over time. *** ### Survey Data Survey responses are stored against the survey itself, not in the UbiQuity database. You can access them directly from the Surveys module. To view responses, go to the Survey Dashboard and click **View Responses**. From there you can filter by completion status, response type (Live or Preview response), and survey answers. If your survey was deployed via a UbiQuity email, you can also filter by database fields and download responses with database contact details included. You can also view a contact's survey history from their record in the Database section if your survey was deployed via a UbiQuity email.
A screenshot of the survey responses view.

A view of survey responses

Each survey has a default report showing results for every question. You can also build custom reports and share them with others via a link, without requiring a UbiQuity login. *** ### Event Data Event registrations are stored against the event itself. You can access them from the Event Dashboard by clicking **View Registrations**. From there you can filter registrations by status, event fields, and if the event was deployed via a UbiQuity email, by database fields. You can also download registration data for use outside UbiQuity. You can also view a contact's registration history from their record in the Database section if your survey was deployed via a UbiQuity email.
A screenshot of the event responses view.

A view of event responses

Each event has a shareable report accessible from the Event Dashboard. No personally identifiable information is included in the shared report. *** ### Deploying surveys and events via email Deploying surveys and events via UbiQuity emails rather than a plain link significantly enriches the data available to you. Responses and registrations are linked to database contacts, giving you a fuller picture of each person's interactions with your organisation across forms, surveys, events, and emails. See [Deploying Your Survey](/documentation/data-capture/surveys/deploying-your-survey) and [Deploying Your Event](/documentation/data-capture/events/deploying-your-event) for more detail on how this works. # Forms Forms let you capture data directly into your UbiQuity database, giving you a simple way to grow your contact list, collect information, and trigger automated follow-up emails. ### Overview Forms are one of the core data capture tools in UbiQuity. They connect directly to your database, so every submission either adds a new contact or updates an existing one. You can embed them on your website, link to them from an email, or share them as a standalone URL. There are four form types to choose from depending on what you need to do. Subscribe Forms add new contacts to your database. Update Forms let existing contacts update their own details, usually from a link in an email. Subscribe/Update Forms handle both, making them useful for website sign-up pages where you can't be sure if someone already exists in your database. Opt Out Forms give contacts a way to unsubscribe from your emails. Once a form is submitted, UbiQuity can send triggered emails automatically. These can go to the person who filled in the form, to someone on your team, or both. You can also link forms to surveys or events as part of a wider programme. Each form also has a built-in report showing visitor activity and submission data over time. [Layouts](/documentation/data-capture/layouts) control how your forms look. A well-designed layout can fully match your brand and work across desktop and mobile. ### In this section * [Creating a Form](/documentation/data-capture/forms/creating-a-form) * [Settings](/documentation/data-capture/forms/settings) * [Fields and Validation](/documentation/data-capture/forms/fields-and-validation) * [Confirmation Page](/documentation/data-capture/forms/confirmation-message) * [Triggered Emails](/documentation/data-capture/forms/triggered-emails) * [Deploying Your Form](/documentation/data-capture/forms/deploying-your-form) * [Form Reports](/documentation/data-capture/forms/form-reports) * [Transactional Forms](/documentation/data-capture/forms/transactional-forms) # Creating a Form Creating a form in UbiQuity takes just a few steps. Before you start, make sure your database fields are set up, as these are what your form will pull from. ### Creating a Form To create a form, go to Forms in the top navigation and click **New Form**. Give your form a name and an optional description, then select your form type.
Screenshot of the Create Form dialog in UbiQuity showing a Form name field and an optional Description text area, with Next and Cancel buttons.

The Create Form dialog where you enter a name and optional description for your new form.

*** ### Form Types
Screenshot of the Select Form type dialog in UbiQuity showing three options: Update for existing contacts, Subscribe for new contacts, and Subscribe/Update for both, with Create form and Cancel buttons.

The form type selector showing the three available form types — Update, Subscribe, and Subscribe/Update.

UbiQuity has three form types to choose from at creation: **Subscribe** adds new contacts to your database. If your database has mandatory fields without default values, those fields must be included on the form. Any unique fields should also be included. **Update** is used where a contact already exists in your database. You would usually link to an Update Form from a UbiQuity email. When the contact clicks the link, the form loads pre-populated with their details, which they can then edit and submit. **Subscribe/Update** combines both. If the link is placed in a UbiQuity email it behaves as an Update Form. If it is placed on a website it behaves as a Subscribe Form. If your database has unique fields and a match is found, the existing contact is updated. Otherwise a new contact is added. You can change the form type at any time after creation. *** ### Opt Out Forms An Opt Out Form gives contacts a way to unsubscribe from your emails. Rather than a separate form type, it is configured by adding the Opted Out field to an existing form. To set up an Opt Out Form, your database must first be configured for sending email. Once configured, an Opted Out field will be available in your database. Add this field to your form, then include a link to the form in your UbiQuity email template. When a recipient clicks the link and submits the form, their Opted Out field is updated and UbiQuity automatically excludes them from future mailouts. # Settings From the Form Settings screen you can configure: **Form type** which can be changed at any time. **Auto-submit** causes the form to submit immediately when the page loads, skipping the form view and going straight to the confirmation page. This is useful for single-click competition entries or opt-outs, where a hidden field sets a value in the database without the contact needing to do anything. **Status** controls whether the form is active. Inactive forms will not accept submissions. **Close date** automatically deactivates the form after a specified date. **Source** sets the value recorded in the Source field for any new contacts added via this form. **Form Access** controls who can access the form. Options include open access for anyone with the link, restriction to API use only, restriction to allowed IP addresses for the account, or a custom IP address whitelist. **Layout** sets the visual layout applied to the form. See Layouts for more detail.
Screenshot of the Edit Form Settings screen showing fields for name, source, description, tags, form URL, layout, form type, auto-submit, status, close date, and form access.

The Edit Form Settings screen, showing form details, settings, and access options.

# Fields and Validation This is where you build your form, choose which database fields appear, set validation rules, and configure how the form behaves. ## Overview To start building your form, go to the Form Dashboard and click **Edit Fields and Validation**. This works like a wizard and you can save at any specific step or work through to the end.
Screenshot of the Add Fields and Validation screen in UbiQuity, showing a Form Introduction section and a Fields section with an Add Field dropdown.

The Add Fields and Validation screen where you build your form fields and introduction text.

Add fields to your form from the Add Field dropdown. Fields are drawn from your UbiQuity database, so the field type in the database determines what input type is available on the form. A Yes/No database field, for example, can only appear as a selection type on the form. UbiQuity automatically adds any unique or mandatory fields (without default values) to Subscribe and Subscribe/Update forms, as these are required for the form to work correctly. *** ### Field Properties For each field you can set: **Placeholder text** shows respondents what to enter, making the form easier to complete. **Default value** pre-fills the field. If the respondent does not change it, the default value is saved to the database. **Field properties** let you change the field display to radio buttons, dropdowns, or other selection types by clicking the properties icon to the right of the field. You can drag and drop fields to reorder them.
Screenshot of the field properties panel for a First Name field, showing options for field type, default value, placeholder text, size, max length, and a mandatory validation checkbox.

The field properties panel, showing options for field type, default value, placeholder, size, and validation.

*** ### Captcha If you want extra protection against automated form submissions, you can add a Captcha to your form. This adds a simple maths problem that bots cannot solve. UbiQuity already includes a hidden honeypot by default, so a Captcha is optional but provides an additional layer of protection. *** ### Form Validation Basic validation can be set per field, including making a field mandatory and choosing the error message shown if it is left blank. For more complex rules, use the Form Validation section at the bottom of the Edit Fields and Validation screen. This lets you build conditional validation rules. For example: if a contact selects email as their preferred contact method, then the email address field becomes mandatory.
Screenshot of the Form Validation panel showing a conditional rule: if the email address field from the form equals nothing, then don't submit the form and display the message "Please enter your Email Address".

An example of a conditional validation rule — if the email address field is empty, the form will not submit and a message is displayed.

For Update and Subscribe/Update forms, Form Validation can also reference database fields, using the values stored in the database before the form is submitted. # Confirmation Message To edit the confirmation page, go to the Form Dashboard and click Edit Confirmation Message. You can either display a custom confirmation message or redirect the contact to another URL after submission. If you choose to display a message, you can personalise it using merge fields from the form. For Update Forms, you can also merge in database fields, though note that merged database field values will reflect what was stored in the database before the form was submitted, not the new values just entered. Use the Insert UbiQuity Link function to add links to other forms, surveys, or events on the confirmation page. Because the contact is now in the database, you can link to an Update Form to collect additional information, or to a survey whose responses will be linked to that contact.
A screenshot of the Confirmation Message page showing the various options available.

The Confirmation Message page showing the various options available.

# Triggered Emails Triggered emails are sent automatically when a form is submitted. You can send them to the person who filled in the form, to someone on your team, or both. ### Creating a Triggered Email To set up a triggered email, go to the Form Dashboard and click **Manage Triggered Emails**, then click **Create Triggered Email.**
A screenshot of the Triggered Emails view for a form, showing the Create Triggered Email button and an empty list.

The Triggered Emails screen for a form, showing the Create Triggered Email button and an empty list.

When creating a triggered email, you have two optional starting points: * **I want to start by copying an existing Triggered Email** — copies the content and settings from an existing triggered email, saving you from starting from scratch if you have a similar one already set up. * **I want to start by loading in content from an Email Template** — loads in the content from an existing email template as the starting point for your triggered email. Give your triggered email a **Name** and an optional **Description**, then click **OK** to continue.
A screenshot of the Create Triggered Email dialog showing the two optional starting points and fields for name and description.

The Create Triggered Email dialog showing the two optional starting points and fields for name and description.

*** ### Content & Preview After creating your triggered email, you will be taken to the Triggered Email Dashboard. Go to **Triggered Email Content** to set up your header fields — including To Email, To Name, From Email, From Name, Reply Email, Reply Name, Subject, and Pre-Header Text. Merge fields can be used in any of these fields. Merge fields let you pull in values from the form submission. For Update Forms, you can also merge in database fields. You will also need to build the body content of your email using the standard email content editor, the same one used in Mailouts and Automated Mailouts. Attachments can be added to triggered emails, though it is generally better to host files in the UbiQuity Media Manager and link to them rather than attaching directly. To preview your triggered email, click **Preview** to send a test to your inbox. For Update Forms, select a database contact from the Preview screen to see how database merge fields will appear. Note that to fully test form field merging, you will need to actually submit the form and receive the triggered email. *** ### Conditions Use **Edit Conditions** to control when a triggered email is sent. If no conditions are set, the email sends every time the form is submitted. For Update Forms, conditions can reference both form fields and database fields, including previous events for the contact.
A screenshot of the Conditions view where you can add conditions to control when the triggered email is sent.

The Conditions screen where you can add conditions to control when the triggered email is sent.

*** ### Activating When your triggered email is ready, activate it from the Triggered Email Dashboard by clicking **Activate Triggered Email**, and typing ACCEPT to confirm activation.
A screenshot of the Triggered Email Dashboard showing the Activate button in the top left corner.

The Triggered Email Dashboard showing the Activate button in the top left corner.

# Deploying Your Form Every form has a unique URL. How you share that URL depends on the form type and where you want people to access it. ### Finding Your Form URL Each form has a live URL visible from the Form Dashboard.
A screenshot of the Form Dashboard showing the live form URL.

The Form Dashboard showing the live form URL.

*** ### Adding Your Form to a Website If you are embedding your form on a website, use the Get Deployment Code function from the Form Dashboard. This gives you code to add the form as a standard link, a popup window, or an inline frame.
A screenshot of the Deploy Code screen showing the three embedding options — standard link, popup window, and inline frame — with the generated code displayed below.

The Deploy Code screen showing the three embedding options — standard link, popup window, and inline frame — with the generated code displayed below.

Give this code to your web developer, or add it to your site yourself if you are comfortable doing so. *** ### Adding Your Form to a UbiQuity Email If you are linking to a Subscribe Form from a UbiQuity email, use the Insert UbiQuity Link function when editing your email content. You can also copy and paste the URL directly. Update and Opt Out forms should always be deployed via a UbiQuity email rather than placed on a public website. When a contact clicks the link from a UbiQuity email, the form loads pre-populated with their details. *** ### Adding Your Form to a Regular Email If you are sending the link via a standard email client such as Outlook or Gmail, copy the URL from the Form Dashboard and paste it into your email as a plain link. Standard email clients do not support popup windows or inline frames. *** ### API If your website or application needs to connect to a form programmatically, this can be done via the UbiQuity API. You will likely need a developer to set this up. Forms connected via the API can still trigger emails. See [API documentation](/documentation/data-and-integrations/api) for more detail. # Form reports Each form in UbiQuity has a built-in report that shows how your form is performing over time. Access it by going to the Form Dashboard and clicking **View Form Report** under the **Report** section.
A screenshot of a Form Report showing visitor activity, submission data, and traffic sources.

The Form Report showing visitor activity, submission data, and traffic sources.

*** ### Report actions At the top of the report you have several options: * **View Form** — Opens the live form * **View Printable** — Generates a print-friendly version of the report * **Send Report by Email** — Sends the report to an email address * **Set Start Date** — Sets the start of the reporting period * **Refresh** — Refreshes the report data Use the **Show Results From** date range selector to filter the report to a specific time period. *** ### Details The Details section shows the form's metadata — including the form name, date of creation, form type, and a public report link that can be shared with others without requiring them to log in to UbiQuity. *** ### Overview The Overview section gives a snapshot of form performance, including: * **Total visitors** — Everyone who visited the form URL * **Unique visitors** — Visitors counted once regardless of how many times they visited * **Times form completed** — How many times the form was successfully submitted * **Referred from UbiQuity** — Visitors who arrived via a UbiQuity email, survey, form, or event * **Referred from social media** — Visitors who arrived via a social media link * **Completed via API** — Submissions made programmatically via the API * **Visitors from other sources** — Visitors from all other sources * **Links clicked on the Form** — How many times links within the form were clicked * **Average time spent on Form** — The average time visitors spent on the form before submitting or leaving *** ### Visitor Activity The Visitor Activity chart tracks total visitors, unique visitors, and form completions over time. Use this to spot trends in form traffic and submission rates. *** ### Visitor Browser Profile The Visitor Browser Profile shows a breakdown of which browsers visitors used to access the form. This can be useful when testing form layouts across different browsers. # Transactional Forms If you are using transactional data in UbiQuity, you can add transactional fields to your forms, allowing contacts to submit transaction records at the same time as their contact details. ## Overview Transactional data is linked to your main UbiQuity database and is useful for storing related records against a contact, such as purchases or event bookings. If your account uses transactional data, you can add transactional fields to Subscribe, Update, and Subscribe/Update forms. Each form submission can include up to 10 new transactions. *** ### Adding Transactional Fields The Transactional Fields panel is available in the Edit Fields and Validation screen, below the Form Introduction section.
A screenshot of the Add Fields and Validation page showing the Add Transactional Fields option

The Add Fields and Validation page showing the Add Transactional Fields option

Click **Add Transactional Fields** to open the setup dialog. From here you can: * Select which transactional database to use * Set the minimum and maximum number of transactions allowed per submission (between 0 and 10) * Customise the Add and Delete button labels that contacts will see on the form
A screenshot of the Add Transactional Fields dialog, where you select a transactional database and configure submission limits and button labels

The Add Transactional Fields dialog, where you select a transactional database and configure submission limits and button labels.

Once confirmed, mandatory transactional fields are added to the form automatically. You can then add additional transactional fields from the dropdown, the same way you would add standard database fields. You must have at least one standard database field on the form so that transactions can be linked to a database contact. *** ### Rules for Transactional Fields All mandatory transactional fields without default values must be included before the form can be saved. Attempting to remove them will produce a validation error. If your transactional database has unique fields and a submitted transaction fails the unique check, an error message will be displayed at the top of the form. *** ### Editing and Removing Transactional Fields To change the number of transactions or button labels, click Edit Options at the bottom right of the transactional fields section. To switch to a different transactional database, click Remove Transactional Fields and then Add Transactional Fields again. You can remove individual transactional fields using the delete button next to each field, or remove all of them at once using Remove Transactional Fields. *** ### Filtering and Reporting Once transactional fields are added to a form, you can use them as part of a matching transactions filter across UbiQuity. To see how many transactions have been submitted via a specific form, apply a filter using the form name as the source.
A screenshot of a filter condition showing how to find contacts with matching transactions from a specific transactional form, filtered by a field value.

A filter condition showing how to find contacts with matching transactions from a specific transactional form, filtered by a field value.

A screenshot of the Manage Transactions screen with a filter applied to show only transactions submitted via a specific form.

The Manage Transactions screen with a filter applied to show only transactions submitted via a specific form.

*** ### API Support Transactional fields are supported through the UbiQuity API. The form submit and validate API calls include transactional data. See [API documentation](/documentation/data-and-integrations/api) for more detail. # Surveys Surveys let you capture feedback, run research programmes, and gather information from your contacts. They can be used as a standalone tool or integrated with UbiQuity emails, forms, and events. Surveys are a flexible data capture tool in UbiQuity. You can run them as a simple standalone survey using a link on your website or in a regular email, or integrate them with UbiQuity Mail to unlock more powerful features like personalised links, database merge fields, reminder emails to non-respondents, and filtering your database based on responses. Surveys support a wide range of question types, from simple text fields to Net Promoter Score, rating groups, and ranking questions. You can control the flow of your survey using logic rules that show or hide questions, skip pages, or end the survey early based on how someone responds. Once responses start coming in, you can view and filter them in real time, download them for further analysis, and build shareable reports. ### In this section * [Creating a Survey](/documentation/data-capture/surveys/creating-a-survey) * [Questions and Pages](/documentation/data-capture/surveys/questions-and-pages) * [Survey Settings](/documentation/data-capture/surveys/details-and-settings) * [Survey Logic](/documentation/data-capture/surveys/survey-logic) * [Triggered Emails](/documentation/data-capture/surveys/triggered-emails) * [Deploying Your Survey](/documentation/data-capture/surveys/deploying-your-survey) * [Responses and Reporting](/documentation/data-capture/surveys/responses-and-reporting) # Creating a Survey Creating a survey in UbiQuity takes just a few steps. You can start from scratch or copy an existing survey to save time. To create a survey, go to Surveys in the top navigation and click **New survey**. Enter a name and an optional description, then click Create Survey. You will land on the Survey Dashboard.
A screenshot of the Create survey dialog where you enter a name and optional description for your new survey.

The Create survey dialog where you enter a name and optional description for your new survey.

If you want to base your new survey on an existing one, use the **Duplicate** option from the survey list. Click the three-dot menu next to the survey you want to copy and select **Duplicate**. The new survey will include all questions, pages, logic, and settings from the original, which you can then edit as needed.
A screenshot of the survey list showing the three-dot menu with the Duplicate option for copying an existing survey.

The survey list showing the three-dot menu with the Duplicate option for copying an existing survey.

Unless you are copying an existing survey, your new survey will be created with no questions or pages set up. Your first steps will be to configure your survey settings and then build out your questions and pages. From the Survey Dashboard you can access all the tools you need to build, test, and deploy your survey.
A screenshot of the Survey Dashboard showing all the tools available to build, test, and deploy your survey.

The Survey Dashboard showing all the tools available to build, test, and deploy your survey.

# Details and Settings Survey details and settings control how your survey behaves, including when it closes, how many times someone can respond, and how it looks to respondents. You can update the name, description, and tags for your survey at any time by going to **Edit Survey Details and Settings**. The survey URL is also visible here and on the Survey Dashboard. ### Close Settings **Date** sets a date after which the survey will automatically close. Anyone trying to access it after this date will see the Inactive page. **Responses** closes the survey once a set number of responses has been reached. Anyone currently completing the survey when the limit is reached will still be able to finish. *** ### Response Limits **Allow multiple responses** is the default. Respondents can complete the survey as many times as they like. **Only allow one response** uses cookies for anonymous respondents and personalised links for contacts arriving via UbiQuity Mail to prevent duplicate responses. Note that on a shared computer, this setting may prevent new respondents from completing the survey. **Allow further responses after a period of time** works like the one response limit but reopens the survey to the same respondent after a set period. This is useful for pulse surveys or recurring NPS programmes. *** ### Save and Resume Allows respondents to leave the survey and come back to it later without losing their progress. For anonymous respondents this uses a cookie. For contacts arriving via a UbiQuity email it uses their personalised link. If you expect respondents to be on public computers and entering sensitive information, save and resume is not recommended. *** ### Survey Access **Accessible to anyone with the link** is the default open access setting. **Restrict access to allowed IP addresses** limits access to the IP addresses configured for your UbiQuity account. Contact UbiQuity to manage this list. **Restrict access to a custom IP address whitelist** lets you specify your own list of permitted IP addresses. **Restrict to database contacts only** means anonymous links will show the Inactive page. Only personalised links from UbiQuity mailouts will work. *** ### Numbering and Layout Options You can configure how questions and pages are numbered, including dynamic numbering that keeps numbers sequential even when logic skips pages, and consecutive numbering across pages. Layout options include showing or hiding a progress bar, enabling or disabling the back button, and showing or hiding asterisks on mandatory questions. # Questions and Pages This is where you build the content of your survey, adding pages, questions, and logic to create the experience you want for respondents. ### Overview To start building your survey, go to the Survey Dashboard and click **Edit Survey Questions and Pages**. Any changes you make are not saved or published until you click Save. Remember to save regularly so you do not lose your work. *** ### Pages When you create a new survey it comes with the following default pages: **Introduction Page** is shown before the first question page. Use it to explain what the survey is about, how long it will take, when it closes, and who to contact with questions. If you leave the Introduction Page empty it will not be shown to respondents. **Question pages** are where you add your questions. You can create as many question pages as you need, but your survey will by default come with one question page. **Thank You page** is shown once a respondent completes the survey. **Inactive page** is shown if someone tries to access the survey after it has closed.
A screenshot of the drop down of default pages that come with a survey.

The drop down of default pages that come with a survey.

Use the page navigator dropdown and arrows to switch between pages. Click Options on any page to name it, randomise the order questions appear, set all questions on the page as mandatory or optional, configure a custom mandatory message, and set the layout mode for questions on that page. *** ### Adding Questions Add questions to a page using the **Add Question** dropdown. Questions are added with default settings and can then be edited using the properties icon to the right of each question. You can drag questions up and down to reorder them.
A screenshot of the different types of questions that can be added via the Add Question drop down

The different types of questions that can be added via the Add Question drop down

The available question types are: **Simple questions** include single line text, paragraph text, email address, mobile number, date, date and time, decimal number, and whole number. Each has appropriate validation built in. **Selection questions** include radio buttons for single select, checkboxes for multi-select, dropdown, rating scale, slider, and Net Promoter Score. NPS always uses a 0 to 10 scale and automatically categorises responses into detractors, neutrals, and promoters in reporting. **Advanced questions** include rating group, ranking group, block of text fields, and spreadsheet. These are more complex question types suited to structured feedback. Selection questions also support Other and Don't Know options. Other shows respondents a free text box. Don't Know is automatically exclusive, meaning selecting it clears any other selections. You can add multiple exclusive options and rename them as needed. *** ### Editing Questions Click the Edit (pencil) icon to the right of any question to edit it. Options vary depending on the question type. Give each question a name to make it easier to reference when building logic or inserting merge fields. For selection questions, you can set a Display Text (what respondents see on the form) and a Response Value (what is stored in the database and downloaded in exports). These can be different if needed.
An screenshot showing some of the question properties that can be configured.

An example of the question properties that can be configured.

*** ### Question Piping For questions that allow multiple selections, you can pipe the selected answers into a question on a later page. Only the options the respondent selected will appear in the piped question. If no options were selected the piped question will not be displayed. *** ### Merging Fields You can merge responses from previously answered questions into later questions or page introductions using the Insert Merge Field icon. If the question was not answered, nothing will appear to the respondent. If your survey is deployed via a UbiQuity email, you can also merge in database fields and responses from previously completed surveys.
A screenshot showing how to insert merge fields.

Use the highlighted button to insert merge fields.

*** ### Inserting Links Use the Insert UbiQuity Link function to add links to other surveys, forms, or events within your survey content. Useful additions include a link back to the respondent's survey response on the Thank You page, a Subscribe Form for anonymous respondents to register into your database, or an Update Form for contacts who arrived via a UbiQuity email.
A screenshot showing how to insert UbiQuity links.

Use the highlighted button to insert UbiQuity links.

*** ### Deleting Questions If you delete a question, all responses to that question will also be deleted. If you want to keep the data but hide the question from future respondents, edit the question and set it to hidden instead. UbiQuity recommends finalising your survey before it goes live to avoid making structural changes while people are responding. # Survey Logic Survey logic lets you personalise the survey experience for each respondent, showing or hiding questions, skipping pages, and branching to different paths based on how someone answers. ### Show and Hide Questions The simplest form of logic is visibility. You can make any question show or hide in real time on the page based on answers to other questions on the same page or previous pages. To set this up, click the **Edit (Pencil)** icon to the right of a question and configure the **Visibility** settings. You can also use the **Mandatory** settings to make a question conditionally mandatory, so it is only required if it is shown. For example, make an email address field mandatory only if the respondent has indicated they want to be contacted by email.
A screenshot showing how logic and validation being used to show a question only if a condition is met.

An example of a logic and validation being used to show a question only if a condition is met.

*** ### Post Logic Post logic runs after a respondent clicks Next at the end of a page. It can skip pages, jump to a specific page, show a message, or end the survey based on the respondent's answers. Post logic is useful when you have a group of questions you want to show or skip together based on a previous answer. Rather than setting visibility on each individual question, put them all on a separate page and use post logic to show or skip that page.
A screenshot showing post logic being used to determine what action should be taken at the end of a page.

An example of a post logic being used to determine what action should be taken at the end of a page.

Logic conditions are processed from top to bottom. If a condition triggers a page jump or ends the survey, no further conditions on that page will run. Note that post logic does not process until the respondent clicks Next, so it cannot be used to show or hide questions on the current page in real time. Use visibility settings for that instead. *** ### Pre Logic Pre logic runs before a page loads. It can be used to skip a page before the respondent even sees it. You can use either post logic or pre logic to achieve similar outcomes, there is no strict rule about which to use. Choose whichever feels most natural for the flow of your survey.
A screenshot showing how pre logic being used determine what action should be taken prior to a page load.

An example of a pre logic being used determine what action should be taken prior to a page load.

*** ### Advanced Logic Logic conditions can be built using answers from anywhere in the survey. If your survey is deployed via a UbiQuity email, you can also use database fields and email interaction data such as whether the contact clicked a link in a previous mailout. When building conditions, the condition tree gives you access to survey questions, database fields, events, and mailout data all in one place.
A screenshot of the advanced logic conditions that allow you to filter from other modules.

The advanced logic conditions that allow you to filter from other modules.

# Triggered Emails Triggered emails are sent automatically when a respondent completes your survey. You can send them to the respondent, to someone on your team, or to any email address based on conditions you set. ### Setting Up the Email To set up a triggered email, go to the Survey Dashboard and click **Manage Triggered Emails**, then click **Create Triggered Email.**
A screenshot of the Triggered Emails screen for a survey, showing the Create Triggered Email button.

The Triggered Emails screen for a survey, showing the Create Triggered Email button.

When creating a triggered email, you have two optional starting points: * **I want to start by copying an existing Triggered Email** — copies the content and settings from an existing triggered email, saving you from starting from scratch if you have a similar one already set up. * **I want to start by loading in content from an Email Template** — loads in the content from an existing email template as the starting point for your triggered email. Give your triggered email a **Name** and an optional **Description**, then click **OK** to continue.
A screenshot of the Create Triggered Email dialog showing the two optional starting points and fields for name and description.

The Create Triggered Email dialog showing the two optional starting points and fields for name and description.

*** ### Content & Preview After creating your triggered email, you will be taken to the Triggered Email Dashboard. Go to **Triggered Email Content** to set up your header fields — including To Email, To Name, From Email, From Name, Reply Email, Reply Name, Subject, and Pre-Header Text. Merge fields can be used in any of these fields. The To Email field can be a specific address such as an internal team inbox, or a dynamic address pulled from a survey question such as the email address the respondent entered on the survey. You will also need to build the body content of your email using the standard email content editor, the same one used in Mailouts and Automated Mailouts. You can merge fields from the survey into the email body. If the survey was deployed via a UbiQuity email, you can also merge database fields. Use the Insert UbiQuity Link function to add links to other surveys, forms, or events, or to include a link that lets the recipient view the respondent's survey response. Preview your triggered email and send a test to your inbox. If you are deploying via a UbiQuity email, use the database filter in the Preview screen to select a contact and see how database merge fields will appear. Note that active triggered emails will not send during survey preview. They will only be triggered by a live response. *** ### Conditions Set conditions to control when the triggered email is sent. If no conditions are set, the email sends every time the survey is completed. Conditions can be based on survey responses. For example, send a follow-up email to a team member only if a respondent gives an NPS score of 6 or below.
A screenshot of the Conditions screen where you can add conditions to control when the triggered email is sent.

The Conditions screen where you can add conditions to control when the triggered email is sent.

*** ### Activating When your triggered email is ready, activate it from the Triggered Email Dashboard by clicking **Activate Triggered Email**, and typing ACCEPT to confirm activation.
A screenshot of the Triggered Email Dashboard showing the Activate button in the top left corner.

The Triggered Email Dashboard showing the Activate button in the top left corner.

# Deploying Your Survey Once your survey is active, there are several ways to get it in front of respondents. The method you choose affects what data you can collect and how much you can personalise the experience. Before deploying, make sure your survey is active. Go to the Survey Dashboard and click **Activate Survey**, then type **ACCEPT** to confirm. The survey status will change to Active and the Live Survey URL will become accessible.
A screenshot of the Survey Dashboard, showing the Activate Survey button.

The Survey Dashboard, showing the Activate Survey button.

Note that the Live Survey URL is generated when the survey is created and does not change, however it will not work until the survey is activated. *** ### Survey Link Every survey has a Live Survey URL accessible from the Survey Dashboard. You can share this link in a regular email, add it to your website, or embed the survey using the **Get Deployment Code** options.
A screenshot of the Deploy Code screen showing the three embedding options — standard link, popup window, and inline frame — with the generated code displayed below.

The Deploy Code screen showing the three embedding options — standard link, popup window, and inline frame — with the generated code displayed below.

Responses collected via a plain link are recorded as anonymous. All you know about each respondent is what they answered in the survey. *** ### Sending via a UbiQuity email Sending your survey via a UbiQuity email unlocks significantly more capability. When a respondent clicks the personalised link in a UbiQuity email, their response is linked to their database contact. This gives you the ability to: * Send reminder emails only to contacts who have not yet responded * Filter your database based on survey responses * Merge database fields into the survey and triggered emails * Use database fields in survey logic To deploy via a UbiQuity email, ensure your survey is active, then create a mailout and use the Insert UbiQuity Link button to insert the survey link into your email content.
A screenshot of showing the insert UbiQuity links button.

Use the highlighted button to insert UbiQuity links.

*** ### Previewing Before You Deploy Before activating and sending, use the **Preview Your Survey** option from the Survey Dashboard to test the survey. You can preview anonymously using the Preview Survey URL, or preview as a specific database contact to test merge fields and logic.
A screenshot showing the ability to preview your survey as an anonymous recipient, or as a specific database contact.

Preview your survey as an anonymous recipient, or as a specific database contact.

Preview responses are kept separate from live responses and will not appear in your reports. Triggered emails will not fire during preview. **Testing checklist before you go live:** * Test the full survey from start to finish * Test all show/hide logic and page branching paths * Check the Inactive page is set up correctly * Set a close date if applicable # Responses and Reporting Once your survey is live, you can view, filter, and download responses in real time. You can also build reports to share results with others. ### Viewing Responses You can access survey responses from three places: * From the main Surveys dashboard, click the **number of responses** shown against the survey * From the Survey Dashboard, click **View Responses** * From the Survey Summary on the Survey Dashboard, click the **Total Responses** figure Responses can be filtered by status and type. Status options are Complete (the respondent finished the survey and saw the Thank You page), Incomplete (the respondent started but did not finish), and Both. Type options are Live (responses from the live survey URL) and Preview (responses recorded during testing). Click **Show Responses** to display the response list.
*** ### Editing Responses Super Users and Survey Administrators can edit individual responses. To edit a response, click the three dots beside it, then **View** and then **Edit**. If triggered emails are set up, UbiQuity will ask whether you want them to be resent when saving the edited response. *** ### Filtering Responses From the Responses page, click **New filter** to filter responses by survey question answers. If the survey was deployed via a UbiQuity email, you can also filter by database fields and by how contacts interacted with the email, such as whether they clicked a specific link.
A screenshot of the filtering options available for Survey responses.

The filtering options available for Survey responses.

*** ### Downloading Responses Click the three dots to the left of **Show Responses** to Download Responses from the Responses page and choose your file format. CSV works well for most purposes. If your survey was deployed via UbiQuity Mail, you can choose to include database fields alongside the survey responses in the download, giving you a complete picture of each respondent against each row.
A screenshot showing the download responses option.

The download responses option.

*** ### Response Source UbiQuity records the source of each response. Anonymous responses come from a plain link on a website or in a standard email. Mailout responses are linked to the UbiQuity mailout they came from. Keyed in responses are entered manually by clicking **Respond to Your Survey** from the Survey Dashboard. *** ### Responding on Behalf of a Contact You can enter a live response on behalf of a database contact by clicking **Respond to Your Survey** from the Survey Dashboard and selecting a contact. This has the same effect as if the contact had clicked a personalised link from a UbiQuity email, and the response will appear in that contact's history. *** ### Passing Data via URL If you are deploying your survey outside of a UbiQuity email and want to pass additional information into responses, you can append up to three data parameters to the survey URL using data1, data2, and data3. These values appear against each response, in reports, and in download files, and can also be used in filters and survey logic. *** ### Reports Each survey has a default report that shows every question. Access it from the Survey Dashboard by clicking **View Default Report**.
A screenshot showing an example of a default survey report.

An example of a default survey report.

To create a custom report, click **Manage Reports** from the Survey Dashboard. You can create a report from scratch or copy the default report as a starting point. Add pages and questions from the survey using the Add Page Item dropdown. You can also add sections to include formatted text, images, or video alongside your charts. For each question added to a report, click the edit icon to change the chart type, display format, and whether statistics are shown. Questions can be added multiple times with different settings.
A screenshot showing an example of the custom report builder.

An example of the custom report builder.

To share a report with someone who does not have a UbiQuity login, tick **Report is public** in **Report Details**. This generates a shareable link. Note that the report is not published anywhere publicly, but the link could be shared further, so consider whether the content is appropriate to share openly before distributing it. If the survey was deployed via a UbiQuity email, you can also filter reports by database contact fields. # Events Track and capture customer interactions and behavioural data within the platform. The Events module in UbiQuity handles the full registration process for your events. You can create a registration form, set capacity limits, send automated confirmation and reminder emails, and track who has registered. Events work well as a standalone registration tool, but become more powerful when connected to UbiQuity emails. Sending your event link via a UbiQuity mailout lets you personalise the experience for each contact, send reminders only to those who have not yet registered, and link registrations back to your database contacts. You can allow a single registration per person or enable multiple registrations per form, either as named places with individual details for each registrant, or as anonymous tickets where one person orders multiple spots. ### In this section * [Creating an Event](/documentation/data-capture/events/creating-an-event) * [Details and Settings](/documentation/data-capture/events/details-and-settings) * [Fields and Validation](/documentation/data-capture/events/fields-and-validation) * [Confirmation Message](/documentation/data-capture/events/confirmation-message) * [Triggered Emails](/documentation/data-capture/events/triggered-emails) * [Deploying Your Event](/documentation/data-capture/events/deploying-your-event) * [Registrations and Reporting](/documentation/data-capture/events/registrations-and-reporting) # Creating an Event Creating an event in UbiQuity takes just a few steps. You can start from scratch or copy an existing event. To create an event, go to **Events** in the top navigation and click **New event**. Unless you copy an existing event, your new event will be created with default settings and no fields on the registration form. You will need to select an Event date, and a date that registrations close on.
A screenshot of the New event button showing in the Events module.

The New event button showing in the Events module.

If you want to base your new event on an existing one, use the **Duplicate** option from the event list. Click the three-dot menu next to the event you want to copy and select **Duplicate**. You can then edit the duplicated event as needed.
A screenshot of the event list showing the three-dot menu with the Duplicate option for copying an existing event.

The event list showing the three-dot menu with the Duplicate option for copying an existing event.

Each event has a unique URL that is used for registration. You can find this on the Event Dashboard at any time. The event date and close registrations date can be updated at any time from the **Edit Details and Settings** option. # Details and Settings Event settings control the key details of your event including dates, capacity, registration behaviour, access controls, and pricing. To access event settings, go to the Event Dashboard and click **Edit Details and Settings**. ### Event Date and Close Date Set the date of the event so you can schedule triggered emails relative to it. For example, send a reminder the day before and a follow-up survey link the day after. Set the date registrations close. Anyone visiting the event link after this date will see the Registrations Closed page. You can edit the content of this page under Confirmation Pages. *** ### Capacity Set a total number of places for your event. Once the limit is reached, new visitors will see the Maximum Capacity Reached page. Cancelling a registration frees up a place. *** ### Additional Registrations You can allow multiple registrations per form submission in two ways. **Named places** require individual details for each registrant. Add Person and Remove Person buttons appear on the form, and you can control which fields appear for additional registrants when editing your form fields. **Anonymous tickets** allow one person to order multiple tickets without entering details for each. A Number of Tickets field is added to the form automatically.
A screenshot of the additional registration settings that are available in event details and settings.

The additional registration settings that are available in event details and settings.

*** ### Single Registration Per Respondent When enabled, each person can only register once. For anonymous registrations via a website link, cookies are used to track this. For contacts arriving via a UbiQuity mailout, personalised links are used instead. Anyone who has already registered and tries to register again will see the Already Registered page, which can be edited under Confirmation Pages. *** ### Confirmation Status Each registration has a status of Unconfirmed, Confirmed, or Cancelled. By default new registrations are marked as Unconfirmed. You can change this default to automatically confirm all new registrations. A confirmed registration counts against the total capacity. An unconfirmed registration does not. For paid events, registrations also have a Paid or Unpaid status. Payments are made via invoices, and will be marked as Unpaid until you update them manually. *** ### Event Access **Accessible to anyone with the link** is the default open access setting. **Restrict access to allowed IP addresses** limits access to the IP addresses configured for your UbiQuity account. Contact UbiQuity to manage this list. **Restrict access to a custom IP address whitelist** lets you specify your own list of permitted IP addresses. **Restrict to database contacts only** means anonymous links will show the Inactive page. Only personalised links from UbiQuity mailouts will work. *** ### Registrant Name Template As registrations come in, you can view them in a list. To control what information appears in that list, add form fields to the **Registrant Name Template** in Edit Event Settings using the merge field selector. *** ### Pricing You can set a price for your event or leave it free. If any pricing or paid items are present, a payment page will appear as part of the registration process. This page can be customised under Layouts. Payments can be taken via invoice, and a text box will appear for the registrant to enter their billing details. You will need to download these and send invoices manually, then update the registration status to Paid once payment is received.
A screenshot of the pricing options that are available in event details and settings.

The pricing options that are available in event details and settings.

# Fields and Validation This is where you build your event registration form, add fields, set validation rules, and configure how the form behaves. To start building your registration form, go to the Event Dashboard and click **Edit Fields and Validation**. Any changes you make are not saved until you click Save. We recommend finalising your event form before it goes live. Editing a live event may produce inconsistent results for anyone currently completing the form. Deleting a field will permanently remove the data stored against that field for existing registrations. Once your event is ready, activate it from the Event Dashboard and your event is ready to go. *** ### Registration Form Fields Add fields to your registration form and edit them by clicking the properties icon. If your event uses named places, you can control which fields appear for additional registrants using the option to show the field in the additional registrants section.
A screenshot showing the Edit Fields and Validation screen where you build your form fields and introduction text.

The Edit Fields and Validation screen where you build your registration form fields and introduction text.

If you have enabled tickets under Event Settings, a Number of Tickets field is added to the form automatically. Paid item fields are added up to a total alongside any event-level pricing. If any costs are present on the event, a payments page will be displayed to the registrant. When event forms are submitted, data is stored against the event registration, not directly in the UbiQuity database. However, the registration is linked to the database contact. You can import event registrants into your database if needed. *** ### Merging Fields If you send your event via a UbiQuity email, you can merge database fields into the registration form introduction, confirmation page, and triggered emails. You can also merge fields from other UbiQuity interactions such as survey responses, provided they are linked to the relevant database contacts. If you are not using a UbiQuity email and are placing the event link on a website, you can still merge fields, but only event fields, and only onto the Thank You page and triggered emails.
A screenshot showing the insert merge fields button in the standard content editor.

Use the highlighted button to insert merge fields.

*** ### Event Validation You can make individual fields mandatory and set custom validation messages. For more complex rules, use the Event Validation section at the bottom of the Edit Fields and Validation screen to build conditional validation rules. For example: if a registrant selects email as their preferred contact method, then the email address field becomes mandatory. *** ### Inserting Links Use the Insert UbiQuity Link function to add links to other events, surveys, or forms within your event content. You can add these links to the introduction, Thank You page, and triggered emails. For example, add a survey to a triggered email sent after the event, or add a Subscribe Form to the Thank You page for anonymous registrants to join your database.
A screenshot of the insert UbiQuity links button in the standard content editor.

Use the highlighted button to insert UbiQuity links.

If the event was sent via a UbiQuity email, you can also include Update Forms so contacts can update their database details directly from the event or a triggered email. # Confirmation Message Different confirmation pages appear to registrants depending on the outcome of their registration attempt. You can customise the content of each page.
A screenshot showing the Confirmation and Inactive Messages page showing the various options available.

The Confirmation and Inactive Messages page showing the various options available.

You can either display a custom confirmation message or redirect the registrant to another URL after submission. The following pages can be configured: **Confirmation page** appears when a registration is successful. You can customise the message and merge in event fields to personalise it. A summary of the registrant's submitted fields is also displayed and appears below your message. The formatting of this summary is controlled by the Layout. **Event Inactive page** appears if the event has not been activated yet. Activate your event from the Event Dashboard. **Registrations closed page** appears when someone tries to register after the close date has passed. The close date is set under Event Details and Settings. **Event over page** appears when someone attempts to view an event after the date of the event. The event date is set under Event Details and Settings. **Maximum capacity reached page** appears when the event is full. Total capacity is set under Event Settings. **Already registered page** appears if Single Registration Per Respondent is enabled and the person has already registered. **Payment page** appears if the event has any pricing or paid items. This page itemises charges and provides credit card and billing details options. It is more complex than the other confirmation pages and is customised via the Layout rather than here. You can use the Insert UbiQuity Link function to add links to other events, surveys, or forms on any of these pages. # Triggered Emails Triggered emails are sent automatically when someone registers for your event, or at scheduled times relative to the event date. You can send them to the registrant, to your team, or both. To set up triggered emails, go to the Event Dashboard and click **Manage Triggered Emails**. ### Creating a Triggered Email To set up a triggered email, go to the Event Dashboard and click **Manage Triggered Emails**, then click **Create Triggered Email.**
A screenshot of the triggered Emails screen for a event, showing the Create Triggered Email button and an empty list.

The Triggered Emails screen for a event, showing the Create Triggered Email button and an empty list.

When creating a triggered email, you have two optional starting points: * **I want to start by copying an existing Triggered Email** — copies the content and settings from an existing triggered email, saving you from starting from scratch if you have a similar one already set up. * **I want to start by loading in content from an Email Template** — loads in the content from an existing email template as the starting point for your triggered email. Give your triggered email a **Name** and an optional **Description**. Then you need to decide when you want to send the triggered email. Triggered emails can be sent immediately when a registration form is submitted, or scheduled relative to the event date. For example, send a confirmation email on submission, a reminder the day before, and a follow-up survey link the day after. The Create Triggered Email dialog showing the two optional starting points and fields for name and description.
A screenshot showing the Create Triggered Email dialog with the two optional starting points, fields for name and description, and trigger conditions.

The Create Triggered Email dialog showing the two optional starting points, fields for name and description, and trigger conditions.

*** ### Primary Registrant If your event uses named places and allows multiple registrants per form, the first registrant's details are treated as the primary registrant. Triggered emails are sent to the primary registrant only. *** ### Content & Preview After creating your triggered email, you will be taken to the Triggered Email Dashboard. Go to **Triggered Email Content** to set up your header fields — including To Email, To Name, From Email, From Name, Reply Email, Reply Name, Subject, and Pre-Header Text. Merge fields can be used in any of these fields. Merge fields let you pull in values from the event registration. If your event was deployed via a UbiQuity email, you can also merge database fields. You will also need to build the body content of your email using the standard email content editor, the same one used in Mailouts and Automated Mailouts. Attachments can be added to triggered emails, though it is generally better to host files in the UbiQuity Media Manager and link to them rather than attaching directly. To preview event triggered emails, you need a preview registration. Click **Preview Your Event** from the Event Dashboard and complete the form to create one. This lets you test any event merge fields in the triggered email. *** ### Conditions Set conditions to control when a triggered email is sent. If no conditions are set, the email sends every time a form is submitted. You can also use advanced conditions to further refine. The triggered email will only be sent when all conditions are satisfied.
A screenshot of the Conditions screen where you can add conditions to control when the triggered email is sent.

The Conditions screen where you can add conditions to control when the triggered email is sent.

*** ### Activating When your triggered email is ready, activate it from the Triggered Email Dashboard by clicking **Activate Triggered Email** and typing **ACCEPT** to confirm.
A screenshot of the Triggered Email Dashboard showing the Activate button in the top left corner.

The Triggered Email Dashboard showing the Activate button in the top left corner.

# Deploying Your Event Every event has a unique URL. How you share that URL determines what data you can collect and how personalised the experience can be. ### Event Link Every event has a live URL accessible from the Event Dashboard. You can share this link in a regular email, add it to your website, or embed the event registration form as an inline frame using the **Get Deployment Code** option.
A screenshot showing the Deploy Code screen showing the three embedding options — standard link, popup window, and inline frame — with the generated code displayed below.

The Deploy Code screen showing the three embedding options — standard link, popup window, and inline frame — with the generated code displayed below.

Registrations collected via a plain link are recorded as anonymous. You will not know who registered unless they provide their details in the form. *** ### UbiQuity Email Sending your event via UbiQuity emails connect each registration to a database contact. This gives you the ability to: * Send reminder emails only to contacts who have not yet registered * Filter your database based on registrations * Merge database fields into the event form, confirmation pages, and triggered emails To deploy via a UbiQuity email, ensure your event is active, then create a mailout and use the Insert UbiQuity Link button to insert the event link into your email content.
A screenshot of the button used to insert UbiQuity links in the standard content editor.

Use the highlighted button to insert UbiQuity links.

You can also add your event link to a form triggered email, a survey Thank You page, or anywhere else in UbiQuity where the Insert UbiQuity Link function is available. # Registrations and Reporting Once your event is live, you can view and manage registrations in real time, filter and download the data, and share a report with others. ### Viewing Registrations Go to the Event Dashboard and click **View Registrations** to see all registrations for your event.
A screenshot of the View registrations page, showing preview registrations and live registrations.

View your preview registrations and live registrations.

Registrations created while you are designing and previewing your event are **Preview** registrations. You need at least one preview registration to test triggered email merge fields before going live. **Live** registrations come from the live event URL or from clicking Register For Your Event from the Event Dashboard. When registering manually from the dashboard, you can link the registration to an existing database contact, which has the same effect as the contact clicking a personalised link from a UbiQuity email. If your event was deployed via a UbiQuity email, you can also view a contact's registration history from their record in the database. *** ### Editing Registrations You can edit individual registrations to update their status or correct details. Changing a registration status will trigger any relevant triggered emails. UbiQuity will give you the option to suppress these if needed. *** ### Filtering Registrations From the View Registrations screen, click **Live** Registrations and use the filter options to narrow results. You can filter by event fields and registration metadata such as status. If the event was deployed via UbiQuity Mail, you can also filter by database fields.
A screenshot of the ability to filter responses by adding a filter condition.

View and filter responses by adding a filter condition.

*** ### Registration Statuses Each registration has one of the following statuses: **Unconfirmed** is the default status for new registrations. These do not count against total capacity. **Confirmed** registrations count against total capacity. You can set new registrations to automatically be confirmed under Event Settings. **Cancelled** registrations free up a place in the total capacity. For paid events, registrations also carry a payment status of **Paid** or **Unpaid**. Invoice-based payments start as Unpaid and must be updated manually once payment is received. *** ### Event Report Each event has a report accessible from the Event Dashboard by clicking **View Event Report**. You can share a link to this report with others who do not have a UbiQuity login. No personally identifiable information is included in the report. # Layouts Layouts control the look and feel of your forms, surveys, and events. Set up your branding once and apply it across everything you publish. ### Overview Layouts let you apply consistent branding and styling across all your UbiQuity forms, surveys, and events. Once you have created a layout, it is available across your entire UbiQuity account and can be applied to any form, survey, or event you create. You can set a default layout so that any new form, survey, or event you create automatically inherits your branding without any additional steps. If you have the Create Layout permission across multiple UbiQuity accounts, you can also copy layouts between accounts. Note that there are slight differences in how layouts apply across forms, surveys, and events. Surveys, for example, include next, back, and finish buttons that forms do not have. Keep these differences in mind when designing your layout and test it across each content type before applying it broadly. For advanced customisation of field positioning and layout within a form, survey, or event, contact UbiQuity for assistance. *** ### Accessing Layouts You can access Layouts from several places in UbiQuity, including the **Manage layouts** button within the Forms, Surveys, and Events modules.
A screenshot of the Manage layouts dropdown, showing options to select a default layout or edit layouts.

The Manage layouts dropdown, showing options to select a default layout or edit layouts.

*** ### Creating and Editing a Layout From the **Manage layouts** drop down, click **Edit layouts** to reach the Layouts list page. From there, you can either click into an existing Layout to edit it, or click **New Layout** to start a new layout, or select an existing layout to edit it. The layout editor has several tabs. The **Basic**, **Logo and Buttons**, and **Advanced** tabs are designed for most users and cover the majority of styling needs without requiring any coding knowledge. The **Base HTML**, **Content HTML**, and **Custom CSS** tabs are for web developers who need deeper control.
A screenshot of the Layouts list page showing an existing layout, with options to create a new layout or set default layouts.

The Layouts list page showing an existing layout, with options to create a new layout or set default layouts.

*** ### Basic and Logo & Buttons Tabs These tabs control the global styling of your layout — including fonts, colours, logos, and button icons or images.
A screenshot of the Basic tab of the layout editor showing styling options for font, wallpaper background, content background, and content width.

The Basic tab of the layout editor showing styling options for font, wallpaper background, content background, and content width.

A screenshot of the Logo & Buttons tab showing all configurable button types for the layout.

The Logo & Buttons tab showing all configurable button types for the layout.

*** ### Advanced Tab The **Advanced** tab gives you detailed control over the visual styling of your layout. Navigate to the specific page or state you want to style, for example a validation error message, and make changes while seeing them applied in real time in the preview below.
A screenshot of the Advanced tab showing granular styling controls for the selected page element.

The Advanced tab showing granular styling controls for the selected page element.

*** ### Base HTML Tab The **Base HTML** tab is for web developers. It controls the core HTML structure of the page including the background, header, footer, and content container, as well as which stylesheets and scripts are loaded. The most important element in the Base HTML is the `[ContentHTML]` marker. This is where the form, survey, or event content is injected into the page. You can move this marker but you must never remove it, or the content will not display. The Base HTML also uses Engage Scripting Language block tags to apply sections conditionally depending on whether the item being displayed is a form, survey, or event. Do not edit the block tags themselves, but you can change the content inside them.
A screenshot of the Base HTML tab showing the core HTML structure of the layout, including Engage Scripting Language block tags.

The Base HTML tab showing the core HTML structure of the layout, including Engage Scripting Language block tags.

*** ### Content HTML Tab The **Content HTML** tab is also for web developers. It controls how each item type, forms, surveys, and events, is structured and rendered within the base page. Use the toggle at the top to switch between item types. As with **Base HTML**, this tab uses Engage Scripting Language block tags. Avoid editing anything inside the block tag syntax itself, but you can adjust the HTML content within those blocks to change how sections are displayed.
A screenshot of the Content HTML tab with the Form view selected, showing the HTML structure for form content including validation and error block tags.

The Content HTML tab with the Form view selected, showing the HTML structure for form content including validation and error block tags.

*** ### Custom CSS Tab The **Custom CSS** tab lets you add your own CSS rules to customise the appearance of your layout beyond what the Basic and Advanced tabs provide. You can create new style rules, or create new classes and reference them in the Base HTML and Content HTML tabs. Click **Apply** at the bottom of the section to see your changes reflected in the preview.
A screenshot of the Custom CSS tab, showing an empty CSS editor ready for custom style rules.

The Custom CSS tab, showing an empty CSS editor ready for custom style rules.

*** ### Previewing a Layout You can preview your layout on a real form, survey, or event while you are working on it. Click **Change Preview** to select the item you want to preview, and use the page dropdown to navigate between different pages of that item, such as the introduction page, a question page, or the Thank You page. This means you can see your changes applied in context before pushing them live.
A screenshot of the layout editor preview showing a form rendered with the current layout applied.

The layout editor preview showing a form rendered with the current layout applied.

*** ### Applying a Layout You can apply a layout to a form, survey, or event in two ways. The first is from within the item itself, on the **Select Layout and Preview** step when building or editing it. The second is directly from the layout editor by previewing the item you want to apply it to and clicking **Apply Layout,** then **Save and Apply**.
A screenshot of the Apply Layout confirmation dialog prompting you to save and apply the layout to the selected form.

The Apply Layout confirmation dialog prompting you to save and apply the layout to the selected form.

*** ### Default Layouts To set a layout as the default for all new forms, surveys, and events, click **Set default layouts** from the Layouts list page.
A screenshot of the Layouts list page showing the Set default layouts button.

The Layouts list page showing the Set default layouts button.

From here, you are able to view and change the default layouts.
A screenshot of the set your default layouts dialog showing the default layout selections for Forms, Surveys, Survey Reports, and Events.

The Set your default layouts dialog showing the default layout selections for Forms, Surveys, Survey Reports, and Events.

# Choosing an integration method Understand the different ways to bring data into UbiQuity, and choose the right approach based on your use case. ### Data & Integrations UbiQuity provides multiple ways to capture and manage data. The right method depends on how often your data changes, how automated the process needs to be, and whether you require real-time interaction. *** ### Quick guide | Use case | Best option | | -------------------------------- | ----------- | | One-off or occasional uploads | Imports | | Ongoing, automated data sync | Connectors | | Real-time or custom integrations | API | *** ### [Imports](/documentation/data-and-integrations/imports) Imports allow you to upload data into UbiQuity using files such as CSV. This is the simplest way to get data into the platform and is typically used for one-off or occasional updates. Common use cases include: * Uploading campaign or marketing lists * Migrating data into UbiQuity * Making ad hoc updates to contact records Imports are quick and flexible, but they are manual and not designed for ongoing synchronisation. *** ### [Connectors](/documentation/data-and-integrations/connectors) Connectors allow UbiQuity to automatically exchange data with external systems on a scheduled basis. They support both: * Importing data into UbiQuity from external sources (import connectors) * Exporting data from UbiQuity to external systems (export connectors) This enables both pull and push data flows, depending on your use case. At this stage, connectors operate using flat files and support the following storage locations: * Azure Blob Storage * Amazon S3 * SFTP Connectors are designed for situations where data changes regularly and needs to stay up to date without manual effort. Common use cases include: * Regularly importing customer or transactional data * Exporting audience or engagement data to external systems * Keeping datasets in sync between UbiQuity and other platforms Connectors reduce manual work and help ensure your data remains consistent over time. *** ### [API](/documentation/data-and-integrations/api) The API allows external systems to send and retrieve data from UbiQuity programmatically. It provides the most flexibility and is typically used for real-time or highly customised integrations. Common use cases include: * Capturing events or behaviours in real time * Triggering workflows from external systems * Building custom integrations with internal or third-party platforms Using the API usually requires developer support, but enables more advanced use cases than imports or connectors. *** ### Choosing the right approach If you're unsure which option to use, start by considering: * How often does the data need to be updated? * Does the process need to be automated? * Do you need real-time interaction or is scheduled data sufficient? In many cases: * Use imports for simple, one-off needs * Use connectors for ongoing data sync * Use the API for real-time or advanced integrations # Imports Upload contacts and data into UbiQuity from a file — the simplest way to get data into the platform without a technical integration. ### Overview Imports let you upload data into UbiQuity using a CSV or text file. This is the most straightforward way to get data into the platform when you are working with an exported list and do not need an ongoing automated connection. Imports are best suited for one-off uploads, occasional updates, campaign-specific lists, and bulk corrections. If you need data to flow into UbiQuity automatically on an ongoing basis, consider using a Connector or the API instead. All imports follow the same core process regardless of what you are importing: upload your file, map your columns to UbiQuity fields, configure how records should be created or updated, and run the import. *** ### What you can import UbiQuity supports two types of imports: **Contacts** — Add or update people in your database, including any profile or contact information you hold against them. See Importing Contacts. **Transactions** — Upload transactional or behavioural data linked to your contacts, such as purchase history or service records. See Importing Transactions. *** ### Things to keep in mind * Imports are manual. You need to run them each time you want to upload data. * Changes in your source data will not automatically update in UbiQuity. * Only CSV and text files are supported. Excel workbooks (.xls/.xlsx) are not accepted — save your file as a CSV before importing. * Clean, consistent data will reduce errors and improve results. UbiQuity validates data against field types during the import, so mismatched data will be rejected. *** ### Where to go next Choose the type of data you want to import: * [Importing contacts](#importing-contacts) * [Importing transactions](#importing-transactions) # Importing contacts A step-by-step guide to uploading and updating contacts in your UbiQuity database using a CSV or text file. ### Overview Importing is the quickest way to get a large number of contacts into your UbiQuity database, or to update existing ones in bulk. Rather than adding contacts one by one, you prepare your data in a spreadsheet, export it as a CSV, and work through the import wizard. You can also use the import function to bring contacts in directly from UbiQuity Survey responses or Event registrations, without needing to download data from those modules first. To access the import screen, go to **Database** then **Manage Imports.**
Screenshot of the Import Contacts screen in UbiQuity showing the Import Contacts button in the left panel and a table listing previous imports with their details and progress.

The Import Contacts screen, accessed via Database then Manage Imports.

*** ### Before you start A few things worth checking before you run an import: * Your file should be in CSV or text format. Excel workbooks are not supported - if your data is in Excel, save it as a CSV before importing. * Your file should ideally have column headings in the first row. These do not need to match the names of your UbiQuity fields exactly, as you will map them during the import. * Give your import file a meaningful name before uploading. The file name becomes the import name in UbiQuity, and a descriptive name makes it easier to identify later - especially if others share the account. * Check that your data is clean and consistent. UbiQuity validates data against field types during the import, and rows that do not match will be rejected. *** ### Step 1 - Select import source On the Import Source screen, choose how you are importing your data: * **Import from a file** - Upload a CSV or text file from your computer * **Import from an Engage survey** - Pull in responses from a UbiQuity survey * **Import from an Engage event** - Pull in registrations from a UbiQuity event If importing from a file, select your file and confirm that the first row contains field names.
A screenshot of the Import Source screen showing the import type selector, file upload, and a data preview.

The Import Source screen showing the import type selector, file upload, and a data preview.

*** ### Step 2 - Map your fields Field mapping is one of the most important steps in the import process. This is where you match the columns in your file to the correct fields in your UbiQuity database. For each column on the left, select the corresponding UbiQuity field on the right. If a column is not relevant, you can choose to ignore it. If you need a field that does not yet exist in your database, you can create a new one directly from this screen (subject to your user permissions). After mapping, a data preview will show a snapshot of how your data will be brought in. If you have ignored or added columns, click Refresh to update the preview.
A screenshot of the Field Mapping screen showing Import Fields mapping, as well as a Data Preview below.

The Field Mapping screen showing Import Fields mapping, as well as a Data Preview below.

*** ### Step 3 - Analysing data UbiQuity analyses your data before making any changes to the database. Any rows that do not meet the required criteria are identified and rejected at this stage. Rows are rejected here if the data does not match the field type. Common examples include an email address missing the @ symbol, or a mobile number with a missing leading zero. If you see rejections at this stage you have two options - download the error list, cancel the import to fix your file and start again, or continue with the import and download the errors at the end.
A screenshot of the Analysing Data screen showing the valid rows and invalid rows, and progress status.

The Analysing Data screen showing the valid rows and invalid rows, and progress status.

*** ### Step 4 - Select update type Choose how UbiQuity should handle the records in your file: * **Append/Update** - Adds any contacts that do not already exist, and updates those that do. This is the most commonly used option. * **Append** - Only adds new contacts. Any contact that already exists in the database will be skipped. * **Update** - Only updates existing contacts. Any contact that does not already exist will be skipped.
A screenshot of the update type screen showing the three import options — Append/Update, Append, and Update.

The Update Type screen showing the three import options — Append/Update, Append, and Update.

#### Matching fields For Append/Update and Update imports, UbiQuity needs to know how to identify whether a contact already exists. This is done using matching fields - the fields UbiQuity will use to look up each row against your existing contacts. You should use the unique field or fields set on your database. For example, if your database is unique on email address, select Email Address as the matching field. If it is unique on a combination of fields, select all of them. Do not tick all available columns - this will likely cause rows to be rejected.
A screenshot of the Select Matching Fields screen with Email Address selected as the matching field.

The Select Matching Fields screen with Email Address selected as the matching field.

#### Importing blank values If your file contains blank values for some fields, you can choose how UbiQuity handles them: * **Preserve existing data** - Blank values in the file are ignored, and any existing values in the database are kept. * **Import blank values** - Blank values in the file will overwrite existing values in the database.
A screenshot of the Importing Blank Values screen showing the two options for handling blank fields in the import file.

The Importing Blank Values screen showing the two options for handling blank fields in the import file.

*** ### Step 5 - Indexing data Indexing is the second stage where rows can be rejected. Rows fail here due to duplication issues rather than data formatting problems. This happens when your file contains two rows with the same matching field values, or when a row in your file matches multiple contacts in the database. UbiQuity cannot determine which row to keep, so all affected rows are rejected. As with the Analysing Data stage, you can download the error list and either cancel to fix your file or continue and review errors at the end.
A screenshot of the Indexing Data screen showing the rows to insert, update and skip, and progress status.

The Indexing Data screen showing the rows to insert, update and skip, and progress status.

*** ### Step 6 - Confirm The final screen shows a summary of your import before it runs, including the import type, matching criteria, blank value handling, and a full mapping table showing how each column will be handled. Review the details carefully, then click **Finish,** type **ACCEPT** and click **Import Contacts** to run the import.
A screenshot of the Confirm Import Details screen showing a summary of import settings and a field mapping table.

The Confirm Import Details screen showing a summary of import settings and a field mapping table.

A screenshot of the Import Contacts confirmation dialog where you type ACCEPT to run the import.

The Import Contacts confirmation dialog where you type ACCEPT to run the import.

**Import progress** Once the import is running, the progress screen will show when it has completed, including a breakdown of rows inserted, updated, and skipped. If any rows were skipped, an error file will be available to download at the bottom of the page. This file is only available for 7 days after the import, so download it promptly if you need to review and fix errors. You can return to this screen at any time from the Import Contacts list by clicking the page icon next to a previous import.
A screenshot showing the import progress screen showing the rows inserted, updated and skipped, with progress status.

The import progress screen showing the rows inserted, updated and skipped, with progress status.

*** ### Frequently asked questions **Why are there invalid rows during the analysing stage?** This is caused by data in your file not matching the field type in the database. Common examples are an email address missing the @ symbol, or a mobile number where the leading zero has been dropped by Excel. Mobile numbers must be in NZ format (02 + 6 to 9 digits) or include an international country code such as 6421 123 456. **Why are there invalid rows during the indexing stage?** This is caused by duplicate matching field values - either in your import file or in your database. UbiQuity cannot determine which row to keep, so all affected rows are rejected. Check your file for duplicate entries on the matching field. **What should I select for matching fields?** Use the unique field or fields set on your database. You can find these under **Database > Edit Fields** at the bottom of the page. If you are unsure, contact your UbiQuity account manager. **Why is my file not uploading?** UbiQuity only accepts CSV and text files. Excel workbooks (.xls or .xlsx) are not supported. To convert, open your file in Excel and save it using the CSV option - note that CSV files can only contain a single sheet. **Why does the number of contacts in my import differ from my mailout filter?** Contacts that are opted out or marked as GNA are automatically excluded from email sends. The import may have succeeded for those contacts, but they will not appear in an emailable filter. See Opt Outs and GNA for more information. **Why can I not add new contacts?** If you see the error "In order to Append contacts you need to have mapped all mandatory fields with no default values", it means your database has a mandatory field with no default value that is not included in your import file. Every new contact must have a value for this field. Check your mandatory fields under **Database > Edit Fields** and either include the field in your import or remove the mandatory requirement if it is no longer needed. # Importing transactions A step-by-step guide to uploading and updating transactional data linked to your contacts in UbiQuity. ### Overview Importing transactions is an easy way to load large amounts of transactional data into UbiQuity. Rather than adding records manually against each contact, you prepare your data in a spreadsheet, export it as a CSV, and work through the import wizard. Each transaction in your import must be linked to an existing contact in your database. UbiQuity uses a lookup field during the import to match each row to the correct contact. To access the import screen, go to **Database > Manage Transactional Data** and select the transactional database you want to import into. Then go to **Manage Imports**, and click **Import Transactions.**
A screenshot of the Import Transactions screen, accessed via Database then Manage Transactional Data then Manage Imports.

The Import Trasnsactions screen, accessed via Database then Manage Transactional Data then Manage Imports.

*** ### Before you start * Your file should be in CSV or text format. Excel workbooks are not supported — save your file as a CSV before importing. * Your file should ideally have column headings in the first row. * Every row in your import must correspond to an existing contact in your database. Rows that cannot be matched to a contact will be rejected. * Check that your data is clean and consistent. UbiQuity validates data against field types during the import, and rows that do not match will be rejected. *** ### Step 1 — Select import Source On the Import Source screen, select **Import from a file** and upload your CSV or text file. Confirm whether your the first row in your file contains field names.
A screenshot of the Import Source screen showing the import type selector, file upload, and a data preview.

The Import Source screen showing the import type selector, file upload, and a data preview.

*** ### Step 2 — Map your fields This step has two parts. **Select lookup fields** — Choose the fields UbiQuity will use to identify which contact each transaction belongs to. This could be the contact's Reference ID, or another unique field in your database such as a Customer ID or Email Address. **Map imported fields** — Match the remaining columns in your file to the correct fields in your transactional database. You can ignore columns that are not needed, map to existing fields, or create new fields directly from this screen.
A screenshot of the Field Mapping screen showing Lookup Fields mapping and Import Fields mapping, as well as a Data Preview below.

The Field Mapping screen showing Lookup Fields mapping and Import Fields mapping, as well as a Data Preview below.

*** ### Step 3 — Analysing Data UbiQuity analyses your data before making any changes. Rows that do not meet the required criteria are identified and rejected at this stage. Rows are rejected here if the data does not match the expected field type — for example, text being imported into a number field. If you see rejections at this stage you can download the error list and either cancel to fix your file and start again, or continue and download the errors at the end.
A screenshot of the Analysing Data screen showing the valid rows and invalid rows, and progress status.

The Analysing Data screen showing the valid rows and invalid rows, and progress status.

*** ### Step 4 — Select update type Choose how UbiQuity should handle the records in your file: * **Append/Update** — Adds any transactions that do not already exist, and updates those that do. This is the most commonly used option. * **Append** — Only adds new transactions. Any transaction that already exists will be skipped. * **Update** — Only updates existing transactions. Any transaction that does not already exist will be skipped.
A screenshot of the Update Type screen showing the three import options — Append/Update, Append, and Update.

The Update Type screen showing the three import options — Append/Update, Append, and Update.

**Matching fields** For Append/Update and Update imports, select the fields UbiQuity will use to identify whether a transaction already exists. This should be the unique field or fields set on your transactional database — for example, a unique transaction ID or order number.
A screenshot of the Select Matching Fields screen with Order Number selected as the matching field.

The Select Matching Fields screen with Order Number selected as the matching field.

**Importing blank values** If your file contains blank values for some fields, choose how UbiQuity handles them: * **Preserve existing data** — Blank values in the file are ignored and existing values are kept. * **Import blank values** — Blank values in the file will overwrite existing values.
A screenshot of the Importing Blank Values screen showing the two options for handling blank fields in the import file.

The Importing Blank Values screen showing the two options for handling blank fields in the import file.

*** ### Step 5 — Indexing Data Indexing is the second stage where rows can be rejected. Rows fail here due to duplication issues rather than data formatting problems. This happens when your file contains two rows with the same matching field values, or when a row matches multiple transactions already in the database. UbiQuity cannot determine which row to keep, so all affected rows are rejected. As with the Analysing Data stage, you can download the error list and either cancel to fix your file or continue and review errors at the end.
A screenshot of the Indexing Data screen showing the rows to insert, update and skip, and progress status.

The Indexing Data screen showing the rows to insert, update and skip, and progress status.

*** ### Step 6 — Confirm The final screen shows a full summary of your import before it runs, including the update type, matching criteria, blank value handling, and a mapping table showing how each column will be handled. Review the details carefully, then confirm to run the import.
A screenshot of the Confirm Import Details screen showing a summary of import settings and a field mapping table.

The Confirm Import Details screen showing a summary of import settings and a field mapping table.

A screenshot of the Import Contacts confirmation dialog where you type ACCEPT to run the import.

The Import Contacts confirmation dialog where you type ACCEPT to run the import.

**Import progress** Once the import is running, the progress screen will show when it has completed, including a breakdown of rows inserted, updated, and skipped. If any rows were skipped, an error file will be available to download at the bottom of the page. This file is only available for 7 days after the import.
A screenshot of the import progress screen showing the rows inserted, updated and skipped, with progress status.

The import progress screen showing the rows inserted, updated and skipped, with progress status.

*** ### **Frequently asked questions** **Why are rows being rejected during the analysing stage?** This is caused by data in your file not matching the field type in the transactional database. For example, importing text into a number field. Check the error file for details on which rows failed and why. **Why are rows being rejected during the indexing stage?** This is caused by duplicate matching field values in your file, or a row matching multiple existing transactions in the database. UbiQuity cannot determine which row to keep, so all affected rows are rejected. Check your file for duplicates on the matching field. **What should I select for matching fields?** Use the unique field or fields set on your transactional database. You can find these under **Database > Manage Transactional Data > Edit Database Fields** at the bottom of the page. **What happens if a row cannot be matched to a contact?** Rows that cannot be matched to a contact in your database will be rejected. Make sure the lookup field values in your import file correspond to contacts that already exist in UbiQuity. You may need to import or update your contacts first before importing transactions. # Connectors Automate data flows between your systems and UbiQuity using file-based integrations with SFTP, Microsoft Azure Blob Storage, and Amazon S3. {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} ### What are Connectors? Connectors let you automatically move data between your systems and UbiQuity, removing the need for manual uploads or custom-built integrations. They are self-service integration pipelines that import and export flat files between UbiQuity and external storage locations such as SFTP, Microsoft Azure Blob Storage, and Amazon S3. For imports, Connectors automatically scan configured storage locations every five minutes and process matching files. For exports, Connectors generate files on a defined schedule and deliver them to your chosen storage location. Once configured, Connectors run automatically in the background, keeping your data up to date and ready to use for campaigns, journeys, reporting, and downstream systems. Connectors replace UbiQuity’s legacy importer and exporter tools and form part of our move toward a more standardised, product-led SaaS model. *** ### What can you do with Connectors? With Connectors, you can: * Import flat files from other systems into UbiQuity * Export flat files out of UbiQuity for use in other systems * Automate recurring data flows without manual intervention Connectors support flat file integrations with: * SFTP Servers * Microsoft Azure Blob Storage * Amazon S3 Each connector is configured for a specific data flow and runs independently, allowing you to manage multiple integrations in parallel. # Before You Begin What you need to know and have in place before setting up your first Connector. {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} ### Overview Connectors are a paid feature available to all UbiQuity customers. Access is controlled by user permissions, and some setup steps will require involvement from technical teams within your organisation. Taking a few minutes to prepare before you start will help ensure your Connector runs smoothly once it's active. *** ### Permissions Access to Connectors is controlled by user permissions within UbiQuity. You need the appropriate permission to view the Connectors dashboard. Additional permissions are required to create, edit, and manage Connectors. If you cannot see Connectors in the menu, or do not have permission to make changes, contact an administrator within your organisation or reach out to your UbiQuity account manager. *** ### What you need before you start #### **A supported storage location** Connectors work with storage locations that you host and manage within your own environment. UbiQuity does not host storage on your behalf. Supported storage types are: * SFTP * Microsoft Azure Blob Storage * Amazon S3 Before setting up a Connector, make sure your storage location is provisioned and accessible. See Connection Setup for instructions specific to your storage type. #### **Access credentials** You will need credentials that allow UbiQuity to connect securely to your storage location. | Storage type | Credentials needed | | ------------------ | ---------------------------------------------------------------------- | | SFTP | Hostname, username, and SSH key or password | | Azure Blob Storage | Storage account details and SAS token or Application Service Principal | | Amazon S3 | Bucket details and IAM role or access keys | Use dedicated service accounts where possible, and limit access to only the folders or containers required for the Connector. #### **A sample file (imports only)** If you are setting up an Import Connector, you will need a representative sample CSV file to upload during setup. Your sample file should: * Use the same structure as the files you plan to import * Include a header row * Contain realistic data values All fields referenced by the Connector must already exist in UbiQuity. Connectors do not create database fields. #### **An understanding of your data flow** Before starting, be clear on the following: * Whether you are importing data into UbiQuity or exporting data out * Which database is in scope — Contact, Transactional, or both * How often the Connector should run. Import Connectors scan for matching files every five minutes automatically. Export Connectors run on a schedule you configure. *** ### Involving the right people You do not need to be technical to configure a Connector within UbiQuity. However, the underlying storage and access controls are typically managed by IT or cloud platform teams within your organisation. You may need support from: * IT or infrastructure teams * Cloud platform teams (AWS, Azure) * Security or compliance teams These teams can provision storage, generate credentials, and confirm that the setup meets your organisation's security and data residency requirements. *** ### Pricing and billing Connectors are billed monthly, per Connector. Billing begins when a Connector is activated and is charged for the full month — partial months are not prorated. If you deactivate a Connector during the month, the full monthly charge still applies for that billing period. See the [UbiQuity pricing page](https://www.ubiquity.co.nz/platform/connectors#pricing) for current Connector pricing. # Creating a Connector # Connection Setup How to configure UbiQuity's connection to your SFTP server, Azure Blob container, or Amazon S3 bucket. {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} Each Connector requires a secure connection to a storage location that you host and manage within your own environment. The configuration steps vary depending on your storage type. Select your storage type below to get started. *** ### Amazon S3 Connect UbiQuity to an Amazon S3 bucket using IAM role assumption. No permanent access keys are stored in UbiQuity. Setting Up Your [Amazon S3 Connection →](/documentation/data-and-integrations/connectors/connection-setup/s3-connection) *** #### Microsoft Azure Blob Storage Connect UbiQuity to an Azure Blob container using a service principal or SAS token. Setting Up Your [Azure Blob Storage Connection →](/documentation/data-and-integrations/connectors/connection-setup/azure-blob-storage-connection) *** #### SFTP Connect UbiQuity to an SFTP server using SSH key authentication or a username and password. Setting Up Your [SFTP Connection →](/documentation/data-and-integrations/connectors/connection-setup/sftp-connection) *** > **Not sure which storage type to use?** This decision is usually made by your IT or cloud platform team. See [Before You Begin](/documentation/data-and-integrations/connectors/before-you-begin) for guidance on involving the right people. # S3 Connection Configure AWS IAM roles and permissions to connect your Amazon S3 bucket to UbiQuity Connectors. {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} This guide walks you through configuring your AWS account so that UbiQuity can securely connect to your Amazon S3 bucket. The setup involves creating an IAM role in your AWS account and granting UbiQuity permission to assume it - no long-lived access keys or secrets are required. *** ### How it works UbiQuity connects to your S3 bucket using **cross-account IAM role assumption**. When the connector runs, UbiQuity's service temporarily assumes a role in your AWS account using AWS STS. This means: * Credentials are temporary and expire after one hour. The connector refreshes them automatically * Access is scoped to only the S3 permissions you grant * Your UbiQuity Account ID acts as an External ID, preventing any other UbiQuity customer from assuming your role * No permanent access keys are stored in UbiQuity *** ### Before you begin You'll need the following before starting: | What you need | Description | Example | | ----------------------- | ----------------------------------------------------------------------------------------------- | ------------------------ | | **AWS Account ID** | Your 12-digit AWS account identifier | `123456789012` | | **S3 Bucket Name** | The bucket the connector will read from or write to | `customer-data-imports` | | **S3 Region** | The AWS region where your bucket is hosted | `ap-southeast-2` | | **UbiQuity Account ID** | Your Database ID in base64 format — find this in UbiQuity under **API > API IDs > Database ID** | `xWqJBlwfjUOUcQjd5gt7vQ` | *** ### Step 1: Create the IAM role In your AWS account, create an IAM role with the following name: ``` ubiquity-connectors-s3-access-role ``` > **Important:** This exact role name is required. UbiQuity's infrastructure uses a specific AssumeRole policy targeting `arn:aws:iam::*:role/ubiquity-connectors-s3-access-role` to avoid wildcard role names while supporting multiple customer accounts. *** ### Step 2: Configure the trust policy The trust policy controls who is allowed to assume the role. Apply the policy below, replacing `YOUR_UBIQUITY_ACCOUNT_ID` with your UbiQuity Database ID (found at **API > API IDs > Database ID** in the platform). json ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::049579744830:root" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "YOUR_UBIQUITY_ACCOUNT_ID" } } } ] } ``` **Why the External ID matters:** All UbiQuity customers share the same UbiQuity AWS account. The External ID condition ensures that only your connectors, authenticated with your specific UbiQuity Account ID, can assume your role. *** ### Step 3: Attach a permissions policy Create a new IAM policy named `ubiquity-s3-access-policy` and attach it to the role from Step 1. Replace `YOUR_BUCKET_NAME` with your actual bucket name. json ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ListBucket", "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME" }, { "Sid": "ObjectOperations", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*" } ] } ``` What each permission is for: * `s3:ListBucket` — allows the connector to list objects in the bucket and verify the connection * `s3:GetObject` — allows the connector to read your data files for import * `s3:PutObject` — allows the connector to write files to your archive and error subdirectories after processing * `s3:DeleteObject` — used alongside PutObject to move processed files into your archive and error subdirectories > **Note:** Files are never permanently deleted. After processing, they are moved to an archive subfolder (or error subfolder if processing fails), preserving a full history of what was imported. *** ### Step 4: Add the connector in UbiQuity Once your IAM role is configured: 1. In UbiQuity, go to **Database > Connectors > Add Connector** 2. Select **Amazon S3** 3. Enter the following details: * **AWS Account ID** — your 12-digit AWS account ID * **Region** — the AWS region where your bucket is hosted (e.g. `ap-southeast-2`) * **Bucket Name** — your S3 bucket name (case-sensitive) * **Prefix** *(optional)* — a folder path to limit connector access to a specific location within the bucket (e.g. `imports/`) 4. Click **Test Connection** A successful test will return: *"Connection successful. Found X files in bucket."* *** ### Troubleshooting **"Access denied" or "Not authorised to perform sts:AssumeRole"** The connector cannot assume your IAM role. Check the following: * The role name is exactly `ubiquity-connectors-s3-access-role` (case-sensitive) * The trust policy Principal is `arn:aws:iam::049579744830:root` * The External ID in the trust policy matches your UbiQuity Account ID exactly — copy it directly from the platform to avoid whitespace issues **Role assumption succeeds but S3 operations fail** The connector can reach your account but cannot access the bucket. Check: * The `ubiquity-s3-access-policy` is attached to the role * Your bucket policy doesn't contain an explicit `Deny` that would override the IAM permissions * If your bucket uses SSE-KMS encryption, the KMS key policy must grant `kms:Decrypt` and `kms:DescribeKey` to the assumed role (see Encrypted buckets below) **"Bucket does not exist in region"** * Double-check the bucket name — it is case-sensitive and must not contain spaces * Verify the region in UbiQuity matches the actual region of your bucket * Confirm the bucket exists in the same AWS account as the IAM role **"Invalid External ID" or "External ID mismatch"** * Copy your UbiQuity Account ID directly from **API > API IDs > Database ID** in the platform * Check for any extra spaces or line breaks that may have been introduced when pasting *** ### Additional configuration **Restricting access to a specific folder** If you'd prefer the connector to only access a specific prefix within your bucket rather than the full bucket, use this modified policy: json ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ListBucket", "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME", "Condition": { "StringLike": { "s3:prefix": ["imports/ubiquity/*"] } } }, { "Sid": "ObjectOperations", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/imports/ubiquity/*" } ] } ``` **Encrypted buckets** The connector supports S3 server-side encryption as follows: * **SSE-S3** — supported out of the box (AWS default encryption) * **SSE-KMS** — supported, provided the KMS key policy grants `kms:Decrypt` and `kms:DescribeKey` to the assumed role. Add the following to your KMS key policy, replacing `YOUR_AWS_ACCOUNT_ID`: json ```json { "Sid": "AllowUbiQuityConnectorDecrypt", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/ubiquity-connectors-s3-access-role" }, "Action": [ "kms:Decrypt", "kms:DescribeKey" ], "Resource": "*" } ``` * **SSE-C** — not supported (requires client-managed keys) **Granting access to multiple buckets** Extend the permissions policy to include each bucket: json ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ListBuckets", "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": [ "arn:aws:s3:::bucket-one", "arn:aws:s3:::bucket-two" ] }, { "Sid": "ObjectOperations", "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::bucket-one/*", "arn:aws:s3:::bucket-two/*" ] } ] } ``` Note that buckets in different AWS regions will each need a separate connector configured in UbiQuity, but can share the same IAM role. **Revoking access** To remove UbiQuity's access at any time, you have three options: * **Delete the role** — immediately and permanently revokes access * **Modify the trust policy** — remove the UbiQuity statement or change the External ID to invalidate future sessions * **Disable the connector in UbiQuity** — prevents new connections being initiated; any active session will expire within the hour regardless *** ### Need help? If you run into issues during setup, contact our support team at [**support@ubiquity.co.nz**](mailto:support@ubiquity.co.nz) with the following details: * Your AWS Account ID (12 digits) * Your S3 bucket name and region * Any error messages shown in UbiQuity or your AWS CloudTrail logs * Screenshots of your IAM role configuration # Azure Blob Storage Connection Configure your Azure Blob Storage account and authentication so UbiQuity can securely connect to your container. {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} This guide walks you through configuring your Azure Blob Storage account so that UbiQuity can securely connect to your container. Two authentication methods are supported — SAS token or Service Principal — and the guide covers both. *** ### **How it works** UbiQuity connects to your Azure Blob Storage container using credentials you provide during setup. When the connector runs, it authenticates directly using either a SAS token or a Service Principal, then reads from or writes to your configured container path. * Access is scoped to only the container and permissions you grant * Files are never permanently deleted — after processing, they are moved to an `archive/` subfolder, or an `error/` subfolder if processing fails * No data is stored by UbiQuity beyond what is written into the platform during import *** ### **Before you begin** You'll need the following before starting: | What you need | Description | Example | | ------------------------ | --------------------------------------------------- | ------------------ | | **Storage Account Name** | The name of your Azure Storage account | `mystorageaccount` | | **Container Name** | The Blob container the connector will use | `ubiquity-imports` | | **Base Path** | Directory path within the container | `data/inbound` | | **Authentication** | Either a SAS token or Service Principal credentials | See below | *** ### **Step 1: Choose your authentication method** UbiQuity supports two authentication methods for Azure Blob Storage. Choose the one that best fits your environment. | Method | Best for | | --------------------- | ------------------------------------------------------------------------------- | | **SAS Token** | Scoped, time-limited access — simpler to set up | | **Service Principal** | Enterprise environments requiring Azure RBAC and longer-lived, auditable access | *** ### **Step 2: Configure authentication** #### **Option A: SAS Token** A Shared Access Signature (SAS) provides time-limited, permission-scoped access to your storage resources. In the Azure Portal, go to your **Storage Account > Shared access signature** and configure the following settings: | Setting | Required value | | -------------------------- | --------------------------------------------------------------------- | | **Allowed services** | Blob, File | | **Allowed resource types** | Container, Object | | **Allowed permissions** | Read, Write, Delete, List, Add, Create | | **Expiry** | Set according to your security policy — establish a rotation schedule | Click **Generate SAS and connection string**, then copy the SAS token value (it begins with `?sv=`). > **Note:** SAS tokens cannot be revoked individually. To invalidate a token before expiry, rotate the storage account key — this invalidates all SAS tokens generated with that key. #### **Option B: Service Principal** A Service Principal uses a registered Azure application with client credentials via Microsoft Entra ID. This is the preferred method for production environments. **1. Register an application in Microsoft Entra ID** 1. Go to **Azure Portal > Microsoft Entra ID > App registrations > New registration** 2. Note the **Application (client) ID** and **Directory (tenant) ID** **2. Create a client secret** 1. Go to **App registration > Certificates & secrets > New client secret** 2. Set an appropriate expiry and copy the secret value immediately — it will not be shown again **3. Assign Storage Blob permissions** 1. Go to **Azure Portal > Storage Account > Access Control (IAM)** 2. Select **Add role assignment** 3. Assign the role **Storage Blob Data Contributor** to your registered application > **Tip:** Assign the role at the container level rather than the storage account level to limit access to only what the connector needs. *** ### **Step 3: Add the connector in UbiQuity** Once authentication is configured: 1. In UbiQuity, go to **Database > Connectors > Add Connector** 2. Select **Microsoft Azure Blob Storage** 3. Enter the following details: * **Storage Account Name** — your Azure Storage account name * **Container Name** — the Blob container for connector files (case-sensitive) * **Base Path** — the directory path within the container (e.g. `data/inbound`) * **Authentication method** — select SAS Token or Service Principal and provide the corresponding credentials 4. Click **Test Connection** A successful test confirms the container is accessible and that UbiQuity has the required read, write, and delete permissions. *** ### **Troubleshooting** **"Failed to authenticate" or "The provided credentials are invalid"** The connector cannot authenticate with your storage account. Check: * For SAS tokens — confirm the token has not expired and includes all required permissions and services * For Service Principals — verify the client ID, tenant ID, and client secret are correct and the secret has not expired * Confirm the storage account name matches the credentials provided **"Insufficient permissions" or HTTP 403** Authentication succeeded but the connector cannot perform required operations. Check: * SAS token permissions include Read, Write, Delete, List, Add, and Create * SAS token resource types include Container and Object * For Service Principals — confirm the **Storage Blob Data Contributor** role is assigned on the correct container or storage account * Check whether the storage account has firewall or network rules blocking access from outside Azure **"Container does not exist"** * Verify the container name exactly — it is case-sensitive, must be lowercase, and cannot contain spaces * Confirm the container exists in the Azure Portal * Confirm the credentials correspond to the correct storage account **No files found for processing** * Check that files exist in the configured base path * Verify the file pattern configured in UbiQuity matches your file naming convention * Check the `archive/` directory — files that have already been processed will have been moved there *** ### **Additional configuration** **Credential rotation** After rotating either a SAS token or a Service Principal client secret, update the connector configuration in UbiQuity immediately to avoid failed runs. | Method | Rotation approach | | ----------------- | --------------------------------------------------------------- | | SAS Token | Generate a new token before expiry and update the connector | | Service Principal | Rotate the client secret before expiry and update the connector | **Data retention** Processed files are retained in the `archive/` subdirectory and failed files in the `error/` subdirectory. Configure Azure Blob Storage lifecycle management policies to manage how long these files are kept. A minimum of 30 days for archive files is recommended for audit purposes. *** ### **Need help?** If you run into issues during setup, contact our support team at [**support@ubiquity.co.nz**](mailto:support@ubiquity.co.nz) with the following details: * Your storage account name and container name * The authentication method used * Any error messages shown in UbiQuity * Screenshots of your SAS token configuration or Service Principal role assignments # SFTP Connection Configure your SFTP server and SSH key authentication so UbiQuity can securely connect to your files. {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} This guide walks you through configuring your SFTP server so that UbiQuity can securely connect to it. The setup involves creating a dedicated user account, generating an SSH key pair, and installing the public key on your server. *** ### **How it works** UbiQuity connects to your SFTP server over SSH using private key authentication. When the connector runs, it establishes a connection using the credentials you provide, then reads from or writes to your configured directory path. * Each connection is opened for the duration of the run and closed immediately after processing completes * Files are never permanently deleted — after processing, they are moved to an `archive/` subfolder, or an `error/` subfolder if processing fails * The `archive/` and `error/` directories are created automatically if they do not exist *** ### **Before you begin** You'll need the following before starting: | What you need | Description | Example | | --------------- | ------------------------------------- | -------------------- | | **Hostname** | DNS name of your SFTP server | `sftp.example.com` | | **Port** | SFTP port (default is 22) | `22` | | **Username** | A dedicated user account for UbiQuity | `ubiquity-connector` | | **Private Key** | SSH private key in PEM format | See below | | **Base Path** | Root directory for connector files | `/data/ubiquity` | > **Important:** The hostname must be a DNS name, not an IP address. This is required for connection uniqueness tracking within the platform. *** ### **Step 1: Generate an SSH key pair** Generate a dedicated SSH key pair for the UbiQuity connector. Either RSA or Ed25519 keys are supported. bash ```bash # RSA (4096-bit) ssh-keygen -t rsa -b 4096 -f ubiquity-connector-key -C "ubiquity-connector" # Ed25519 (modern, shorter) ssh-keygen -t ed25519 -f ubiquity-connector-key -C "ubiquity-connector" ``` This produces two files: * `ubiquity-connector-key` — the private key (provided to UbiQuity) * `ubiquity-connector-key.pub` — the public key (installed on your server) > **Important:** Do not use a passphrase when generating the key. The connector cannot prompt for a passphrase during an automated run. The private key must be in PEM format. Accepted formats: ``` -----BEGIN OPENSSH PRIVATE KEY----- [key content] -----END OPENSSH PRIVATE KEY----- ``` ``` -----BEGIN RSA PRIVATE KEY----- [key content] -----END RSA PRIVATE KEY----- ``` *** ### **Step 2: Configure your SFTP server** **Create a dedicated user account** Create a user specifically for the UbiQuity connector. Do not reuse an existing account. bash ```bash # Create user with no shell access useradd -m -s /usr/sbin/nologin ubiquity-connector # Create the directory structure mkdir -p /home/ubiquity-connector/data/ubiquity chown ubiquity-connector:ubiquity-connector /home/ubiquity-connector/data/ubiquity ``` The user should: * Be restricted to SFTP only — disable shell access where possible * Have a home directory or chroot set to the appropriate location * Have read and write permissions on the connector directory **Install the public key** Append the public key to the user's `authorized_keys` file on the server: bash ```bash cat ubiquity-connector-key.pub >> ~/.ssh/authorized_keys ``` **Required permissions** The SFTP user requires the following permissions on the base path and its subdirectories: | Permission | Purpose | | ---------- | ------------------------------------------------------ | | **Read** | List and download files for import | | **Write** | Create archive/error directories and upload files | | **Delete** | Remove files from source after moving to archive/error | | **Rename** | Move files between directories | | **Stat** | Check file existence and determine file types | | **Mkdir** | Create archive and error subdirectories | > **Important:** The base path cannot be the root directory (`/` or `.`). You must specify a subdirectory. *** ### **Step 3: Add the connector in UbiQuity** Once your server is configured: 1. In UbiQuity, go to **Database > Connectors > Add Connector** 2. Select **SFTP** 3. Enter the following details: * **Hostname** — the DNS name of your SFTP server * **Port** — the SFTP port (default: `22`) * **Username** — the dedicated user account created for the connector * **Private Key** — paste the contents of your private key file in PEM format * **Base Path** — the root directory for connector files (e.g. `/data/ubiquity`) 4. Click **Test Connection** A successful test confirms the server is reachable and that the user has the required read, write, and move permissions. *** ### **Troubleshooting** **"Unable to authenticate" or connection timeout** The connector cannot authenticate with your server. Check: * The private key is in valid PEM format with the correct begin/end tags * The public key is present in the user's `~/.ssh/authorized_keys` on the server * The server's `sshd_config` has `PubkeyAuthentication` enabled **"Connection refused" or cannot reach the server** The connector cannot establish a connection. Check: * The SFTP server is running and listening on the configured port * UbiQuity's IP ranges are allowlisted in your firewall — contact support for the current ranges * The hostname resolves correctly via DNS (IP addresses are not supported) * The port configured in UbiQuity matches the server **"Permission denied" on file operations** Authentication succeeded but the connector cannot read or write files. Check: * The user has read and write access to the base path directory * Directory ownership and permissions are correct (`ls -la /path/to/directory`) * If SELinux or AppArmor is in use, review its logs for blocked operations * If a chroot is configured, confirm it includes the target directory **No files found for processing** * Confirm files exist in the configured base path * Verify the file pattern in UbiQuity matches your file naming convention (e.g. `*.csv`) * Check the `archive/` directory — previously processed files will have been moved there * Confirm the base path is not set to the root directory **Intermittent connection failures** The connector retries automatically once on a failed connection. If failures persist: * Check server connection limits and timeout settings * Review server logs for connection rejection reasons * Verify network stability between UbiQuity and your server *** ### **Additional configuration** **Credential rotation** To rotate the SSH key pair, generate a new key pair, install the new public key on the server, update the private key in UbiQuity, then remove the old public key from the server's `authorized_keys`. **Data retention** Processed files are retained in the `archive/` subdirectory and failed files in the `error/` subdirectory. Use cron jobs or similar mechanisms to clean up old files. A minimum of 30 days for archive files is recommended for audit purposes. **Hosting options** Your SFTP server can be hosted on-premises, in the cloud (including Azure Blob Storage with SFTP enabled, AWS Transfer Family, or any cloud VM running an SFTP server), or via a managed SFTP provider. The connector works with any standard SFTP server. *** ### **Need help?** If you run into issues during setup, contact our support team at [**support@ubiquity.co.nz**](mailto:support@ubiquity.co.nz) with the following details: * Your SFTP hostname and port * The username configured for the connector (do not send private keys) * Any error messages shown in UbiQuity or your server logs # Preparing Your Files What your files need to look like before you place them in your configured storage location. ### Overview Import Connectors process files automatically, so your files must follow a consistent structure from the start. Most import failures are caused by formatting changes, missing required fields, or structural differences between the sample file used during setup and the files placed in storage. Getting this right upfront avoids the majority of issues. *** ### Supported file formats Connectors support flat files in CSV format only. Your file must: * Be a CSV file * Contain a single header row * Use a consistent delimiter * Match the structure of the sample file uploaded during Connector setup *** ### Header and column structure **Header row** The first row of your file must contain column names. These names are used for field mapping and must remain consistent across all future files. Do not rename header fields after the Connector is activated unless you update the mapping configuration first. **Column consistency** Once a Connector is active, treat the file structure as fixed. Do not: * Add new columns without updating the mapping * Remove mapped columns * Rename columns * Change the delimiter If structural changes are required, update the Connector configuration before uploading the file. *** ### Required fields and data validity Before uploading a file, confirm: * All required fields are present and contain valid values * Data types match expected formats * Date formats are consistent throughout the file * Boolean values use a consistent representation Invalid or missing required data may cause rows to fail during import. See Field Mapping for detailed validation behaviour. *** ### File naming and pattern matching Your file name must match the file pattern configured in your Connector. Patterns support wildcards. For example, if your file pattern is `contacts-*.csv`, valid file names include: * `contacts-2026-02-01.csv` * `contacts-weekly.csv` Files that do not match the pattern will not be processed. *** ### Upload timing Import Connectors scan configured storage locations every five minutes. To avoid errors: * Ensure files are fully uploaded before the next scan cycle * Do not modify a file while it is being processed * Avoid uploading partial or temporary files that match the file pattern For large files, confirm the upload completes before the next scan window. *** ### Handling duplicates If deduplication is configured, duplicate rows will be removed based on the unique identifier defined in your Connector. If deduplication is not configured, duplicate rows will be imported as provided. Be clear on your deduplication strategy before activating the Connector. *** ### Combined Contact and Transactional imports If your Connector imports to both the Contact and Transactional databases: * Ensure the file structure supports both record types * Confirm which fields apply to Contact records and which apply to Transactional records Incorrect structuring may result in skipped or failed rows. *** ### Common mistakes to avoid Most file-related failures come down to the same recurring issues: * Renaming columns after the Connector is activated * Changing the delimiter or file encoding * Uploading incomplete files * Using inconsistent date or boolean formats * Forgetting to create required fields in UbiQuity before uploading # Field Mapping # Monitoring Connectors How to track Connector activity, review run history, and set up notifications. ### Overview Once a Connector is active, it runs automatically. You can monitor activity in three ways: the Connectors dashboard, individual Connector run history, and email notifications. Together these give you visibility into whether your data is being imported or exported as expected. *** ### Connectors dashboard The Connectors dashboard provides a high-level view of all configured Connectors. 📸 *Screenshot of the Connectors dashboard* For each Connector, the dashboard shows: | Column | Description | | -------------------- | --------------------------------------------------------- | | Connector name | The name assigned during setup | | Database | The UbiQuity database the Connector is associated with | | Direction | Whether the Connector is importing or exporting | | Source / Destination | The storage type (SFTP, Azure Blob Storage, or Amazon S3) | | Last run time | When the Connector last ran | | Last status | The outcome of the most recent run | | Active status | Whether the Connector is currently active | *** ### Connector statuses Each run displays one of the following statuses: | Status | Meaning | | --------- | ----------------------------------------------------------------------------- | | Running | The Connector is currently processing a file | | Completed | The run finished successfully. For imports, data has been written to UbiQuity | | Failed | The Connector encountered an error and did not complete | If a run shows **Failed**, select the Connector to open its run history and review the error details. See Troubleshooting for guidance on common errors. *** ### Run history Selecting a Connector from the dashboard opens its run history. The run history shows: * Run name * Status * Start time * End time * Duration You can expand an individual run to see additional detail, including a summary of what was imported or exported during that run. 📸 *Screenshot of a Connector run history* *** ### Email notifications Connectors can send email notifications to recipients you configure during setup. Notifications provide visibility without needing to log in to UbiQuity. **Success notifications** A success email is sent after a Connector completes successfully. For imports, this includes: * File name processed * Total rows processed * Rows inserted * Rows updated * Rows failed * Rows skipped **Failure notifications** If a Connector run fails, a failure notification is sent to configured recipients. The email includes the Connector name, the file involved where applicable, and a summary of the failure. **No-file notifications** You can configure no-file notifications to alert your team if an expected file has not been received within a defined time threshold. This helps catch missing data feeds before they affect campaigns or reporting. *** ### What to do if a Connector fails If a run shows as **Failed**: 1. Open the Connector's run history and review the error message 2. Confirm the file matches the configured file pattern 3. Verify credentials and permissions are still valid 4. Ensure the file was fully uploaded before the next scan cycle If the issue persists, contact support with your account name, Connector name, run time, error message, and file name. See [Troubleshooting](/documentation/data-and-integrations/connectors/troubleshooting) for a full list of common errors and how to resolve them. # Troubleshooting How to identify and resolve common Connector errors. ### Overview If a Connector run fails, the cause is usually one of four things: credentials or permissions, an incorrect file path or pattern, a change in file structure, or an incomplete file upload. This page covers how to diagnose and fix the most common issues. *** ### Check the Connector status Start by going to the Connectors dashboard and reviewing the **Last Status** column. If a Connector shows **Failed**, select it to open its run history and review the error message for that run. 📸 *Screenshot of the Connectors dashboard showing a failed run* *** ### Common connection errors #### **Invalid credentials** **Cause:** Credentials are incorrect, expired, or have been rotated without updating the Connector. Check that: * Credentials are correct and have not expired * Any tokens or secrets that have been rotated are updated in the Connector settings immediately #### **Insufficient permissions** **Cause:** The storage account user or role does not have the required access. Check that: * The account can read and write to the configured location * Access has not been restricted beyond what the Connector requires #### **Incorrect path or prefix** **Cause:** The configured location does not match the actual storage path. Check that: * Folder and container names are correct * File paths are accurate * Casing is correct where the storage type is case-sensitive *** ### Common file errors #### **File does not match file pattern** **Cause:** The file name does not match the pattern configured in the Connector. Check that: * The file name matches the wildcard pattern (for example, `contacts-*.csv`) * The file extension is correct Files that do not match the pattern will not be processed. #### **File structure has changed** **Cause:** Column names were added, removed, or renamed after the Connector was activated. Check that: * The header row matches the original sample file * Column names are unchanged * All required fields are still present If changes to the file structure are needed, update the Connector configuration before uploading the file. #### **Invalid data format** **Cause:** Data types do not match the expected format. Common examples include incorrect date formats, unexpected boolean values, and numeric fields containing text. Review your file against the sample file used during setup and ensure consistency. #### **Partial or incomplete file** **Cause:** The file was not fully uploaded before the Connector's next scan cycle. Check that: * The upload completes before the next five-minute scan window * The file is not being modified during processing *** ### Import-specific issues **No data imported** If a run completes but no data was written to UbiQuity, possible reasons include: * All rows failed validation * Deduplication removed all rows * The file contained only a header row with no data Review the success notification or run summary for row-level counts to identify where rows were dropped. *** ### Export-specific issues **No file generated** If an Export Connector runs but produces no output file, possible reasons include: * The export filter returned no matching records * The scheduled frequency has not yet triggered * The Connector is inactive Check the schedule configuration and confirm the Connector is active. *** ### Preventing common issues Most Connector failures are avoidable. To reduce the likelihood of errors: * Use consistent file naming conventions that match your configured pattern * Avoid changing file structure without updating the Connector mapping first * Rotate credentials carefully and update the Connector immediately after rotating * Use dedicated service accounts rather than personal credentials * Monitor failure notifications so issues are caught early *** ### When to contact support If you cannot resolve the issue, contact support and include: * Your account name * The Connector name * The run time * The error message * The file name, if applicable * The storage type (SFTP, Azure Blob Storage, or Amazon S3) Providing these details upfront will help the support team resolve your issue faster. # Security and Data Handling How Connectors protect your data in transit, at rest, and throughout the integration process. {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} Connectors follow the same security, privacy, and compliance standards as the wider UbiQuity platform. All data transferred through Connectors is encrypted, authenticated, and logged. No data is shared between customer environments. *** ### How Connectors handle data Each Connector runs in an isolated execution environment. Customer jobs and credentials are logically separated, and no persistent external connection is maintained between runs. Key principles: * Each Connector job runs independently and in isolation * Credentials are never shared between customer environments * No data is retained in transit infrastructure after a job completes *** ### Encryption **Data in transit** | Storage type | Encryption | | ---------------------------- | ----------------- | | Amazon S3 | TLS 1.2 or higher | | Microsoft Azure Blob Storage | TLS 1.2 or higher | | SFTP | SSH encryption | **Data at rest** Data processed within UbiQuity is encrypted using AES-256. Credentials and tokens are stored securely and are never viewable in plain text after entry. *** ### Storage ownership and responsibility UbiQuity does not host file storage for Connectors. Responsibility is shared between UbiQuity and your organisation. | Responsibility | Your organisation | UbiQuity | | ---------------------------------------------- | ----------------- | -------- | | Hosting and managing storage | ✓ | | | Controlling access and permissions to storage | ✓ | | | Ensuring data residency compliance | ✓ | | | Securely connecting to your storage location | | ✓ | | Processing data within the platform | | ✓ | | Maintaining platform security and availability | | ✓ | *** ### Access control Access to Connectors within UbiQuity is controlled by user permissions. Only authorised users can view, create, edit, or activate Connectors. Administrative access to production systems is restricted, logged, and reviewed. *** ### Monitoring and audit logging All Connector activity is logged. Within UbiQuity, you can view run history, run status, and timestamps for every Connector. UbiQuity also maintains system-level monitoring and alerting internally to ensure reliability, performance, and security. Logs are retained in line with UbiQuity's auditing and operational policies. *** ### Compliance UbiQuity is certified to ISO/IEC 27001:2022 for its Information Security Management System. Connectors operate under the same governance, controls, and secure development practices as the wider platform. Security measures include regular vulnerability scanning, penetration testing, controlled deployment processes, and continuous monitoring and incident response procedures. *** ### Best practices To maintain a strong security posture for your Connectors: * Use dedicated service accounts rather than personal credentials * Prefer SSH keys over passwords for SFTP connections * Rotate access keys and tokens regularly, and update the Connector immediately after rotating * Restrict credentials to the specific folders or containers required — avoid granting broad storage access * Disable unused Connectors and revoke associated credentials promptly # FAQs Common questions about how Connectors work, including scheduling, billing, and file handling. {% hint style="info" %} CONNECTORS ARE COMING AUGUST 2026 {% endhint %} This page answers the most common questions about Connectors. For troubleshooting failed runs, see Troubleshooting. For security and compliance questions, see Security and Data Handling. *** ### How often do Import Connectors run? Import Connectors scan configured storage locations automatically every five minutes. If a matching file is found, it is picked up and processed. No manual trigger is required. *** ### How often do Export Connectors run? Export Connectors run on a schedule you configure during setup. Available frequencies are every 10 minutes, hourly, daily, weekly, or monthly. *** ### Can I run a Connector manually? No. Connectors run automatically based on their configuration and cannot be triggered manually. Import Connectors scan configured storage locations every five minutes. If a matching file is present, it will be picked up and processed in the next scan cycle — so there is no need to trigger a run manually. Export Connectors run on the schedule you configured during setup, which can be set to every 10 minutes, hourly, daily, weekly, or monthly. If you need to change how often an Export Connector runs, update the schedule in the Connector settings. If you need to reprocess data outside of the normal cycle, upload a new file that matches the configured file pattern and it will be picked up at the next scan. *** ### Can I deactivate a Connector? Yes. Use the Active toggle in the Connectors dashboard to deactivate a Connector at any time. When inactive, the Connector will not run. Note that you cannot pause a Connector that is currently running. *** ### What happens if no matching file is found? If no file matches the configured file pattern, the Connector will not process anything. You can configure no-file notifications to alert your team if an expected file has not been received within a defined time threshold. *** ### What happens if a Connector fails? The run will show a status of **Failed** in the dashboard, and a failure notification will be sent to configured recipients. Open the Connector's run history to review the error message and identify the cause. See [Troubleshooting](/documentation/data-and-integrations/connectors/troubleshooting) for common failure scenarios. *** ### Can I change the file structure after a Connector is activated? Not without updating the Connector first. If you need to add, remove, or rename columns, update the Connector configuration before uploading a new file. Connectors expect a consistent file structure once activated. *** ### Does UbiQuity host my storage? No. Your organisation must host and manage its own SFTP server, Azure Blob container, or Amazon S3 bucket. UbiQuity connects securely to your environment but does not provision or manage storage on your behalf. *** ### How is billing handled? Connectors are billed monthly, per Connector. Billing begins when a Connector is activated and is charged for the full month — partial months are not prorated. If you deactivate a Connector during the month, the full monthly charge still applies for that billing period. See the [UbiQuity pricing page](https://www.ubiquity.co.nz/platform/connectors#pricing) for current pricing. *** ### Are Connectors secure? Yes. Connectors follow the same security and compliance standards as the wider UbiQuity platform. All data is encrypted in transit and at rest, access is permission-controlled, and all Connector activity is logged. UbiQuity is certified to ISO/IEC 27001:2022. See [Security and Data Handling](/documentation/data-and-integrations/connectors/security-and-data-handling) for full details. --- [Next Page](/llms-full.txt/1)