GreenArrow Email Software Documentation

Sending Domains API

GreenArrow CloudMTA

This feature is only available on GreenArrow CloudMTA.

Overview

Sending Domains tie your RFC5322.From domain to a complete, automatically managed DNS configuration for DKIM signing and click/open/bounce tracking. See Sending Domains for a full conceptual overview.

Attributes

The following are the configurable attributes defined for Sending Domains.

sending_domain

hash

/

required
id

integer

/

read-only

A unique automatically generated identifier.
created_at

string

/

read-only

When the Sending Domain was created, in ISO-8601 format in the Engine’s time zone.
domain

string

/

required

The RFC5322.From domain for this Sending Domain.

  • Must be present and unique (case-insensitive).
  • Immutable after creation.
cname_suffix_domain

string

/

optional

The domain that this Sending Domain’s CNAME records point at. GreenArrow manages the TXT and A records underneath it, so DKIM key rotation and IP changes never require the customer to touch their own DNS again.

Defaults to the system’s configured suffix domain (dnsforemail.com unless your installation overrides it).

  • Must be one of the suffix domains allowed on your installation. Ask GreenArrow support which values are available if you need something other than the default.
  • Immutable after creation.
tracking_subdomain

string

/

optional

The subdomain of domain used for click/open/bounce tracking. Defaults to "trk".

  • Immutable after creation.
  • Must be distinct from dkim_selector1 and dkim_selector2.
  • Must not contain . or _.
  • May not be mx, which is reserved for the mail exchanger of a same-named Receiving Domain.
  • May not be specified if a shared_tracking_domain is present. A request that gives both is rejected; sending an explicit null is allowed, so an object read back from the API can be sent whole.
  • Omitted from responses when the sending domain uses a shared_tracking_domain, which supplies the tracking host in its place.
shared_tracking_domain

hash

/

optional

A Shared Tracking Domain that handles click/open/bounce tracking DNS for this domain instead of the per-domain tracking_subdomain. Either id or domain may be provided when creating or updating.

May not be specified if a tracking_subdomain is present.

id

integer

The unique identifier of the Shared Tracking Domain.
domain

string

The domain of the Shared Tracking Domain.
effective_url_domain

string

/

read-only

The hostname that click and open tracking links use for email from this domain. GreenArrow uses it only while dns_verified is true.

  • With a shared_tracking_domain, this is the url_domain of the Shared Tracking Domain (or its domain, if it has no url_domain).
  • Otherwise, this is tracking_subdomain and domain joined by a period, for example trk.example.com.
  • If there is no shared tracking domain or tracking subdomain, this is null.
effective_bounce_domain

string

/

read-only

The hostname of the bounce address (the Return-Path) of email from this domain. GreenArrow uses it only while dns_verified is true.

  • With a shared_tracking_domain, this is the bounce_domain of the Shared Tracking Domain (or its domain, if it has no bounce_domain).
  • Otherwise, this is the same hostname as effective_url_domain.
  • If there is no shared tracking domain or tracking subdomain, this is null.
track_open

boolean

/

optional

Whether opens are tracked for this domain. Overrides the Mail Class setting. Default: true.

Omitting this key on create gets you true; omitting it on update leaves the stored value unchanged. Sending an explicit null sets it back to inheriting the Mail Class setting.
track_click

boolean

/

optional

Whether clicks are tracked for this domain. Overrides the Mail Class setting. Default: true.

Omitting this key on create gets you true; omitting it on update leaves the stored value unchanged. Sending an explicit null sets it back to inheriting the Mail Class setting.
route

hash

/

optional

The Route used for email from this domain, unless overridden by an X-GreenArrow-Route header (or an X-GreenArrow-VirtualMTA header.) Overrides the Mail Class setting. Either id or name may be provided when creating or updating. If null, then the Mail Class VirtualMTA setting is used.

Omitting this key on update leaves the stored Route unchanged. Sending an explicit null on update removes the Route of the domain.

id

integer

The unique identifier of the route.
name

string

The unique name of the route.
dkim_mode

string

/

optional

