Onboarding: Forms

Mautic customers use forms for lead generation and data collection. With Mautic forms, marketers can convert anonymous web visitors to known contacts and build a contact’s profile with progressive profiling. The more data you can gather without coming off as intrusive or annoying, the more effective your personalization strategy will be.

Form Types
General Options
Form Details
Form Fields

Form Actions
Adding Forms to Pages

To create a new form, go to Forms (under the Components section in the left side panel) and click +New.

Form Types

Form Types

Campaign Form: Used to immediately trigger a campaign on submission. There are fewer form submit actions (actions that happen after a contact submits a form) directly associated with Campaign forms, because most actions would be triggered as part of the campaign that the form triggers.

Standalone Form: Used for more generic data collection, and the more commonly used of the two form types. It’s still possible to trigger a campaign based on Standalone Form submissions. To do that, use form submit actions to add contacts to a segment and use that segment as the contact source for a campaign,

General Options
Form Options

Category: You can organize your forms based on their goals, campaigns, etc. Learn more about categories in our Global Categories help center topic.

Publish options: The Yes/No toggle is the fastest way to publish or unpublish a form. If a form is unpublished, it won’t be visible on pages you’ve added the form to using Javascript. If you used the manual copy and pasted the HTML code onto your page, the form will still be visible but not submittable. Contacts will see an error message if they attempt to submit the form.

Disable search indexingTo prevent search engines like Google, Bing, Yahoo, etc. from being able to find and display the form in search results for related topics, change this to yes.

Kiosk Mode: Setting this to Yes turns off tracking, and prevents Mautic from generating new cookies or attaching the IP address to the contact record. This may also be referred to as data entry mode. An example of this would be at an event, where several different contacts may enter their information using the same device. Kiosk mode will avoid having all of the activity on that device tied to one contact.

Render Style: When set to Yes, the form will appear on your page or application with the styling either from the selected theme or styling from the Attributes tab of a field editor. When set to No, the form will adopt the CSS of your page or application.

Theme: The selected theme will dictate the styling of your form when it’s added to an external page or application, if Render Style is set to Yes. Note: Not all themes include form styling. Check the “Features” column on your Themes page (in Settings) too see which available themes include CSS for forms.

Form Details

Form Details

Name: Title your form, including any terms you may want to use to search for the form.

Description: Add a description, so other users can easily see what the goal of the form is. It may help to include information like the creation date and any pages where the form appears.

Successful Submit Action: Options include Remain at form (nothing appears to happen), Redirect URL (directs the contact to another page, such as a thank you page, after submission), and Display message (shows a simple message above the form once the contact has submitted the form).

Redirect URL/Message: If you decide to use the Redirect URL successful submit action, paste the address you’d like submitters to be directed to here. If you decide to use Display message, enter the message you’d like to display.

Form Fields

Form Fields

Field Types

Choosing the proper field type not only helps Mautic users gather data appropriately on forms, but it can optimize the end-user’s experience of completing the form. Particularly on mobile devices, certain form fields may appear differently and the wrong field type may result in a more difficult submission – and potentially lost conversions.

To add a new field, click the “Add a new field” dropdown and select the field type you’d like to add. Once you’ve selected that, you’ll enter more information about the field.

Captcha: This is a very basic form of spam protection, either requiring a human to submit an answer or identifying when spambots attempt to submit data in a hidden Captcha field (honeypot). We recommend using some form of Captcha on every form. Mautic also supports reCAPTCHA v2, which you’ll see as an additional field type after setting up the reCAPTCHA plugin.

Checkbox Group: Enables a contact to select multiple options from a list, using checkboxes. Commonly, Mautic customers also use the Checkbox for a single option on opt-in forms to gain consent to use cookies and send marketing emails or other messages to the contact.

Date: Validates date fields in your default date format, and improves the end-user experience when completing the form. In a web browser on a laptop or desktop, the field shows selectors for month, day, and year. On mobile devices, a calendar will appear.

Date/time: Similar to the date field, but an additional selector will appear for time.

Description area: A basic header field, most commonly used to give the form a visible title on the page. The Header field acts as the field name/label, and the description area (in the Properties tab) is a free text editor where you can add a description of the form. Of course, you can also achieve this by adding text around the form on your page, but if you’re using the same form on several pages or applications it will likely be easier for you to add the description on the form.

Email: Requires that the field contains an email address with the proper syntax – name@domain.com. Because this is the default unique identifier, we recommend having a required Email field on your forms.

