GreenArrow Email Software Documentation

URL Domains API

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


HTTP/1.1 200 OK


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

Set Default URL Domain

PUT /ga/api/v3/eng/url_domains/default

Set the default URL Domain to be used by email sent from GreenArrow Engine when the SimpleMH mail class is configured to use the system default URL Domain.

Payload

default_url_domain

hash

/

required

Either the id or the domain may be provided to set the default URL Domain. If you provide both id and domain, then the id will be used in favor of domain.

id

integer

The id of the URL domain to use as the default.
domain

string

The string domain name of the URL domain to use as the default.

Response

default_url_domain

hash
id

integer

The id of the URL domain to use as the default.
domain

string

The string domain name of the URL domain to use as the default.

Example

PUT /ga/api/v3/eng/url_domains/default


{
  "default_url_domain": {
    "domain": "test-domain-1.com"
  }
}


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "default_url_domain": {
      "id": 20,
      "domain": "test-domain-1.com"
    }
  },
  "error_code": null,
  "error_messages": null
}

Get Default URL Domain

GET /ga/api/v3/eng/url_domains/default

Get the default URL Domain to be used by email sent from GreenArrow Engine when the SimpleMH mail class is configured to use the system default URL Domain.

Response

default_url_domain

hash
id

integer

The id of the URL domain to use as the default.
domain

string

The string domain name of the URL domain to use as the default.

Example

GET /ga/api/v3/eng/url_domains/default


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "default_url_domain": {
      "id": 27,
      "domain": "test-domain-2.com"
    }
  },
  "error_code": null,
  "error_messages": null
}

 DKIM Keys API
Incoming Email Domains API 

Copyright © 2012–2024 GreenArrow Email