For GreenArrow Engine On-Premises, create a DKIM key for the intended signing domain, publish the generated public-key TXT record, and enable the intended signing key. Configure SPF separately at the actual SMTP envelope domain to authorize the real outbound servers. Then test a delivered message: publishing a key, changing the visible From address and setting the Return-Path are three different operations.
This guide includes mail submitted from GreenArrow Studio through Engine. It does not prescribe the same administrative procedure for GreenArrow Cloud. GreenArrow's new-From-domain instructions explicitly target On-Premises customers and direct Cloud customers to Technical Support. GreenArrow's deployment-specific From-domain guide.
On this page: Prerequisites · Create DKIM · Publish DNS · Activate signing · SPF and Return-Path · DMARC · Testing · Troubleshooting · FAQs · Documentation review and testing boundary
Map the sending route before changing DNS
You need an authorized Engine administrator, the DNS administrator for each affected domain, and access to the application or Studio account that submits mail. Save the current DNS records and signing configuration. For an existing sending domain, plan activation and rollback so a new key does not unexpectedly replace a working one.
Document these values for each production route:
| Item | Why it matters |
|---|---|
Visible From: domain |
DMARC protects this author identity |
Optional Sender: header |
Engine's default key selection checks this before From |
| SMTP MAIL FROM / Return-Path domain | Normally determines the SPF policy and bounce route |
Selected DKIM d= and s= |
Determine the signing identity and public-key DNS owner |
| Outbound IPs or upstream relay | SPF must authorize the IP the receiving system actually sees |
| Injection method and Mail Class | Per-message and route settings can change signing or envelope behavior |
| Authoritative DNS zone | A delegated subdomain can have a different DNS owner from its parent |
Keep these distinctions even if all messages use the same brand. Employee mail through Google Workspace, for example, has a separate authentication configuration that must remain authorized if it shares the domain.
GreenArrow Engine can deliver mail through SMTP without requiring a successful SPF, DKIM or DMARC result. Queue acceptance is therefore not an authentication test. Its outbound signing support also should not be confused with inbound SPF/DKIM/DMARC validation, which the vendor's authentication FAQ says Engine does not provide. GreenArrow authentication capabilities.
Create the DKIM key in Engine
In Engine's web interface:
- Open Configure → DKIM Keys.
- Choose Add DKIM Key.
- Enter the intended signing domain in Domain.
- Review the selector, generation/import choice and signing behavior, then save the approved configuration.
- For an authorized existing private key, the documented import path is to clear Generate a new private key and enter that key in Engine. Otherwise, generate a new key through the supported workflow.
Use the actual signing domain, not the SMTP hostname merely because it is convenient. Never publish a private key in DNS or copy the illustrative private key from a manual. GreenArrow DKIM key creation and import.
Select a unique selector and suitable key strength
A selector identifies a key within a signing domain. Engine's documented default name is default, but you can choose another unused selector. Reusing the same selector for two different keys under the same domain causes a collision; reusing a selector name under a different domain is not the same collision. GreenArrow DKIM identity and selection behavior.
Use SHA-256 signing. RFC 8301 prohibits SHA-1 for DKIM and recommends RSA keys of at least 2048 bits. GreenArrow's key-length page still describes its older 1024-bit default/recommendation, while explicitly supporting 2048-bit keys and noting a throughput tradeoff. Do not confuse the documented product default with the current standards recommendation. Check the Bits column, and use your deployment's supported key-generation or import procedure for the chosen strength. RFC 8301 cryptographic requirements; GreenArrow key-length support.
Publish the generated public key
Open Configure → DKIM Keys, locate the key and choose View. Publish the exact TXT record displayed for that key. A newly created key's details page already provides this information. The public value differs by key; do not copy a value from a screenshot. GreenArrow DKIM DNS publication.
The lookup owner has this structure:
SELECTOR._domainkey.SIGNING-DOMAIN
For illustration, s=ga2026 and d=news.example.com require ga2026._domainkey.news.example.com. These are explanatory values, not a deployment recommendation.
| DNS zone being edited | Relative owner for that example |
|---|---|
example.com |
ga2026._domainkey.news |
Separately delegated news.example.com |
ga2026._domainkey |
If your DNS editor expects fully qualified names, use the full owner instead. Inspect the saved record so the zone has not been appended twice. Publishing at ga2026._domainkey.example.com would be wrong for a signature whose d= is news.example.com.
For an already delegated _domainkey.news.example.com namespace, publish the illustrated full TXT owner ga2026._domainkey.news.example.com as relative ga2026 at that authority. Use the actual generated selector and public value, preserving NS delegation and other selectors. Relative DNS names.
Copy the complete generated public value, including the public key. A long TXT value may be represented as several quoted character strings inside one TXT resource record. Do not split one key into multiple competing TXT records, truncate the key, or insert unintended spaces between its encoded segments. DKIM DNS record representation, RFC 6376.
The documented Engine workflow uses a direct TXT record. Do not convert it into an invented hosted CNAME. If the owner already delegates to another service, stop and choose a coordinated new selector or migration: a CNAME cannot coexist with an ordinary TXT record at the same owner. DNS alias constraints.
Activate the intended signing key
Having a public key in DNS does not ensure Engine selects its private counterpart. For the domain's default signing key, open Configure → DKIM Keys → Edit for that key, select Sign mail from this domain with this key by default, and save. Coordinate the switch after the new public key is available, especially on an already active domain. GreenArrow default-key selection.
Check Sender before assuming From controls signing
By default, Engine checks Sender: first. If present, it attempts to use that domain's default key. Without Sender, it uses the From domain for default selection. Explicit configuration or an X-GreenArrow-DKIM instruction can override normal selection.
This distinction matters in Studio too: a configured Sender address can change signing even when the visible From looks correct. For example, a signature for an unrelated agency Sender domain may validate cryptographically but not align with the client's From domain. Inspect the submitted headers and approved signing rules rather than adding a second random key. GreenArrow's default signing behavior.
Raw injection and SimpleMH configurations can use non-default choices. Check route-level overrides when a test signs with an unexpected selector. Avoid casually removing a Sender header if the application relies on it; arrange an aligned signing configuration instead.
If the installation also uses /var/hvmail/control/dkim.json, the vendor documents that the web configuration wins when the same domain/selector pair is defined in both places. Editing the file alone may therefore not change the active key. GreenArrow key configuration precedence.
Configure SPF for the actual envelope domain
There is no universal GreenArrow SPF include in the reviewed On-Premises workflow. SPF is DNS authorization for the actual sending infrastructure, not a software-brand switch. GreenArrow's SPF documentation associates it with the Return-Path and warns against excluding other legitimate senders or creating multiple SPF records. GreenArrow SPF guidance.
1. Establish the envelope domain and real egress
Use the configured SMTP MAIL FROM and confirm it in a delivered message. If mail leaves through another relay, authorize that relay's actual route according to its instructions. Your Engine server's private IP or web-interface address is not automatically the IP the receiver evaluates.
2. Configure bounce handling separately
Adding a DKIM/From domain does not configure the envelope domain. For SimpleMH, installation supplies a default Return-Path. An approved per-message SimpleMH header or a Mail Class's Override Default Bounce Address can select another route. The documented Mail Class option should use a valid bounce mailbox from the incoming-domain configuration. There is also a global SimpleMH configuration option, but errors there can break sending; it is not a routine DKIM setup step. GreenArrow SimpleMH Return-Path options.
Do not type a cosmetic bounce subdomain into a header without configuring the receiving/bounce-processing side. Raw injection follows its own envelope controls, so apply the documentation for the injection method actually in use.
3. Publish or merge the policy at that owner
If the envelope is bounce@returns.example.com, SPF belongs at returns.example.com. A TXT policy only at example.com is not inherited by that subdomain.
For an administrator-controlled direct-sending setup, authorize the confirmed outbound IPv4/IPv6 addresses using the appropriate ip4/ip6 mechanisms. If your organization maintains a supported shared SPF policy, use its approved include rather than inventing one from the GreenArrow name. Retain all other legitimate senders at that same owner and keep the policy's intended final qualifier.
If the existing SPF policy uses redirect=, do not blindly append an all mechanism or a complete canned policy: any all mechanism makes redirect ignored. Preserve the redirect-authorized senders and approved final semantics through a reviewed policy design. SPF redirect semantics.
Publish one v=spf1 TXT record per evaluated hostname. The SPF limit is ten DNS-lookup-causing terms across evaluation, including nested includes, not ten arbitrary TXT records or ten IP addresses. Test the complete policy before rollout. RFC 7208 publication and processing limits.
Do not copy the older Sender ID discussion or DNS-host limitations into a modern SPF change. SPF and DMARC must be evaluated under their current standards.
Preserve DMARC and prove alignment
Keep the domain's existing DMARC policy while fixing the sender. Inspect _dmarc under the visible From domain and the applicable inherited policy. A new subdomain can already be subject to enforcement. Do not publish a second policy, overwrite another reporting service's delegation, or downgrade reject/quarantine to monitoring just to make a test pass.
First inspect the direct TXT policy at _dmarc.YOUR-FROM-DOMAIN and any applicable inherited policy. Only absent both, with owner-approved monitoring, an illustrative first TXT value is v=DMARC1; p=none. It requests no reports unless an authorized monitored rua destination is added. For an owner-approved first monitoring policy only, with no direct or applicable inherited policy to preserve, publish one TXT policy at the actual From domain’s DMARC owner. From example.com uses full owner _dmarc.example.com, or _dmarc relative to the example.com zone. From news.example.com uses full owner _dmarc.news.example.com: enter _dmarc.news in the parent zone, but _dmarc in a separately delegated news.example.com zone. Publish at the actual authority and preserve NS delegation; never create a child monitoring override of existing protection. DMARC policy publication, relative DNS names.
DMARC requires at least one passing mechanism whose domain aligns with the author domain. A successful DKIM signature for the exact From domain supplies strict alignment. Under relaxed alignment, domains sharing the same organizational domain can align. An envelope subdomain may therefore align in relaxed SPF mode but not with aspf=s. A Sender-domain signature unrelated to From does not gain alignment merely because Engine selected it. DMARC alignment and policy discovery, RFC 9989.
For reporting, retain approved rua destinations and check that the reporting system can receive the data. When the destination is outside the policy domain's organizational domain, it needs external-destination authorization in its own DNS. The policy publisher cannot grant that permission by adding a mailbox address alone. Aggregate-report authorization, RFC 9990.
Compare the Organizational Domain of the aggregate report URI’s host with the Organizational Domain of the domain where the DMARC policy was found, not necessarily the visible From domain. If they differ, the report-generating receiver must check DNS authorization. A destination within the same Organizational Domain as that policy domain is excepted; a different hostname alone does not make it external. This protocol check is separate from the domain owner’s approval to share report data with that recipient. RFC 9990 section 4.
Use reports to find every legitimate route before changing policy. One successful Studio test cannot establish that all applications, Mail Classes or failover routes align. DMARC success also does not guarantee acceptance or inbox placement.
Verify DNS and a real Engine message
Public DNS checks
Replace the illustrative owners below with the generated selector, actual signing domain and envelope domain:
dig +short NS example.com
dig +short TXT ga2026._domainkey.news.example.com
dig +short TXT returns.example.com
dig +short TXT _dmarc.news.example.com
dig +short TXT _dmarc.example.com
Compare authoritative and recursive responses. Expect the complete correct DKIM public key, one valid SPF policy at the envelope owner and the intended DMARC policy. A record visible only in an internal DNS zone is not sufficient for public receiving systems.
Sending and receiver checks
After authorization to test, submit a new message through the relevant Studio or Engine route to an external mailbox you control. GreenArrow documents Studio Preview or an Engine injection method for testing. Use the same From, Sender, Mail Class and routing configuration as the production use case; if preview differs, validate the actual production path separately. GreenArrow DKIM testing.
At the recipient, inspect the original message and use that mailbox provider's trusted Authentication-Results. A sender-inserted or unrelated upstream header is not authoritative evidence. RFC 8601 trust boundaries.
Establish which result fields were generated inside the receiving service’s known processing boundary and how it removes or distinguishes externally supplied Authentication-Results. Use its documented handling or ask the receiving administrator if the boundary is unclear. A familiar authserv-id string or header position alone is not proof; reject attacker-supplied or otherwise untrusted fields. Operational result-field trust.
An illustrative acceptance record, not an observed result:
From domain: news.example.com
Sender header: absent, or reviewed for intended selection
DKIM: pass; d=news.example.com; s=ga2026
SPF: pass; smtp.mailfrom=returns.example.com
DMARC: pass; header.from=news.example.com
Alignment: exact DKIM match; SPF assessed against effective aspf mode
Confirm that the successful signature is the intended branded one, not only an unrelated infrastructure signature. Check all signatures if more than one exists. Repeat for each outbound pool or relay whose configuration differs, and verify that bounces still reach the configured processor.
Require the intended branded signature to have trusted dkim=pass and align with the intended unchanged visible From under the effective adkim mode, together with trusted dmarc=pass. SPF-only DMARC success is not completion of this DKIM setup. Diagnose the distinct SPF outcomes below independently even when DKIM supplies DMARC. DMARC alignment.
Safe key rotation
For a routine rotation, introduce a new selector and publish its public key before switching signing. Keep the previous public key available long enough for previously signed messages, queue retries and DNS caches to clear according to your operational plan. GreenArrow's documented replacement sequence waits seven or more days before retiring the old key and also checks non-default-key overrides. Confirm your actual queue and retention requirements before retirement. Do not overwrite a selector's key while old messages still need it. GreenArrow key replacement sequence. A suspected private-key compromise requires an incident-specific revocation plan rather than an automatic reuse of the routine overlap period.
Troubleshooting
| Symptom | Investigation |
|---|---|
| No DKIM signature | Check default activation, actual From/Sender domain, injection overrides and which Engine handled the message. |
| DKIM signature uses the wrong domain | Inspect Sender precedence and explicit signing rules before changing DNS. |
| DKIM key lookup fails | Reconstruct s._domainkey.d from the delivered signature; check the exact zone, spelling and public visibility. |
| DKIM body/signature verification fails | Check key pairing, truncation and modifications after signing, including an upstream relay's footer or content rewriting. |
| UI key differs from a file-defined key | Inspect the same domain/selector in the web configuration, which can take precedence. |
| SPF fails only on some traffic | Compare actual outbound IPs, relay/failover route and envelope domain for passing versus failing messages. |
| SPF and DKIM pass but DMARC fails | Test alignment of each passing identity with From, including strict settings and Sender-selected signatures. |
| Mail is accepted into Engine but later rejected | Read the receiving server's response and receiver results. Injection success did not prove authentication or deliverability. |
For SPF, distinguish fail/softfail (the evaluated policy did not authorize the IP) from none (no usable policy), permerror (such as syntax, multiple policies or lookup-limit problems), and temperror (temporary DNS trouble). Diagnose the evaluated envelope owner. A non-aligned SPF pass is a different problem, usually solved by an appropriate aligned identity rather than adding more IPs.
If a hostname is delegated to another service, or an upstream relay owns the envelope domain, coordinate its correction with that operator. Do not replace a shared delegation with a local TXT record just to satisfy a checker.
Documentation review and testing boundary
No customer Engine installation, private keys, DNS changes, account changes or test messages were used. Treat the generated key and deployment settings as account-specific, and complete the DNS and delivered-message checks before relying on production authentication.