How to use the URL mapping tool to redirect pages

Last updated: September 22, 2016

Available For:

Product: HubSpot Marketing
Subscription: Basic, Professional, & Enterprise
Add-Ons: Website

Whenever you change the URL of a page or post built with HubSpot, the software automatically sets up a 301 redirect from the original URL to the updated URL.

For example, if you have a page called and you change the URL of that page to in the Site Pages content editor, when a visitor goes to they will be automatically 301 redirected to These automatic 301 redirects ensure that your visitors always reach the intended page, even when the URL has changed. You can also manually set up 301 redirects using the URL mapping tool in Content Settings.

Follow these instructions to set up a manual URL mapping on the COS. 

Whenever a site is migrated to the HubSpot COS, the HubSpot migration team maps every old page on your site to a corresponding page on the new site, or to the home page.

Go to the URL mappings tool

From your HubSpot Dashboard, navigate to Content > Content Settings.

HubSpot Help article screenshot

Click on COS URL Mappings in the Content Options side menu.

HubSpot Help article screenshot

Click Add a new URL mappings

Click the Add a new redirect button.

HubSpot Help article screenshot

Choose single or bulk mappings

COS URL Mappings allow you to add a single mapping or add many mappings at once. Click Add one redirect to add a single URL mapping.

An explanation of bulk URL mappings is explained below.

HubSpot Help article screenshot

You will then see the Add a new URL mapping window pop-up to place your information.

HubSpot Help article screenshot

Set the original URL or path

Type in the original URL or path that you want to redirect traffic from. A sample absolute URL might be, and a sample relative URL path that would also redirect traffic to that page would be /page.

Please note: it is not possible to redirect a file hosted on the HubSpot COS File Manager. Because of the way those files are hosted, a URL mapping will not work. Instead, an alternative to deleting an old file would be to replace it with an updated version.

HubSpot Help article screenshot

Set the destination URL or path

Type in the destination URL or path to redirect the original URL or path's traffic to. A sample URL might be, and a path that would also redirect traffic to that page would be /new-page.

Please note: When entering a destination URL of an external website page that is not hosted on HubSpot, be sure to include the entire URL such as

HubSpot Help article screenshot

If you use a relative URL path and have multiple domains connected to HubSpot's COS tools, the mapping will work across all connected subdomains. For example, if is set to be your primary domain for your COS blog, and is set to be your primary domain for your Site Pages, the relative URL example above redirect would redirect to and to, respectively depending on which url the user had entered.

The COS URL Mappings tool can redirect any primary COS domain connected in Content Settings > Domain Manager. It cannot redirect domains associated with external sites. Your destination URL, however, can be any URL you want (whether or not you own the domain is irrelevant).

You can only set up redirects for secondary COS domains with an Enterprise account.

Add URL Mapping

After selecting the appropriate settings (explained in detail below), click Add URL Mapping.

HubSpot Help article screenshot

URL Mapping Settings

HubSpot will automatically attempt to select the appropriate mapping settings, based on what you enter as the original and the destination URL. In addition, you can click Show Advanced Options which will provide you with more options for your new redirect.

HubSpot Help article screenshot

Here are the following options you can consider manually configuring:

Redirected URLs should match original URL's query string, or lack thereof

Select this option if you wish for the mapping to function only when the Original URL and its query string is entered on a browser's address bar. In other words, when this option is selected, the redirect will only occur if the page, along with the query string, is entered. If the same page URL is entered in a browser's address bar without the exact query string, the mapping will not redirect.

HubSpot Help article screenshot

Ignore this URL mapping if a page exists at the requested URL

Check this option to only redirect the URL if a there is not an existing page at that URL. This will let you temporarily redirect a URL until you finish building out a replacement page and then automatically disable the redirect when you publish a page on that URL. This option is also useful for a designer or IT person, setting up a site for internal end users. If a page/post is later created and falls under a pattern-based mapping, if this option were checked, it would no longer redirect that content once that page/post was published. Unchecking this option will make the redirect always take effect, even if there is a page at this URL in your HubSpot account. This option marks the priority of the URL mapping with post.

