GreenArrow Email Software Documentation

Link Replacements API

Overview

Link Replacements provide a mechanism for modifying the destination and/or expiration of a SimpleMH link after the email has been sent.

Link Replacements are performed at the time of the click. The purpose of this is to allow links with mistakes in them to be fixed, or to shut down links that are being abused.

Attributes

The following are the configurable attributes defined for Link Replacements.

link_replacement

hash

/

required
id

integer

/

read-only

A unique automatically generated identifier.
mailclass

hash

/

optional

When configured, this link replacement will only affect clicks associated with the specified Mail Class. The comparison is made case-insensitively.

If a Mail Class is set for a Link Replacement, and that Mail Class is deleted, the Link Replacement will be deleted as well. Link Replacements associated with a specific Mail Class do not appear on that Mail Class’s “References to This Mail Class” table.

id

integer

The unique identifier of the Mail Class.
name

string

The unique name of the Mail Class.
instanceid

string

/

optional

When configured, this link replacement will only affect clicks associated with the specified InstanceID. The comparison is made case-insensitively.

In order to specify instanceid, mailclass must be set.

May be no longer than 300 characters.
match_type

string

/

required

The match type to perform when determining if this link replacement affects a particular click.

  • all: All clicks that match the specified filters (mailclass, instanceid).
  • exact: Clicks where the original destination URL exactly matches match_string and the specified filters (mailclass, instanceid).
  • regexp: Clicks where the original destination URL matches match_string using regular expression comparison and the specified filters (mailclass, instanceid).
  • linkid: Clicks where the link being clicked was defined using the data-ga-linkid="linkid" attribute and the content of that tag matches this value. The specified filters (mailclass, instanceid) also apply.
match_string

string, optional

The string to use when comparing for match_type types of exact and regexp.

May be no longer than 10240 characters (we don’t recommend having URLs this long).
linkid

string, optional

The string to use when comparing for match_type type of linkid.
replacement_string

string, optional

The new URL to use in place of the original URL. If this is blank, no replacement will be made.

All Link Replacements must include either replacement_string or expiration_time (or both).

May be no longer than 10240 characters (we don’t recommend having URLs this long).
replacement_includes_capture_refs

boolean, optional

If match_type is regexp, then match_string may containing capturing groups and replacement_string may contain capture references.

  • If replacement_includes_capture_refs is true, then: In replacement_string, the text \1 will be replaced with the characters captured by the first regex capture sequence. This continues from \2 through \9. Additionally, in the text \\ will be replaced with a single backslash. There are other undocumented backslash-escaped sequences (which are subject to change in the future), so we strongly recommend that all backslashes that are not part of a \\ or \1 (etc) replacement codes be escaped as \\.

  • If replacement_includes_capture_refs is false, none of these replacements will be made.
expiration_time

timestamp, optional

If this link replacement matches for a click, and the current time has passed the value for expiration_time, the user will be presented with the message link expired instead of being taken to the destination URL.

All Link Replacements must include either replacement_string or expiration_time (or both).
notes

string, optional

User-defined text description of the purpose of this link replacement.

May be no longer than 512 characters.

Link Replacements must be unique for their matching criteria – this means that only one Link Replacement can exist for any given combination of mailclass, instanceid, match_type, match_string, and linkid.

Link Replacements are evaluated from most-specific to least-specific mailclass and instanceid settings:

  1. mailclass and instanceid is set
  2. mailclass is set, instanceid is not set
  3. mailclass and instanceid are not set

Additionally, if multiple matches are found, ties will be broken by specificity of the match_type:

  1. linkid
  2. exact
  3. regexp
  4. all

If there’s still a tie after the above evaluations, the earliest created (lowest id) Link Replacement will be used.

GET /ga/api/v3/eng/link_replacements

Parameters

The following parameters are valid for the above endpoint.

page

integer

/

optional

The page number from which to retrieve. Page numbering starts at 0.
page_token

string

/

optional

The page_token to retrieve the next page based on the prior query results.
mailclass

string

/

optional

Filter the results to just a single Mail Class (case-insensitive). If this parameter is specified and blank, this will filter the results to link replacements that do not specify a Mail Class.
instanceid

string

/

optional

Filter the results to just a single InstanceID (case-insensitive). If this parameter is specified and blank, this will filter the results to link replacements that do not specify an InstanceID.

Can only be specified if mailclass is also specified.

Examples:

GET /ga/api/v3/eng/link_replacements?page={page}
GET /ga/api/v3/eng/link_replacements?page_token={page_token}
GET /ga/api/v3/eng/link_replacements?mailclass={mailclass}
GET /ga/api/v3/eng/link_replacements?mailclass={mailclass}&instance={instance}