File: Allows contacts to upload files with the form.

Hidden: A field that won’t display with the form. Users may add default values to save with the form for reporting or internal tagging purposes.

HTML area: Enables marketers to add custom code into their forms.

List – Country: Populates Mautic’s default country list. This is not editable. To use custom list, you’ll need to use a Select field type and manually enter the options for the countries you’d like to appear on the list.

Number: Validates that the entered values are digits. Decimals and negatives are allowed, but no other non-numerical values (including commas) may be entered. On mobile devices, the keyboard will change to a number pad when a contact selects this field to complete.

Page break: Enables marketers to break up the form into multiple pages, or field groupings.

Password: Allows contacts to create a password, generally used if the form is used to create an account and the results are posted to another form/system. This entered field value should almost never be saved, because it will be saved in plain text on the contact record.

Phone: Similar to the number field, but this automatically maps to the Phone field and has an option to validate as international format. That validation requires a dialing code (for example, +1 for the United States or +44 for the United Kingdom).

Radio Group: Give contacts a list of options, from which they can select one with a radio button. This may also be called an option button group.

Select: Displays as a drop-down/pick-list, where a contact may choose one option. You may also choose to allow multiple selections, which will change the display to a box with the options listed. On mobile devices, a single selection will appear as a modal with radio buttons and multiple selections allowed will appear in a modal with checkboxes.

Social Login: Connects a contact’s Twitter, Facebook, and/or LinkedIn profiles with the Mautic contact record.

Text: The most common field type, this is free-form text with a limit of 255 characters. Common fields such as first name, last name, position/job title, city, etc. are generally built as text fields.

Textarea: A longer-form text field, this field has a maximum character limit of 65,535 characters.

URL: Validates that the entry must be a URL, including https:// or http://.

Field Editor


Field Editor - General

Label: The title of your field – telling the contact what you’d like them to enter in that field. The label displays above the form field by default.

Show label?: If set to no, the label will not display on the form.

Save result: If set to no, Mautic won’t save the data entered in the list of form submission results. However, if you map the field to a contact field, Mautic will still save the data to the contact record.

Default value: In case the contact does not submit data for the field, you may enter a default value to be submitted with the form. This is particularly useful for hidden fields and reporting.

Help message: If you’d like to keep the label short but add a little bit more detail on what you’d like a contact to enter, enter a custom help message.

Input placeholder: Adds text within the form field, generally acting as a label or help message.

Here’s how these options display for a basic text field (styling is from a “Fresh” landing page theme).

Contact Field

Forms - Contact Field

The Contact Field tab is where you’ll map the form field to where you want the data to save on a contact or company record. Without a field mapped here, the data won’t be saved to the contact record. The data type you choose for the form field should match the data type for the Mautic field. For example, a date and time form field should map to a date and time custom field (or standard field). Checkbox group form fields work well with Select – Multiple Mautic fields, and Radio Group or Select form fields work well with BooleanSelect, or Select – Multiple Mautic fields.


Forms - Validation

Required: Determines if the form field must be populated on submission. Making a field required means Mautic will not accept form submissions without data in the field. Labels for required fields will have an asterisk next to them to indicate that they are required.

Validation message: This will appear if a contact attempts to submit a form without data in a required field. “This is required.” is Mautic’s default validation message. To change that, enter your custom message in this box.


This tab does not appear on all field types, and different field types have different properties options.


Forms - Captcha - Properties

Captcha answer: To use the Captcha field as a honeypot, leave the Captcha answer field blank. This will hide the field, and spambots will try to populate the field with data. However, Mautic will recognize that if there’s data in a honeypot Captcha field, it can’t be a human submitting the form. To have a human actually answer a basic question or statement, e.g. What is 2+2? or Enter “Captcha”, enter the expected response in the Captcha answer box. In these cases, 4 or Captcha would be the answers. The field’s Label should be your question, or you may simply label the field Captcha and use the input placeholder, depending on your preference for the form’s appearance.

Custom error message: If a human enters an incorrect Captcha answer, an error message will appear on submission. Mautic’s default error message is The answer to “{label}” is incorrect. Please try again.” You may enter a custom message here to be used instead.

Checkbox Group, Radio Group, and Select

Forms - Checkbox Group - Properties

This is where you’ll enter the options a contact will select from.

Use assigned contact/company field’s list choices: If you’ve mapped the form field to a Mautic field that has a pre-set option list (in the Custom Field setup), you may simply use those options and not have to re-create them on the form.

