URL Domains API

Table of Contents
Overview
Attributes
Get a List of URL Domains
Get Details on a single URL Domain
List the References to a URL Domain
Create a URL Domain
Update a URL Domain
Delete a URL Domain

Overview

GreenArrow can perform click and open tracking using URL Domains.

Attributes

The following attributes are defined for URL Domains:

url_domain
hash
/
required

id
integer
/
read-only

An automatically generated identifier.

domain
string
/
required

The domain name associated with this URL Domain.

Must be unique (case-insensitive)
Must be from 1 to 200 characters in length
Must be a domain name: it must have dot-separated strings of only letters, numbers, and dashes. Dashes may not appear next to a dot. (For example “a-b.example.com” is valid, but “a-.example.com” and “a..example.com” are not valid.)

ssl
boolean
/
required

When this is true, links are generated using https. Otherwise, http is used.

Get a List of URL Domains

GET /ga/api/v3/eng/url_domains
GET /ga/api/v3/eng/url_domains?page={page}
GET /ga/api/v3/eng/url_domains?page_token={page_token}

Parameters

page integer / optional	The page number to retrieve. Page numbering starts at `0`.
page_token string / optional	The `page_token` can be used to retrieve the next page of results.

Response

The response will contain a list of URL Domains in the following format.

url_domains
array of hashes

id integer	An automatically generated identifier.
domain string	The domain name associated with this URL Domain.

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/url_domains

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "url_domains": [
      {
        "id": 1,
        "domain": "example.com"
      },
      {
        "id": 2,
        "domain": "test-domain-1.com"
      },
      {
        "id": 3,
        "domain": "test-domain-2.com"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Get Details on a single URL Domain

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

Response

The response will contain details on the requested record.

url_domain
hash

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

Example

GET /ga/api/v3/eng/url_domains/8

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "url_domain": {
      "id": 8,
      "domain": "test-domain-1.com",
      "ssl": true
    }
  },
  "error_code": null,
  "error_messages": null
}

List the References to a URL Domain

GET /ga/api/v3/eng/url_domains/{id}/used_by
GET /ga/api/v3/eng/url_domains/{id}/used_by?page={page}
GET /ga/api/v3/eng/url_domains/{id}/used_by?page_token={page_token}

Parameters

page integer / optional	The page number to retrieve. Page numbering starts at `0`.
page_token string / optional	The `page_token` can be used to retrieve the next page of results.

Response

used_by
array of hashes

A list of objects that use this URL Domain.

This list does not include any references made by GreenArrow Studio, but it may in the future.

type
string

The type of object.

May be: mail_class

id
integer

The unique identifier for the object.

name
string

The user-supplied case-insensitive unique identifier for the object.

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/url_domains/2/used_by

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "used_by": [
      {
        "type": "mail_class",
        "id": 1,
        "name": "basic_mail_class"
      },
      {
        "type": "mail_class",
        "id": 3,
        "name": "advanced_mail_class"
      },
      {
        "type": "mail_class",
        "id": 4,
        "name": "tertiary_mc"
      }
    ],
    "pagination": {
      "page": 0,
      "per_page": 100,
      "num_pages": 1,
      "num_records": 3,
      "next_page_token": null
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a URL Domain

POST /ga/api/v3/eng/url_domains

Payload

url_domain
hash
/
required

An object as described in the Attributes section of this page.

All required fields must be present. Do not specify read-only fields.

Response

The response is the full URL Domain record as defined in the URL Domain Attributes.

Example

POST /ga/api/v3/eng/url_domains

{
  "url_domain": {
    "domain": "my-domain.com",
    "ssl": false
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "url_domain": {
      "id": 12,
      "domain": "my-domain.com",
      "ssl": false
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a URL Domain

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

Payload

url_domain
hash
/
required

This hash is described in the Attributes section of this page.

Response

The response is the full URL Domain record as defined in the URL Domain Attributes.

Example

PUT /ga/api/v3/eng/url_domains/16

{
  "url_domain": {
    "domain": "new-domain.com",
    "ssl": false
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "url_domain": {
      "id": 16,
      "domain": "new-domain.com",
      "ssl": false
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a URL Domain

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

URL Domains that are used by other records may not be deleted. Use the URL Domains API to get a list of such records.

References made to URL Domains from GreenArrow Studio will not prevent deletion of the URL Domain, but may in the future. Deleting a URL Domain that is used by a scheduled/in-progress GreenArrow Studio campaign will cause the campaign to either not send or send with the deleted domain.

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/url_domains/19

HTTP/1.1 200 OK

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