DKIM Keys API

Table of Contents
Overview
Attributes
Get a List of DKIM Keys
Get Details on a Single DKIM Key
Create a DKIM Key
Update a DKIM Key
Delete a DKIM Key

Overview

GreenArrow Engine can digitally sign outgoing messages using DKIM.

Attributes

The following attributes are defined for DKIM Keys:

dkim_key
hash
/
required

id
integer
/
read-only

An automatically generated identifier.

domain
string
/
required

The domain name associated with this DKIM Key.

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. A dot may not appear next to a dash or another dot. (For example “a-b.example.com” is valid, but “a-.example.com” and “a..example.com” are not valid.)

selector
string
/
required

The selector used to identify this DKIM Key.

Must be from 1 to 200 characters in length
Must be unique (case-insensitive) among all DKIM Keys with the same (case-insensitive) domain.

default_for_domain
boolean
/
default: false

Whether this is the default DKIM key for this domain.

If, when this parameter is set to true through a create or update API call, another DKIM Key sharing the same domain already has default_for_domain set to true, the other domain’s default_for_domain value will be set to false.

key
hash
/
required

To create the private key, you have two options:

Use a key generated elsewhere. To do this, enter your private key into the private field. The bits field will be filled in automatically based upon this key.
Automatically generate a new private key. To do this, specify the length of the new key using the bits field. The private field will automatically be filled in with the generated key. We recommend 1024 bit keys. The maximum key size that will be generated automatically is 8192 bits.

The bits field may not be changed on existing keys. If the private field is updated on existing keys, bits will automatically be set to the correct value for the new key.

bits
integer
/
default: see above

The number of bits used to generate this key.

Must be a positive integer greater than or equal to 512

private
string
/
default: see above

The PEM-encoded private key.

Must be a valid private key.

public
string
/
read-only

The public key, derived from the private key. This is PEM-encoded with the header line, footer line, and line-breaks stripped. (This is the format that is published in DNS.)

dns
hash
/
read-only

The DNS record that must be created for recipients to verify DKIM signatures.

public_key
hash

name string	The DNS record name.
type string	The DNS record type.
value string	The DNS record value.

Get a List of DKIM Keys

GET /ga/api/v3/eng/dkim_keys
GET /ga/api/v3/eng/dkim_keys?page={page}
GET /ga/api/v3/eng/dkim_keys?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.
domain string / optional	Only include DKIM keys for the specified domain (case-insensitive).

Response

The response will contain a list of DKIM Keys in the following format.

dkim_keys
array of hashes

id integer	An automatically generated identifier.
domain string	The domain name associated with this DKIM Key.
selector string	The selector used to identify this DKIM Key.
default_for_domain boolean	This DKIM Key is the default to be used for this `domain`.
key_bits integer	The size of this key in bits.

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

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "dkim_keys": [
      {
        "id": 1,
        "domain": "my-domain.com",
        "selector": "default",
        "default_for_domain": false,
        "key_bits": 32
      },
      {
        "id": 2,
        "domain": "domain.com",
        "selector": "default",
        "default_for_domain": false,
        "key_bits": 128
      },
      {
        "id": 3,
        "domain": "domain-3.com",
        "selector": "default",
        "default_for_domain": true,
        "key_bits": 64
      }
    ],
    "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 DKIM Key

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

Response

The response will contain details on the requested record.

dkim_key
hash

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

Example

GET /ga/api/v3/eng/dkim_keys/1

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "dkim_key": {
      "id": 1,
      "domain": "my-domain.com",
      "selector": "default",
      "default_for_domain": false,
      "key": {
        "bits": 32,
        "private": "-----BEGIN RSA PRIVATE KEY-----\nMC0CAQACBQCoJLcxAgMBAAECBBur+skCAwDfNwIDAMDXAgMAhSECAkWhAgMAyzU=\n-----END RSA PRIVATE KEY-----",
        "public": "MCAwDQYJKoZIhvcNAQEBBQADDwAwDAIFAKgktzECAwEAAQ=="
      },
      "dns": {
        "public_key": {
          "name": "default._domainkey.my-domain.com",
          "type": "TXT",
          "value": "k=rsa; p=MCAwDQYJKoZIhvcNAQEBBQADDwAwDAIFAKgktzECAwEAAQ=="
        }
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Create a DKIM Key

POST /ga/api/v3/eng/dkim_keys

Payload

dkim_key
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 DKIM Key record as defined in the DKIM Key Attributes.

Example

POST /ga/api/v3/eng/dkim_keys

{
  "dkim_key": {
    "domain": "my-domain.com",
    "selector": "second",
    "default_for_domain": false,
    "key": {
      "private": "-----BEGIN RSA PRIVATE KEY-----\nMCwCAQACBQCpGuTBAgMBAAECBCt6no0CAwDd5wIDAMMXAgIotwICDVkCAwCGMg==\n-----END RSA PRIVATE KEY-----"
    }
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "dkim_key": {
      "id": 4,
      "domain": "my-domain.com",
      "selector": "second",
      "default_for_domain": false,
      "key": {
        "bits": 32,
        "private": "-----BEGIN RSA PRIVATE KEY-----\nMCwCAQACBQCpGuTBAgMBAAECBCt6no0CAwDd5wIDAMMXAgIotwICDVkCAwCGMg==\n-----END RSA PRIVATE KEY-----",
        "public": "MCAwDQYJKoZIhvcNAQEBBQADDwAwDAIFAKka5MECAwEAAQ=="
      },
      "dns": {
        "public_key": {
          "name": "second._domainkey.my-domain.com",
          "type": "TXT",
          "value": "k=rsa; p=MCAwDQYJKoZIhvcNAQEBBQADDwAwDAIFAKka5MECAwEAAQ=="
        }
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Update a DKIM Key

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

Payload

dkim_key
hash
/
required

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

Response

The response is the full DKIM Key record as defined in the DKIM Key Attributes.

Example

PUT /ga/api/v3/eng/dkim_keys/1

{
  "dkim_key": {
    "domain": "new-domain.com"
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "dkim_key": {
      "id": 1,
      "domain": "new-domain.com",
      "selector": "default",
      "default_for_domain": false,
      "key": {
        "bits": 32,
        "private": "-----BEGIN RSA PRIVATE KEY-----\nMC0CAQACBQCoJLcxAgMBAAECBBur+skCAwDfNwIDAMDXAgMAhSECAkWhAgMAyzU=\n-----END RSA PRIVATE KEY-----",
        "public": "MCAwDQYJKoZIhvcNAQEBBQADDwAwDAIFAKgktzECAwEAAQ=="
      },
      "dns": {
        "public_key": {
          "name": "default._domainkey.new-domain.com",
          "type": "TXT",
          "value": "k=rsa; p=MCAwDQYJKoZIhvcNAQEBBQADDwAwDAIFAKgktzECAwEAAQ=="
        }
      }
    }
  },
  "error_code": null,
  "error_messages": null
}

Delete a DKIM Key

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

Response

The response is a standard success or error response.

Example

DELETE /ga/api/v3/eng/dkim_keys/2

HTTP/1.1 200 OK

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