openapi: 3.2.0 info: description: 'Public REST API for Benchmark Email. Authenticate every request by including your API key in the `X-API-Key` header. Each key is issued with one or more scopes that control which endpoints it may call. Rate limits: 60 requests per minute per account. Monthly quota: determined by your subscription plan.' title: Benchmark Email Email Domain API version: 1.0.0 servers: - description: Your account's API base URL. Copy the full URL shown on Settings > API Keys in your Benchmark Email account and paste it here. url: '{apiBaseUrl}' variables: apiBaseUrl: default: '' description: Your account's API base URL. Copy it from Settings > API Keys in your Benchmark Email account. security: - apiKeyAuth: [] tags: - description: Email domain related endpoints name: email-domain paths: /api/email/domain: get: operationId: get_api_email_domain responses: '200': content: application/json: schema: items: properties: _id: description: Id of the domain type: string createdAt: description: Date of creation type: string dkim: description: DKIM (DomainKeys Identified Mail) configuration (multi-record domains only) properties: records: description: DNS records (CNAME record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object dmarc: description: DMARC (Domain-based Message Authentication, Reporting & Conformance) configuration with status and DNS records (multi-record domains only) properties: records: description: DNS records (TXT record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object domain: description: Domain name type: string identity: description: Domain identity information (not present in multi-record domains - see spf/dkim sections instead) properties: mailFrom: description: Mail-from configuration properties: status: description: Mail-from status type: string subdomain: description: Mail-from subdomain type: string type: object status: description: Identity status (pending, created, verified, failed) type: string verificationInfo: description: Verification status and details properties: errorCode: description: Error code if verification failed type: string lastCheckedAt: description: Timestamp of last verification check format: date-time type: string lastRecordFound: description: DKIM CNAME value from the most recent diagnostic DNS lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' lastSuccessAt: description: Timestamp of last successful verification format: date-time type: string type: object verificationStatus: description: Overall verification status type: string type: object isReadyForSending: description: Is the domain ready for sending type: boolean lastCheckedAt: description: Date of last domain verification type: string linkTracking: description: Link tracking configuration with status and DNS records (multi-record domains only) properties: records: description: DNS records (CNAME record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object nameServer: description: Name server for the domain type: string provider: description: Domain provider type: string spf: description: SPF (Sender Policy Framework) configuration with mail-from records (multi-record domains only) properties: records: description: DNS records (MX and TXT records) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Mail-from verification details properties: lastRecordFound: description: DNS record values from the most recent diagnostic lookup properties: mx: description: MX exchange hostname found at bounces.{domain}. null if no record found. maxLength: 512 type: - string - 'null' txt: description: SPF TXT record value found at bounces.{domain}. null if no record found. maxLength: 512 type: - string - 'null' type: - object - 'null' type: object type: object sslCertStatus: description: SSL certificate status (pending, created, renewed, expired, failed) type: string status: description: Status of the domain (verifying, verified) type: string type: description: Type of the domain (private, grey-label, multi-record) type: string updatedAt: description: Date of update type: string validationResults: items: properties: checkedAt: description: Date of last domain verification type: string code: description: Code of the validation result type: string description: description: Description of the validation result type: string domainInfo: properties: authorities: description: Authorities of the DNS record for the domain. items: type: string type: array domainFirstRecord: description: First record found for the domain properties: ttl: description: TTL of the DNS record type: number type: description: Type of the DNS record type: string value: description: Value of the DNS record type: string type: object parentDomain: description: Parent domain name type: string parentNameServers: description: Parent name servers items: type: string type: array resultRecord: description: Result of the DNS record validation properties: type: description: Type of the DNS record (NS, MX, A, CNAME, etc.) type: string value: description: Value of the DNS record type: string type: object validType: description: Indicates if the DNS record is valid type type: boolean validValue: description: Indicates if the DNS record is valid value type: boolean type: object result: description: Result of the validation type: string type: object type: array type: object type: array description: Successfully fetched '401': description: Unauthorized security: - apiKeyAuth: [] summary: Get all domains tags: - email-domain x-api-key-scope: domains:read /api/email/domain/grey-label: get: operationId: get_api_email_domain_grey_label responses: '200': content: application/json: schema: properties: _id: description: Id of the domain type: string createdAt: description: Date of creation type: string dkim: description: DKIM (DomainKeys Identified Mail) configuration (multi-record domains only) properties: records: description: DNS records (CNAME record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object dmarc: description: DMARC (Domain-based Message Authentication, Reporting & Conformance) configuration with status and DNS records (multi-record domains only) properties: records: description: DNS records (TXT record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object domain: description: Domain name type: string identity: description: Domain identity information (not present in multi-record domains - see spf/dkim sections instead) properties: mailFrom: description: Mail-from configuration properties: status: description: Mail-from status type: string subdomain: description: Mail-from subdomain type: string type: object status: description: Identity status (pending, created, verified, failed) type: string verificationInfo: description: Verification status and details properties: errorCode: description: Error code if verification failed type: string lastCheckedAt: description: Timestamp of last verification check format: date-time type: string lastRecordFound: description: DKIM CNAME value from the most recent diagnostic DNS lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' lastSuccessAt: description: Timestamp of last successful verification format: date-time type: string type: object verificationStatus: description: Overall verification status type: string type: object isReadyForSending: description: Is the domain ready for sending type: boolean lastCheckedAt: description: Date of last domain verification type: string linkTracking: description: Link tracking configuration with status and DNS records (multi-record domains only) properties: records: description: DNS records (CNAME record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object nameServer: description: Name server for the domain type: string provider: description: Domain provider type: string spf: description: SPF (Sender Policy Framework) configuration with mail-from records (multi-record domains only) properties: records: description: DNS records (MX and TXT records) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Mail-from verification details properties: lastRecordFound: description: DNS record values from the most recent diagnostic lookup properties: mx: description: MX exchange hostname found at bounces.{domain}. null if no record found. maxLength: 512 type: - string - 'null' txt: description: SPF TXT record value found at bounces.{domain}. null if no record found. maxLength: 512 type: - string - 'null' type: - object - 'null' type: object type: object sslCertStatus: description: SSL certificate status (pending, created, renewed, expired, failed) type: string status: description: Status of the domain (verifying, verified) type: string type: description: Type of the domain (private, grey-label, multi-record) type: string updatedAt: description: Date of update type: string type: object description: Successfully fetched '404': description: Not found security: - apiKeyAuth: [] summary: Get the grey label domain for the account tags: - email-domain x-api-key-scope: domains:read /api/email/domain/{domainId}: get: operationId: get_api_email_domain_by_domainId parameters: - in: path name: domainId required: true schema: type: string responses: '200': content: application/json: schema: properties: _id: description: Id of the domain type: string createdAt: description: Date of creation type: string dkim: description: DKIM (DomainKeys Identified Mail) configuration (multi-record domains only) properties: records: description: DNS records (CNAME record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object dmarc: description: DMARC (Domain-based Message Authentication, Reporting & Conformance) configuration with status and DNS records (multi-record domains only) properties: records: description: DNS records (TXT record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object domain: description: Domain name type: string identity: description: Domain identity information (not present in multi-record domains - see spf/dkim sections instead) properties: mailFrom: description: Mail-from configuration properties: status: description: Mail-from status type: string subdomain: description: Mail-from subdomain type: string type: object status: description: Identity status (pending, created, verified, failed) type: string verificationInfo: description: Verification status and details properties: errorCode: description: Error code if verification failed type: string lastCheckedAt: description: Timestamp of last verification check format: date-time type: string lastRecordFound: description: DKIM CNAME value from the most recent diagnostic DNS lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' lastSuccessAt: description: Timestamp of last successful verification format: date-time type: string type: object verificationStatus: description: Overall verification status type: string type: object isReadyForSending: description: Is the domain ready for sending type: boolean lastCheckedAt: description: Date of last domain verification type: string linkTracking: description: Link tracking configuration with status and DNS records (multi-record domains only) properties: records: description: DNS records (CNAME record) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Verification details properties: errorCode: description: Error code if verification failed type: string lastRecordFound: description: Raw DNS record value from the most recent verification lookup. null if no record was found. Absent if never checked. maxLength: 512 type: - string - 'null' type: object type: object nameServer: description: Name server for the domain type: string provider: description: Domain provider type: string spf: description: SPF (Sender Policy Framework) configuration with mail-from records (multi-record domains only) properties: records: description: DNS records (MX and TXT records) items: properties: name: description: DNS record name type: string ttl: description: Time to live in seconds type: number type: description: DNS record type (MX, TXT, CNAME) type: string value: description: DNS record value type: string type: object type: array status: description: Verification status (pending, success) type: string verificationInfo: description: Mail-from verification details properties: lastRecordFound: description: DNS record values from the most recent diagnostic lookup properties: mx: description: MX exchange hostname found at bounces.{domain}. null if no record found. maxLength: 512 type: - string - 'null' txt: description: SPF TXT record value found at bounces.{domain}. null if no record found. maxLength: 512 type: - string - 'null' type: - object - 'null' type: object type: object sslCertStatus: description: SSL certificate status (pending, created, renewed, expired, failed) type: string status: description: Status of the domain (verifying, verified) type: string type: description: Type of the domain (private, grey-label, multi-record) type: string updatedAt: description: Date of update type: string validationResults: items: properties: checkedAt: description: Date of last domain verification type: string code: description: Code of the validation result type: string description: description: Description of the validation result type: string domainInfo: properties: authorities: description: Authorities of the DNS record for the domain. items: type: string type: array domainFirstRecord: description: First record found for the domain properties: ttl: description: TTL of the DNS record type: number type: description: Type of the DNS record type: string value: description: Value of the DNS record type: string type: object parentDomain: description: Parent domain name type: string parentNameServers: description: Parent name servers items: type: string type: array resultRecord: description: Result of the DNS record validation properties: type: description: Type of the DNS record (NS, MX, A, CNAME, etc.) type: string value: description: Value of the DNS record type: string type: object validType: description: Indicates if the DNS record is valid type type: boolean validValue: description: Indicates if the DNS record is valid value type: boolean type: object result: description: Result of the validation type: string type: object type: array type: object description: Successfully fetched '401': description: Unauthorized '404': description: Not found security: - apiKeyAuth: [] summary: Get a domain by id tags: - email-domain x-api-key-scope: domains:read components: securitySchemes: apiKeyAuth: description: API key authentication in: header name: X-API-Key type: apiKey