Optionlist: If you’re not using the assigned options from a contact or a company field, set up the potential options here. The Label field is how the option will display on the form. The Value is how the data will be stored on the contact record & in the database. The Label and Value often match, but not always. As an example, if you’re using a checkbox field for GDPR opt-ins, your label may say something like “Yes, I accept that I may receive email communications from this company.” However, your value might be a “Yes” or “1” as a positive boolean value.

Empty Value (on Select only): This serves the same purpose as an Input Placeholder, which is available on most other field types. The Empty Value is not a default value, and Mautic will not save this value to the contact record.

Allow Multiple (on Select only): This option transforms the field from its default Select field type into a Select – Multiple field type.

Description Area

Forms - Description Area - Properties

If there’s any information you’d like to be displayed with the form, you may use the Description Area field. Often, users will add this kind of information on the webpage, landing page, or application separately from the form, but it is an option in the form builder.


Forms - File - Properties

Allowed file extensions: By default, Mautic accepts the following file types: csv,doc,docx,epub,gif,jpg,jpeg,mpg,mpeg,mp3,mp4,odt,odp,ods,pdf,png,ppt,pptx,tif,tiff,txt,xls,xlsx,wav,zip. To not allow some file types for the form field, delete those extensions here.

Maximum size (MB): The maximum size Mautic allows for uploads is 100MB. You may restrict users to uploading smaller files by reducing the file size here.

Public accessible link to download: When a contact uploads a file on a form, the Mautic saves the file as a link. Setting this to Yes enables anyone to download the originally uploaded file by visiting that link. Setting this to No means that anyone not logged into the Mautic instance may not download any files uploaded through this form field.


Forms - HTML Area - Properties

Add code you’d like to include in an HTML field here.

List – Country

Forms - Country List - Properties

Empty Value: This serves the same purpose as an Input Placeholder, which is available on most other field types. The Empty Value is not a default value, and Mautic will not save this value to the contact record.

Allow Multiple: This option transforms the field from its default Select field type into a Select – Multiple field type.

Note: Mautic’s Country field is based on a pre-defined list which is not editable by users. To edit the list’s options, create a Select field and manually enter the options for your custom country list.

Page Break

Forms - Page Break - Properties

Next page button label: This is the text that appears on the button which contacts will click to get to the next page, or next set of questions on the form. This is not a submit button and will not save any data, just a button to move forward in the form.

Previous page button label: This may apply if you’re already on a 2nd (or more) page and would like to give contacts an option to go back to the previous page. It is also not a submit button, just a button to move backward in the form.


Attributes are CSS tags to change the styling of a particular form. Remember, if you set Render Style to no on the form, these attributes will be ignored.

Forms - Attributes

Field HTML name: The machine name for the field. Mautic will automatically populate this based on the label, but you may want to customize it particularly if the label is long. Generally, you’ll only need to reference the HTML name when you’re connecting Mautic forms to other forms or when you’re using the Manual Copy function to manually add the form to your page or application.

Label attributes: Changes the way the label text appears. Use the format style=”attribute: descriptor” to change the style. For example, to change the label to red, use style=”color: red” or style=”color: #ff0000″.

Input attributes: Changes the way any text inside the form field appears. This may apply to the input placeholder text, text entered by the person submitting the form, and/or the options for select fields when Allow Multiple is set to yes (including List – Country).

Field container attributes: Changes the form field itself. You may want to change the size of the box, fill color, rounded edges, or any of several other properties about the actual field.

Radio/checkbox label attributes: Where available, this changes the way options on radio buttons or checkbox groups appear, similarly to the input attributes.


Forms - Behavior

This tab helps marketers improve the experience for the contact completing the form. It also helps marketers implement progressive profiling, to gather more data from the contact which helps in optimized personalization.

Show when value exists: If the contact is known and tracked and a value for the field exists on the contact’s record, Mautic can hide the field. To do that, set this option to No. Marketers may want to do this so they are not asking the same question over and over again. However, marketers may want to show the question repeatedly to ensure the contact is entering the most up-to-date information. We recommend always keeping the unique identifier (most commonly the email address) shown.

Show after X submissions: This is the key to progressive profiling. If you’re using the same form multiple places on your site, you may want to change the fields the contact sees each time they see the form. Entering a value in this field will hide the field until the contact has submitted the same form that number of times. This can go anywhere from 1 to 200. When left blank, the field will appear every time the contact sees the form. Generally, the goal of this is to shorten the form so you’ll want to use it in conjunction with hiding fields when values exist.