How DKIM keys are configured for this domain. Immutable after creation. Default: "automatic".

  • automatic — Two DKIM keys with CNAME delegation to dnsforemail.com (or an ESP-specific dynamic DNS domain). GreenArrow manages the TXT key records; key rotation requires no DNS changes on your end.
  • txt_single — One DKIM key. You add a TXT record directly containing the public key.
  • txt_multiple — Two DKIM keys. You add two TXT records directly containing the public keys.
dkim_selector1

string

/

optional

The selector name for the first DKIM key. Immutable after creation. If not supplied, it is filled in with the configured default; the resulting value is always stored, so the selectors are never null.

  • Must be distinct from dkim_selector2 and tracking_subdomain.
  • May not be mx, which is reserved for the mail exchanger of a same-named Receiving Domain.
dkim_selector2

string

/

optional

The selector name for the second DKIM key. Immutable after creation. If not supplied, it is filled in with the configured default; the resulting value is always stored, so the selectors are never null.

  • Required unless dkim_mode is "txt_single".
  • Must be distinct from dkim_selector1 and tracking_subdomain.
  • May not be mx, which is reserved for the mail exchanger of a same-named Receiving Domain.
dkim_key_length

integer

/

optional

The bit length for generated DKIM keys. Immutable after creation. Must be 1024 or 2048. Default: 1024.
sending_enabled

boolean

/

optional

Whether email injection is allowed for this domain. Default: true. When false, injection via this domain is prevented regardless of DNS verification status.
dns_verified

boolean

/

read-only

true once all DNS records have been verified. This is a one-way flag — it never returns to false.
dns_verified_time

string

/

read-only

When the domain was first verified, in ISO-8601 format in the Engine’s time zone. null until it verifies. Returned only on the single-domain (show) endpoint, not on the list endpoint.
dns_regression

boolean

/

read-only

true if the domain was previously verified but DNS records are no longer correct, as of the last DNS check (which is automatically done every 15 minutes). Cleared when the records are fixed. You may use the DNS check API to perform an immediate DNS check.
dns_regression_time

string

/

read-only

When the current regression was detected, in ISO-8601 format in the Engine’s time zone. null when the domain is not regressed. Returned only on the single-domain (show) endpoint, not on the list endpoint.
dns_records

array of hashes

/

read-only

The DNS records that must be added to your DNS zone for this domain to become verified. Returned only on the single-domain (show) endpoint, not on the list endpoint.

bind

string

The full BIND zone file syntax for this record, ready to paste.
type

string

The DNS record type: CNAME or TXT.
name

string

The DNS hostname.
value

string

The expected record value.
verified

boolean or null

true if the last DNS check accepted this record, and false if it did not. A CNAME can also be accepted when its provider returns matching flattened records. null if no DNS check of this domain has completed yet. Unlike dns_verified, this is not a one-way flag: each completed DNS check sets it again. It returns to false if a later check finds the record missing or wrong, or gets no answer from a nameserver.

GreenArrow checks DNS when the domain is created and then every 15 minutes. Use the Check DNS API with recheck_now=1 to check at once. That API allows one such check of a domain in 60 seconds.
active

boolean

false for a DKIM record whose key does not sign email, and true for each other record. GreenArrow signs the email of a domain with one DKIM key: the default key of the domain. The key of the first DKIM selector becomes the default when the domain is first verified. Until then, each DKIM record is false.
unwanted_dns_records

array of hashes

/

read-only

DNS records that currently exist but must be removed before the domain can verify (for example a conflicting record). Empty when there are none. Returned only on the single-domain (show) endpoint, not on the list endpoint.

type

string

The DNS record type.
name

string

The DNS hostname.
value

string

The record value that was found.

Get a List of Sending Domains

GET /ga/api/v3/eng/sending_domains

To keep the list response lightweight, the dns_records and unwanted_dns_records arrays are not included here — fetch a single domain (below) to retrieve them.

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.

A page_token keeps the order_by of the request that returned it. So if you start with no page_token and follow next_page_token until it is null, you get each sending domain once, in one order.

Send the same filters (domain, dns_state, sending_enabled) with each page_token. In domain order, if the last sending domain of the prior page is deleted, or no longer matches your filters, before you request the next page, the request fails with the error code invalid_request and the message “the next record has been deleted, please restart your request”. Start again from the first page.
order_by

string

/

optional

The order of the sending domains: domain or id. domain orders the sending domains by domain name, ignoring letter case. Another value fails with the error code invalid_request.

Defaults to domain.
domain

string

/

optional

Filter by domain name. This performs a case-insensitive substring match, so domain=example would match example.com, mail.example.org, etc.
dns_state

string

/

optional

Filter by DNS verification state. One of not_verified, verified_good (verified and DNS still correct), or verified_regressed (verified but DNS has since regressed).

To select more than one state, give a list with commas between the states. For example, dns_state=not_verified,verified_regressed returns the domains that are in either state.

An empty or unrecognized state, whether alone or in a list, leaves the results unfiltered by DNS state.
sending_enabled

boolean

/

optional

Filter by whether sending is enabled — true or false.

Response

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

sending_domains

array of hashes

Each hash contains all of the attributes listed in the Attributes section.
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/sending_domains


HTTP/1.1 200 OK


{
  "sending_domains": [
    {
      "id": 1,
      "created_at": "2026-08-10T14:02:11-05:00",
      "domain": "example.com",
      "tracking_subdomain": "trk",
      "effective_url_domain": "trk.example.com",
      "effective_bounce_domain": "trk.example.com",
      "track_open": true,
      "track_click": true,
      "dkim_mode": "automatic",
      "dkim_selector1": "ga1",
      "dkim_selector2": "ga2",
      "dkim_key_length": 1024,
      "sending_enabled": true,
      "dns_verified": true,
      "dns_regression": false,
      "shared_tracking_domain": null,
      "route": null
    }
  ],
  "pagination": {
    "page": 0,
    "per_page": 100,
    "num_pages": 1,
    "num_records": 1,
    "next_page_token": null
  }
}

Get a Single Sending Domain

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

The {id} may be either the numeric ID or the domain name (case-insensitive).

Example

GET /ga/api/v3/eng/sending_domains/1
GET /ga/api/v3/eng/sending_domains/example.com


HTTP/1.1 200 OK


{
  "sending_domain": {
    "id": 1,
    "created_at": "2026-08-10T14:02:11-05:00",
    "domain": "example.com",
    "tracking_subdomain": "trk",
    "effective_url_domain": "trk.example.com",
    "effective_bounce_domain": "trk.example.com",
    "track_open": true,
    "track_click": true,
    "dkim_mode": "automatic",
    "dkim_selector1": "ga1",
    "dkim_selector2": "ga2",
    "dkim_key_length": 1024,
    "sending_enabled": true,
    "dns_verified": true,
    "dns_verified_time": "2026-08-11T06:16:00-05:00",
    "dns_regression": false,
    "dns_regression_time": null,
    "shared_tracking_domain": null,
    "route": null,
    "dns_records": [
      {
        "bind": "trk.example.com.  IN  CNAME  trk.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "trk.example.com",
        "value": "trk.abc123def456.dnsforemail.com",
        "verified": true,
        "active": true
      },
      {
        "bind": "ga1._domainkey.example.com.  IN  CNAME  ga1.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga1._domainkey.example.com",
        "value": "ga1.abc123def456.dnsforemail.com",
        "verified": true,
        "active": true
      },
      {
        "bind": "ga2._domainkey.example.com.  IN  CNAME  ga2.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga2._domainkey.example.com",
        "value": "ga2.abc123def456.dnsforemail.com",
        "verified": true,
        "active": false
      }
    ],
    "unwanted_dns_records": []
  }
}

Create a Sending Domain

POST /ga/api/v3/eng/sending_domains

Parameters

See the Attributes section for valid parameters.

Example

POST /ga/api/v3/eng/sending_domains


{
  "sending_domain": {
    "domain": "example.com"
  }
}


HTTP/1.1 200 OK


{
  "sending_domain": {
    "id": 1,
    "created_at": "2026-08-10T14:02:11-05:00",
    "domain": "example.com",
    "tracking_subdomain": "trk",
    "effective_url_domain": "trk.example.com",
    "effective_bounce_domain": "trk.example.com",
    "track_open": true,
    "track_click": true,
    "dkim_mode": "automatic",
    "dkim_selector1": "ga1",
    "dkim_selector2": "ga2",
    "dkim_key_length": 1024,
    "sending_enabled": true,
    "dns_verified": false,
    "dns_regression": false,
    "shared_tracking_domain": null,
    "route": null,
    "dns_records": [
      {
        "bind": "trk.example.com.  IN  CNAME  trk.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "trk.example.com",
        "value": "trk.abc123def456.dnsforemail.com",
        "verified": false,
        "active": true
      },
      {
        "bind": "ga1._domainkey.example.com.  IN  CNAME  ga1.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga1._domainkey.example.com",
        "value": "ga1.abc123def456.dnsforemail.com",
        "verified": false,
        "active": false
      },
      {
        "bind": "ga2._domainkey.example.com.  IN  CNAME  ga2.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga2._domainkey.example.com",
        "value": "ga2.abc123def456.dnsforemail.com",
        "verified": false,
        "active": false
      }
    ]
  }
}

Update a Sending Domain

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

The {id} may be either the numeric ID or the domain name (case-insensitive).

Parameters

See the Attributes section for valid parameters. Note that domain, cname_suffix_domain, tracking_subdomain, dkim_mode, dkim_selector1, dkim_selector2, and dkim_key_length are immutable after creation and cannot be changed.

Example

PUT /ga/api/v3/eng/sending_domains/1
PUT /ga/api/v3/eng/sending_domains/example.com


{
  "sending_domain": {
    "route": { "name": "my-route" },
    "track_open": false
  }
}


HTTP/1.1 200 OK


{
  "sending_domain": {
    "id": 1,
    "created_at": "2026-08-10T14:02:11-05:00",
    "domain": "example.com",
    "tracking_subdomain": "trk",
    "effective_url_domain": "trk.example.com",
    "effective_bounce_domain": "trk.example.com",
    "track_open": false,
    "track_click": true,
    "dkim_mode": "automatic",
    "dkim_selector1": "ga1",
    "dkim_selector2": "ga2",
    "dkim_key_length": 1024,
    "sending_enabled": true,
    "dns_verified": true,
    "dns_verified_time": "2026-08-11T06:16:00-05:00",
    "dns_regression": false,
    "dns_regression_time": null,
    "shared_tracking_domain": null,
    "route": {
      "id": 3,
      "name": "my-route"
    },
    "dns_records": [
      {
        "bind": "trk.example.com.  IN  CNAME  trk.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "trk.example.com",
        "value": "trk.abc123def456.dnsforemail.com",
        "verified": true,
        "active": true
      },
      {
        "bind": "ga1._domainkey.example.com.  IN  CNAME  ga1.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga1._domainkey.example.com",
        "value": "ga1.abc123def456.dnsforemail.com",
        "verified": true,
        "active": true
      },
      {
        "bind": "ga2._domainkey.example.com.  IN  CNAME  ga2.abc123def456.dnsforemail.com.",
        "type": "CNAME",
        "name": "ga2._domainkey.example.com",
        "value": "ga2.abc123def456.dnsforemail.com",
        "verified": true,
        "active": false
      }
    ]
  }
}

Delete a Sending Domain

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

The {id} may be either the numeric ID or the domain name (case-insensitive).

Parameters

The following parameter is valid for the above endpoint.

fail_delete_if_disabled

boolean

/

optional

If true, a Sending Domain whose sending_enabled is false is not deleted. The request fails with the error code validation_failed and the message sending_domain: cannot be deleted while sending is disabled. Default: false. The values true, 1, 1.0, yes, y and on are true, in upper or lower case. Each other value is treated as false, so this option does not prevent deletion.

Example

DELETE /ga/api/v3/eng/sending_domains/1
DELETE /ga/api/v3/eng/sending_domains/example.com


HTTP/1.1 200 OK


{
  "success": true
}

To refuse deletion when sending is disabled, put the parameter in the request URL:

DELETE /ga/api/v3/eng/sending_domains/example.com?fail_delete_if_disabled=true

For a disabled domain, the response is:

{
  "success": false,
  "data": null,
  "error_code": "validation_failed",
  "error_messages": ["sending_domain: cannot be deleted while sending is disabled"]
}

 Mailgun-Compatible IP Pool API
Shared Tracking Domains API 

Copyright © 2012–2026 GreenArrow Email