EmailDomainKey

Represents a domain key for an organization’s domain, used to authenticate outbound email that Salesforce sends on the organization’s behalf. This object is available in API version 28.0 and later.

Supported Calls

create()delete()describeSObjects()query()retrieve()update()upsert()

Fields

Field Name Details
Domain
Type
string
Properties
Create, Filter, Group, Sort, Update
Description

The organization’s domain name that the DKIM key is generated for.

DomainMatch
Type
picklist
Properties
Create, Filter, Group, Restricted picklist, Sort, Update
Description
The specificity of match required on the sending domain name before signing with this DKIM key. Valid values are:
  • DomainOnly—Sign if sending domain matches at the domain level only (example.com but not mail.example.com)
  • SubdomainsOnly—Sign if sending domain matches at the subdomain level only (mail.example.com but not example.com)
  • DomainAndSubdomains—Sign if sending domain matches at the domain and subdomain levels (example.com and mail.example.com)
IsActive
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description

Indicates whether this DKIM key is active (true) or not (false). You can set IsActive to true on create if you specify an existing key pair.

PrivateKey
Type
textarea
Properties
Create, Nillable, Update
Description

The private portion of the DKIM key pair used to encrypt mail headers from your domain. Salesforce generates an encrypted PrivateKey if you don’t specify a value when creating the DKIM key. If you do specify a value, it must be an existing valid PrivateKey from another EmailDomainKey object.

This field doesn’t contain the actual private key, but a value that represents the key in our system. Therefore:
  • The actual private key can’t be leaked.
  • You can’t use the value to do your own email signing.
PublicKey
Type
textarea
Properties
Create, Nillable, Update
Description

Part of the domain key pair that mail recipients retrieve to decrypt the DKIM header and verify your domain. Add the PublicKey value to your domain’s DNS records before you start signing with this domain key. Otherwise, mail recipients may reject your email.

Selector
Type
string
Properties
Create, Filter, Group, Sort, Update
Description

Text used to distinguish the DKIM key from any other DKIM keys your organization uses for the specified domain.

Usage

Use this object to define a DomainKeys Identified Mail (DKIM) key, which is used to authenticate outbound email that Salesforce sends on your organization’s behalf. When you create a DKIM key, Salesforce generates a public and private key pair. You must publish the public key in the DNS, which tells recipients that you, as the owner of the domain, have authorized the use of this key to sign your mail. Salesforce uses the private key to create DKIM signature headers on your outgoing email. Then, recipients of the mail, can compare the signature header with the public key in the DNS to determine that the mail was signed with an authorized key. If your domain also publishes a Domain-based Message Authentication, Reporting and Conformance (DMARC) policy, recipients can use the DKIM signature to verify that the mail conforms to DMARC.

For each domain key you create, we recommend this sequence:
  1. Insert the Domain, DomainMatch, and Selector.
  2. Update your domain’s DNS records.
    1. Locate the DNS record at selector._domainkey.domain. For example, mail._domainkey.mail.example.com.
    2. Add the PublicKey value, like this: V=DKIM1; p=public_key.
    DKIM Signing Outbound Email
    1. In addition, you can optionally put the record in testing mode, which instructs recipients to not make decisions based on the email signature. Add parameter t=y to the DNS entry, like this: V=DKIM1; t=y; p=public_key.
  3. Update the key via the API or UI to be active.
Consider the following when using domain keys.
  • Make sure you add the public key to your DNS record before you make your key active in Salesforce and start DKIM signing. DKIM signing is active whenever your DKIM key is in the active state.
  • You can’t have more than one active DKIM key per domain name. You might have multiple active DKIM keys if your organization mails from more than a single domain or if you use subdomains under your organizational domain and have specified domain matching at the subdomain level.
  • If you want to use the same DKIM key for multiple organizations, you can. Create the key and ensure it’s working for one organization first. Then using the API or UI create the key in your other organizations by setting the corresponding fields in the new key to the same values as the original.
  • When you insert or update a DKIM key, it’s possible that the change affects existing domain keys. For example, if you’ve set DomainMatch to DomainAndSubdomains for the example.com domain, and you then set DomainMatch to SubdomainsOnly for the mail.example.com domain, either key could be used. Here’s how we resolve conflicts in the case when DKIM keys overlap.
    • If two keys are equally specific about matching for the same domain, the new key replaces and deactivates the existing key.
    • If a new key is more specific about matching than an existing key, the new key is used and the existing key is modified to inactive.
    • If multiple keys have different domains that match the sending domain, the key with the longest domain name is used. In case of a tie, the most specific key is used. For example, because DomainOnly and SubdomainsOnly are more specific than DomainAndSubdomains, a new DomainOnly key would change the DomainMatch for an existing DomainAndSubdomains key to become SubdomainsOnly. In case of a tie, the most specific key is used.