HubSpot Help article screenshot

Advanced: Original URL is a flexible pattern URL

If you migrated to HubSpot from another CMS, your old site's URLs may follow a particular pattern, and rather than mapping all the individual URLs, you can use a pattern-based mappings to dynamically redirect those pages to their corresponding HubSpot URLs.

In the example below, each of the components of the url is given a name, using a colon (:).  The portion that starts with an asterisk (*) creates a named component that is matched until the end of the URL (before the query string). You then add those same component names, wrapped in braces {} to wherever you would like those components to render in the destination URL. The tool automatically displays the names of the components that you have entered in the original URL, below the destination URL.

HubSpot Help article screenshot

In the example depicted above, a URL such as redirects to

To learn more about flexible pattern mappings, click here.

Redirect requests with or without a trailing slash

This option will be automatically checked off for any new redirect you add.

HubSpot Help article screenshot

Redirect requests regardless of protocol (either http or https)

This option will be automatically checked off for any new redirect you add.

HubSpot Help article screenshot

Redirect Type

The redirect type option allows you to choose whether you want this redirect to be a permanent (301) redirect or a temporary (302) redirect. Search engines handle these two types of redirects differently. A 301 redirect should tell a search engine that a page has been permanently move to a new location, and to index the new page accordingly. A 302 redirect should tell a search engine that the original page still exists, and to continue to index it. Unless you have a specific reason that your webmaster wants to use a Temporary (302) redirect, you should always choose Permanent (301).

HubSpot Help article screenshot

Managing your URL Mappings

In addition to creating mappings, the COS URL mappings tool has several other features to help you manage your existing mappings.

Bulk add redirects

You can add multiple URL mappings at once, by clicking the Bulk add redirects button.

HubSpot Help article screenshot

Each URL mapping should be on its own line and consists of a source and destination URL or path, separated by a separator. The default separator is a comma, but you can can set a custom separator of your very own. You can also choose have these mappings override existing mappings that share the same original URL by choosing Update existing mapping with new destination in case of conflict. When you're done adding multiple URL mappings, click the Add URL Mappings button to finish up.

HubSpot Help article screenshot

Export URL mappings

You can export URL mappings into a .csv file by clicking on the Export Mappings button.

HubSpot Help article screenshot

Download the .csv file to view the URL mappings in a spreadsheet. Click on the link of the file in the downloads section of your browser.

HubSpot Help article screenshot

Now you can see all of your URL mappings in one place.

HubSpot Help article screenshot

Search for a URL mapping

You can use the search box to quickly search for a URL mapping.

HubSpot Help article screenshot

System versus manual mappings

System mappings are redirects that HubSpot has automatically created for you. These mappings are visible in COS URL Mappings, so your webmaster can keep track of all of the redirects that are taking place, with regards to your HubSpot content. Manual mappings are redirects that you have created through the COS URL Mappings tool or by changing the URL of a page within the content editor. For example, if you change the URL of your blog or of a particular page in the content editor, HubSpot sets up those mappings for you and labels the as created by Manual.

HubSpot Help article screenshot

Edit a URL mapping

You can edit an existing URL mapping by clicking on the gear icon and choosing Edit.

HubSpot Help article screenshot

Delete a URL mapping

You can remove a URL mapping by clicking on the gear icon and choosing Delete. This will permanently disable the redirection and you will have to add a new URL mapping, if you want to restore that redirect.

HubSpot Help article screenshot

Change priority of a URL mapping

You can adjust the priority of a URL mapping by clicking on the gear icon and choosing Change priority option.

HubSpot Help article screenshot

Here, you can enter a new priority for the mapping. When multiple mappings apply to the same URL, the mappings with lower priorities take precedence over higher priority. For example, a mapping with a priority of 1 will override a mapping with a priority of 2. You can also choose to make this mapping only apply when a page does not exist at that URL (this is the same option that you have access to when editing a mapping).

HubSpot Help article screenshot

Mappings that only take effect when the page does not exist will display post next to their priority.

HubSpot Help article screenshot

Was this article helpful?

Previous article:

Measuring Your Performance Project

Next article: