Mailing links custom tracker

This extension allows replacing links in Outreach outbound emails with links provided by your service. Links your service provide are expected to eventually redirect to the original link. Outreach will call the registered URL of your service and provide a list of links from the email in the payload expecting to collect the list of replacement links to be inserted back into the email.

Expect traffic!

Note that on busy customers the traffic rate may become high, thus you should ensure your service can handle that type of load. If your service becomes unavailable or fails to respond to the request the email will be sent with the set of original links and the operation will not be retried.

Only http:// and https:// links are offered for replacement (other links e.g. mailto:// are filtered out).

Configuring mailing links custom tracker extension

Add the "Mailing clicks custom tracker" feature to your app.

Custom link tracker extension

Then configure your service URL and optional filter for links to be sent for replacement.

Custom link tracker extension configuration

In case the filter is empty the service will receive all http:// and https:// links present in the email for replacement. Otherwise only links that match a specified regular expression will be included into payload. Outreach uses Perl Compatible Regular Expressions syntax.

There is a tester tool present at the configuration page for convenience. It is recommended to verify that the filter is correctly specified before saving the Mailing links custom tracker configuration by testing it against a sample link value that would be present in the emails.

Request payload format

Before sending out the email Outreach will iterate over applications with the Mailing links custom tracker installed for the organization and make an HTTP POST request to each service URL with the following payload:

Copy

Copied

{
  "data": [
    "https://bit.ly/33zYFqH",
    "https://yhoo.it/35tPtX6"
  ],
  "meta": {
    "mailing": {
      "id": "123"
    },
    "prospect": {
      "email": "abc@prospect.com",
      "id": "456"
    },
    "user": {
      "email": "def@user.com",
      "id": "789"
    },
    "urls": {
      "https://www.google.com/": "https://bit.ly/33zYFqH",
      "https://www.yahoo.com/": "https://yhoo.it/35tPtX6"
    }
  }
}

The data array constains either the original links present in the outgoing email or their replacements as per responses from the services that were called before.

The meta/urls object complements the data values by providing a mapping between original links extracted from the email to their most recent replacements.

Please note that the regular expression filter is applied to the original links and not their replacement values. In case an organization has multiple applications with Mailing links custom tracker installed the order of the services being called is not deterministic and can not be relied on.

The meta/mailing, meta/prospect and meta/user objects provide information about the outgoing email.

Request origin verification

Every mailing links request will contain the Outreach-Webhook-Signature header. Use this header to validate that the request came from Outreach. The signature generation process is described in application lifecycle webhooks. The secret used to sign mailing links extension payload is the same as for webhook requests.

Response format

The mailing links extension service is expected to respond with the following JSON:

Copy

Copied

{
  "data" : {
    "https://bit.ly/33zYFqH" : "https://example.com/aX2",
    "https://yhoo.it/35tPtX6" : "https://example.com/fsr"
  }
}

Note that you have to use the values from the data array as keys for response data object. Outreach will only replace URLs that are mapped to valid HTTP(S) URLs; missing or invalid URLs will be left untouched.

Service requirements

Outreach gives each mailing links extenion service 2 seconds to respond with valid JSON and it does not retry on any kind of failure.