Receiving Domains API

• Table of Contents
• Overview
• Attributes
• Get a List of Receiving Domains
• Get a Single Receiving Domain
• Create a Receiving Domain
• Update a Receiving Domain
• Delete a Receiving Domain
• Mailboxes

Overview

Receiving Domains configure inbound MX-based email receiving for a domain. When a Receiving Domain’s DNS is verified, GreenArrow automatically provisions an Incoming Email Domain so that mailboxes under that domain can receive email.

DNS verification requires a single MX record pointing your domain at GreenArrow’s mail exchanger. An MX record (rather than a CNAME) is used so that you can keep hosting your own website at the domain, and because an MX record may not point at a CNAME (RFC 2181 §10.3). GreenArrow checks DNS every 15 minutes and updates verification status automatically.

Attributes

The following are the configurable attributes defined for Receiving Domains.

Get a List of Receiving Domains

GET /ga/api/v3/eng/receiving_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.

Response

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

Example

GET /ga/api/v3/eng/receiving_domains

HTTP/1.1 200 OK

{
  "receiving_domains": [
    {
      "id": 1,
      "domain": "receive.example.com",
      "cname_suffix_domain": "dnsforemail.com",
      "dns_verified": true,
      "dns_regression": false
    }
  ],
  "pagination": {
    "page": 0,
    "per_page": 100,
    "num_pages": 1,
    "num_records": 1,
    "next_page_token": null
  }
}

Get a Single Receiving Domain

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

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

Example

GET /ga/api/v3/eng/receiving_domains/1

HTTP/1.1 200 OK

{
  "receiving_domain": {
    "id": 1,
    "domain": "receive.example.com",
    "cname_suffix_domain": "dnsforemail.com",
    "dns_verified": true,
    "dns_verified_time": "2026-08-11T06:16:00-05:00",
    "dns_regression": false,
    "dns_regression_time": null,
    "dns_records": [
      {
        "bind": "receive.example.com.  IN  MX  10 mx.abc123def456.dnsforemail.com.",
        "type": "MX",
        "name": "receive.example.com",
        "value": "10 mx.abc123def456.dnsforemail.com"
      }
    ],
    "unwanted_dns_records": []
  }
}

Example: Look Up by Domain Name

The domain name may be used in place of the numeric ID (case-insensitive).

GET /ga/api/v3/eng/receiving_domains/receive.example.com

HTTP/1.1 200 OK

The response body is identical to the by-ID example above.

Create a Receiving Domain

POST /ga/api/v3/eng/receiving_domains

Parameters

See the Attributes section for valid parameters.

Example

POST /ga/api/v3/eng/receiving_domains

{
  "receiving_domain": {
    "domain": "receive.example.com"
  }
}

HTTP/1.1 200 OK

{
  "receiving_domain": {
    "id": 1,
    "domain": "receive.example.com",
    "cname_suffix_domain": "dnsforemail.com",
    "dns_verified": false,
    "dns_regression": false,
    "dns_records": [
      {
        "bind": "receive.example.com.  IN  MX  10 mx.abc123def456.dnsforemail.com.",
        "type": "MX",
        "name": "receive.example.com",
        "value": "10 mx.abc123def456.dnsforemail.com"
      }
    ],
    "unwanted_dns_records": []
  }
}

Update a Receiving Domain

PUT /ga/api/v3/eng/receiving_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 and cname_suffix_domain are immutable after creation and cannot be changed.

Delete a Receiving Domain

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

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

Deleting a Receiving Domain removes the associated Incoming Email Domain if it has no mailboxes. If the Incoming Email Domain has mailboxes, it is preserved.

Example

DELETE /ga/api/v3/eng/receiving_domains/1

HTTP/1.1 200 OK

{
  "success": true
}

Mailboxes

Once a Receiving Domain’s DNS is verified, GreenArrow provisions an Incoming Email Domain for it. Mailboxes on that domain can be managed through paths scoped to the Receiving Domain, using the Receiving Domain’s numeric ID or domain name as the {id} path parameter.

The {id} may be either the numeric ID or the domain name (case-insensitive). A 404 is returned if the Receiving Domain does not exist, has been deleted, or has not yet been DNS-verified (and therefore has no Incoming Email Domain).

GET    /ga/api/v3/eng/receiving_domains/{id}/mailboxes
GET    /ga/api/v3/eng/receiving_domains/{id}/user_mailboxes
GET    /ga/api/v3/eng/receiving_domains/{id}/forwarding_mailboxes
GET    /ga/api/v3/eng/receiving_domains/{id}/spam_complaint_mailboxes
GET    /ga/api/v3/eng/receiving_domains/{id}/bounce_mailboxes

GET    /ga/api/v3/eng/receiving_domains/{id}/mailboxes/{mailbox_id}

POST   /ga/api/v3/eng/receiving_domains/{id}/user_mailboxes
POST   /ga/api/v3/eng/receiving_domains/{id}/forwarding_mailboxes
POST   /ga/api/v3/eng/receiving_domains/{id}/spam_complaint_mailboxes
POST   /ga/api/v3/eng/receiving_domains/{id}/bounce_mailboxes

PUT    /ga/api/v3/eng/receiving_domains/{id}/mailboxes/{mailbox_id}

DELETE /ga/api/v3/eng/receiving_domains/{id}/mailboxes/{mailbox_id}

These endpoints are equivalent to the corresponding /incoming_email_domains/{domain_id}/... endpoints, scoped to the Incoming Email Domain that was provisioned for this Receiving Domain. Request and response format, parameters, and examples are documented in the Incoming Email Domains API.