Auto fill data: If the contact is known and tracked and a value for the field exists on the contact’s record, Mautic can pre-populate that data. Note that this only works with Mautic landing pages, and data will not pre-populate when the form is placed anywhere else. Even if you’re hiding this field, you may want to turn auto-fill on so the result is saved with the form submission.

Field Order

To change the order of the fields on your form, click on the field you’d like to move and drag it to the place you’d like it to go.

Form Actions

Once a contact has submitted a form, you may want to have a few things happen. These could include communications with your contact, tracking, internal notification, or other lead management. In fact, you may want to do all of the above (and more!).

All of the Form Actions that are available on Campaign forms are also available on Standalone forms. The actions available on both are marked with an asterisk (*).

Add to company’s score: If the contact who submitted the form is associated with a Company record in Mautic, you may add points to that Company’s overall score. Company scoring in Mautic does not aggregate points for all of its associated contacts. As a result, any actions you’d like to contribute to a company’s score must be explicitly said to do so. Negative numbers are valid if you’d like to subtract from a company’s score based on a contact submitting the form. If the contact has not been previously tracked and the form doesn’t include a field mapped to Company (on the contact object) or Company Name (on the Company object), no points will be awarded to a Company.

Form Action - Company Score

Adjust contact’s points: A little bit more in depth than the company score action, this action allows you to multiply or divide a contact’s score. Select the operator and the amount you’d like to change the points by (i.e. add 10, subtract 5, multiply by 3, divide by 2). If the form is collecting information that doesn’t identify the contact, Mautic will save the points to the anonymous contact record. If that anonymous contact record is later converted to or merged with a known contact record based on some identifying event (form submission with the unique identifier or link click in a message), the points will stay with the contact.

Form Action - Adjust Contact's Points

Modify contact’s segments: This action enables users to change a contact’s segment membership when they submit a form.  Type in the name of the segment you’d like to add a contact to or remove a contact from. You may use both fields in one Action, and may include multiple segments in either or both fields. Remember, dynamic segments based on filters will automatically update based on information on the contact record. That includes the data from the form submission, as long as the fields are mapped to Contact or Company fields. Typically, you’ll only want to use static segments here. However, an example of a time when you might remove someone from a dynamic segment is for an event registration. You may have built a filter-based segment for your invitation campaign, but once a contact submits the registration form you want to remove them from the source segment so they’ll be removed from the invitation campaign.

Form Action - Modify Contact Segments

*Modify contact’s tags: If you use tags for tracking, segmentation, and reporting, you may add or remove tags based on a form submission. If you’d like to add or remove a tag that you’ve previously used, select that tag from the list that will appear when you click into the field. To help you find a tag, start typing the name to search and shorten the list. If you’re adding a new tag, type the full tag name and press Enter/Return on your keyboard to save the tag.

Form Action - Modify Contact Tags

Record UTM Tags: If the page your form is on has UTM tags, whether it’s a Mautic landing page or not, Mautic can record those UTM tags to the contact record. This is useful for reporting on where your new leads and form submissions are coming from.

Form Action - Record UTM Tags

*Remove contact from do not contact list: If a contact has previously unsubscribed and this form gives you permission to send them emails again, you may use this action to remove the Do Not Contact designation.

Form Action - Remove from DNC

*Download an asset: Using this option triggers an asset download as soon as the contact clicks the submit button. If you use categories to organize your assets and want the contact to receive the most recently published asset from a certain category, choose that option then choose the category to download from. Or, choose a specific asset to be downloaded. For more information on assets, visit our Assets documentation.

Form Action - Download Asset

*Post results to another form: If you need to connect your Mautic form with some other form, use this option. You may also have forms in other tools that you use for tracking and reporting. Or, you may have back end forms that trigger software instance creation. Enter the URL for where the form should post to, as well as email address(es) for anyone who should receive error notifications. If the form you’re posting to is behind a firewall, also enter the authorization header. Finally, if the field aliases (machine names) for any of the fields don’t match, enter the alias the other form uses for any fields on the Mautic form.

Form Actions - Post Results

Push contact to integration: Once a contact as submitted the form, you may want to push them to another piece of software you’re using for contact management (such as a CRM). Be sure the plugin you want to push contacts is properly configured and published, then select it here. The Salesforce plugin enables users to select a campaign and a campaign status, beyond a basic push to Salesforce.