Response

The response will contain a list of Link Replacements in the following format.

link_replacements

array of hashes
id

integer

An automatically generated identifier.
pagination

hash
page

integer

The page number of this result set. Page numbers start at 0.
per_page

integer

The number of records returned on each page.
num_pages

integer

The total number of pages in the result set.
num_records

integer

The total number of records that are in the result set.
next_page_token

string

A unique identifier that can be used to retrieve the next result set.

null is returned if this is the last page.

Example

GET /ga/api/v3/eng/link_replacements


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "link_replacements": [
      {
        "id": 1,
        "match_type": "all",
        "mailclass": {
          "id": 1,
          "name": "foo"
        },
        "instanceid": "1234",
        "match_string": null,
        "linkid": null,
        "replacement_string": "http://foo.com",
        "replacement_includes_capture_refs": null,
        "expiration_time": null,
        "notes": null
      },
      {
        "id": 2,
        "match_type": "all",
        "mailclass": null,
        "instanceid": null,
        "match_string": null,
        "linkid": null,
        "replacement_string": "http://foo.com",
        "replacement_includes_capture_refs": null,
        "expiration_time": null,
        "notes": null
      },
      {
        "id": 3,
        "match_type": "all",
        "mailclass": {
          "id": 1,
          "name": "foo"
        },
        "instanceid": "12345",
        "match_string": null,
        "linkid": null,
        "replacement_string": "http://foo.com",
        "replacement_includes_capture_refs": null,
        "expiration_time": null,
        "notes": null
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}


GET /ga/api/v3/eng/link_replacements/{id}

Response

The response will contain details on the requested record:

link_replacement

hash

The attributes for this hash are defined in the Attributes section of this document.

Example

GET /ga/api/v3/eng/link_replacements/16


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "link_replacement": {
      "id": 16,
      "match_type": "all",
      "mailclass": {
        "id": 6,
        "name": "foo"
      },
      "instanceid": "1234",
      "match_string": null,
      "linkid": null,
      "replacement_string": "http://foo.com",
      "replacement_includes_capture_refs": null,
      "expiration_time": null,
      "notes": null
    }
  },
  "error_code": null,
  "error_messages": null
}


POST /ga/api/v3/eng/link_replacements

Payload

link_replacement

hash

/

required

The content of this hash is described in the Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

The response will include a link_replacement key containing the full Link Replacement record as defined in the Attributes.

Example

POST /ga/api/v3/eng/link_replacements


{
  "link_replacement": {
    "match_type": "regexp",
    "mailclass": {
      "id": 9
    },
    "instanceid": "1234",
    "match_string": ".*",
    "linkid": "5000",
    "replacement_string": "https://example.com",
    "replacement_includes_capture_refs": true,
    "expiration_time": "2023-12-15T13:14:03Z"
  }
}


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "link_replacement": {
      "id": 28,
      "match_type": "regexp",
      "mailclass": {
        "id": 9,
        "name": "foo"
      },
      "instanceid": "1234",
      "match_string": ".*",
      "linkid": "5000",
      "replacement_string": "https://example.com",
      "replacement_includes_capture_refs": true,
      "expiration_time": "2023-12-15 13:14:03",
      "notes": null
    }
  },
  "error_code": null,
  "error_messages": null
}


PUT /ga/api/v3/eng/link_replacements/{id}

Payload

link_replacement

hash

/

required

The content of this hash is described in the Attributes section of this page.

The data may contain a mixture of required and optional fields. Do not specify read-only fields.

Response

The response will include a link_replacement key containing the full Link Replacement record as defined in the Attributes.

Example

PUT /ga/api/v3/eng/link_replacements/22


{
  "link_replacement": {
    "linkid": "foo bar",
    "notes": "hey there\nthis is a note\n"
  }
}


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "link_replacement": {
      "id": 22,
      "match_type": "all",
      "mailclass": {
        "id": 8,
        "name": "foo"
      },
      "instanceid": "1234",
      "match_string": null,
      "linkid": "foo bar",
      "replacement_string": "http://foo.com",
      "replacement_includes_capture_refs": null,
      "expiration_time": null,
      "notes": "hey there\nthis is a note"
    }
  },
  "error_code": null,
  "error_messages": null
}


DELETE /ga/api/v3/eng/link_replacements/{id}

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/link_replacements/19


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
  },
  "error_code": null,
  "error_messages": null
}

 Engine Users API
Running Custom Code During Delivery Attempts 

Copyright © 2012–2024 GreenArrow Email