GreenArrow Email Software Documentation

DKIM Keys API

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:

  1. 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.

  2. 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
}


Copyright © 2012–2024 GreenArrow Email