Form Actions - Push to Integration

Send email to contact: To directly email the contact after they’ve submitted a form, use this option. You’ll need to use a Template email – either select it from the list, or click the +New Email button to build a new one. Once you’ve selected an email, you can also pop open a new window to make edits or just to preview the email.

Form Action - Email Contact

*Send email to user: To email an internal user after a contact submits a form, use this option. This is limited to only people who have been set up as Mautic users. Similarly to the previous option, select the Template email you’d like to use or create a new one. Any tokens in the email will display the data from the contact, not the user.

Form Action - Email User

*Send form results: This is most commonly used to send an internal notification that a contact has submitted a form. However, you may also use it to send a confirmation of the submission to the contact, with the data that the contact entered. You’ll want to make the subject line clear which form the submission is for, particularly if you have several forms with the results going to the same person or people. The Reply to contact option automatically sets the reply-to address on a notification email to the contact’s address, so if you click reply on the email your recipient will be the contact. If you have contact owners assigned in Mautic, you can send the notification directly to the submitter’s owner. You may also decide to send the email directly to the contact.

You may style the message section as you’d like. The tokens for the fields will automatically populate for any fields that exist when you add this action. If you later make changes to the fields, you’ll want to come back to this action and re-enter the field tokens. To do that, you can simply click the field name on the right side and Mautic will automatically insert the token where your cursor is in the Message box.

If instead of using the basic form results template you’d like to use a Template email, you may select one from the Import from an existing template box. Finally, add the addresses for the people you’d like to receive the form results. Unlike the Send email to user action, Send form results emails are not limited to Mautic users. You may send these to internal employees who aren’t users, 3rd parties, or to distribution lists.

Form Action - Send Form Results

Form Action - Send Form Results P2

Adding Forms to Pages

Form Code

There are a few different ways to add form code to your web page or application.


If you’re adding a form to a Mautic landing page or a Drupal, Joomla!, or WordPress page, you can just use a shortcode. In each of these cases, replace ID# with the forms ID number. You can find this in the forms list in the far right column, or if you’re on the form, it’s the number at the end of the URL. All of these options use Javascript, and will keep the form up to date automatically as you make changes.

Mautic Landing Page: {form=ID#}

Drupal 7.x: {mauticform id=ID# width=300px height=300px}. Be sure to change the width and height to the appropriate sizes for the space you’d like the form to appear in.

Note: This shortcode does not work for Drupal 8.x. We recommend using the Automatic Copy option below instead.

Joomla!: {mauticform ID#}

WordPress: Note: Replace the parentheses with square brackets. (mautic type=”form” id=ID#)

Automatic Copy

Forms - Automatic Copy

The Automatic option keeps your forms updated wherever you use this code. If you make changes to the form in your Mautic instance, you don’t need to worry about re-copying the code everywhere the form appears on your site. Features like auto-fill and progressive profiling will work only with the automatic copy options, not with manual copy.

First, if you have a custom domain for your instance, be sure you’re logged in using the custom domain rather than subdomain.mautic.net. 

Via Javascript: Other than shortcodes, this is the recommended way to add forms to pages. Copy the line of code in the box and paste it into your site where you’d like the form to appear.

Via iframe: While there may be cases where using an iframe is preferred for page load time or styling, iframes can be more difficult to manage. Be sure to adjust the width and height for the space you’d like the form to be in. Depending on the size of the screen your contact is using, they may still need to scroll within the iframe on your page to see all of the fields. You may enter a custom error message to appear in place of the form, in case the contact’s browser does not support iframes. To do so, edit the text between the <p> and </p> tags before copying the code and pasting it on your site where the form should appear.

Manual Copy

Forms - Manual Copy

The Manual copy option gives you a little bit more flexibility to extend forms with Javascript snippets and custom styling. It is, however, more manual, and any changes made to the form won’t appear on your page unless you re-copy and paste the HTML code.

Once again, be sure you’re logged into your instance using your custom domain, if you have one.

First, copy the Javascript code in the top box and paste it into the head or body of your page. If you’ll have multiple Mautic forms on the same page, you only need to add this once.

Next, copy the HTML code in the bottom box and paste it where you’d like the form to appear on your page. If you have Render Style set to Yes in the form editor, the styling for each field will be included in this code. If Render Style = No, styling code will not be included and the form will use the default CSS for your page.

If you’re a Mautic Cloud customer and have further questions about forms, please email support@mautic.com.