{ "openapi": "3.0.0", "info": { "title": "EasyDMARC API", "version": "1.0.0", "description": "EasyDMARC Public API Documentation", "contact": { "name": "EasyDMARC", "url": "https://easydmarc.com" }, "x-logo": { "url": "https://easydmarc.com/img/logo.png", "backgroundColor": "#FFFFFF", "altText": "EasyDMARC" } }, "tags": [ { "name": "Authentication", "x-displayName": "Authentication" }, { "name": "Domains", "x-displayName": "Domains" }, { "name": "Alerting", "x-displayName": "Alerting" }, { "name": "DNS Lookup", "x-displayName": "DNS Lookup" }, { "name": "Aggregate Reports", "x-displayName": "Aggregate Reports" }, { "name": "Failure Reports", "x-displayName": "Failure Reports" }, { "name": "Organizations", "x-displayName": "Organizations" }, { "name": "Billing - Subscriptions & Pricing", "x-displayName": "Billing - Subscriptions & Pricing" }, { "name": "Users", "x-displayName": "Users" }, { "name": "DnsCore", "x-displayName": "DnsCore" } ], "paths": { "/v1/domains/overview": { "servers": [], "post": { "tags": [ "Domains" ], "summary": "List domains with the domain details", "description": "", "operationId": "getDomainsOverview", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "$ref": "#/components/schemas/OrganizationIdField" }, "startDate": { "type": "string", "description": "Start Date" }, "endDate": { "type": "string", "description": "End Date" }, "page": { "type": "number" }, "pageSize": { "type": "number", "default": 1 }, "filters": { "description": "Filter conditions for the search.", "oneOf": [ { "$ref": "#/components/schemas/FilterCondition" }, { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } } ] } } } } } }, "responses": { "200": { "description": "Successful response with a list of domains", "content": { "application/json": { "schema": { "type": "object", "title": "GetDomainsOk", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DomainOverview" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/domains": { "servers": [], "post": { "tags": [ "Domains" ], "summary": "Create new domain", "operationId": "createDomain", "requestBody": { "description": "Request payload for creating one or more domains.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string" }, "domain": { "type": "string" }, "type": { "type": "string" }, "groupId": { "type": "string" } }, "x-examples": { "Example 1": { "organizationId": "org_68267af02750d5671394546e", "domain": "lurline.info", "type": "sending", "groupId": "dmngrp_68267f052750d56713945475" } } }, "examples": { "Example 1": { "value": { "organizationId": "org_68267af02750d5671394546e", "domain": "lurline.info", "type": "sending", "groupId": "dmngrp_68267f052750d56713945475" } } } } } }, "responses": { "201": { "description": "Domain created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" }, "examples": { "success": { "value": { "domain": "anderson.biz", "domainVerified": false, "type": "sending", "policy": "missing", "logoUrl": "http://company.com/favicon.png", "domainGroup": "group1", "domainGroupId": "dmngrp_42517f052750d56713945475" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "get": { "tags": [ "Domains" ], "summary": "List domains", "operationId": "getDomains", "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/pageSize" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/Domain" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "examples": { "Example 1": { "value": { "data": [ { "domain": "easydmarc.com", "domainVerified": false, "type": "sending", "policy": "reject", "logoUrl": "https://assets.easydmarc.com/favicons/2025-04/easydmarc_1744732732290.png", "domainGroup": "Default Group", "domainGroupId": "dmngrp_34267f052750d56713945475" }, { "domain": "easydmarc.corg", "domainVerified": false, "type": "sending", "policy": "reject", "logoUrl": "https://assets.easydmarc.com/favicons/2025-04/easydmarc_1744732732290.png", "domainGroup": "Default Group", "domainGroupId": "dmngrp_56267f052750d56713945475" } ], "meta": { "total": 2, "page": 1, "pageCount": 1, "limit": 20, "hasPreviousPage": false, "hasNextPage": false } } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/domains/batch": { "servers": [], "post": { "tags": [ "Domains" ], "summary": "Create new domains in batch", "operationId": "createDomainsBatch", "requestBody": { "description": "Request payload for creating one or more domains.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string" }, "domains": { "type": "array", "items": { "type": "object", "properties": { "domainName": { "type": "string" }, "type": { "type": "string" }, "groupId": { "type": "string" } }, "required": [ "domainName", "type", "groupId" ] } } }, "required": [ "organizationId", "domains" ], "x-examples": { "Example 1": { "organizationId": "org_6825fd937307b513490da37c", "domains": [ { "domainName": "domain1.com", "type": "sending", "groupId": "dmngrp_682b42fc6ef3ac50b4ca4fce" }, { "domainName": "domain2.com", "type": "parked", "groupId": "dmngrp_682b42d86ef3ac50b4ca4fcd" } ] } } }, "examples": { "single": { "value": { "organizationId": "org_6825fd937307b513490da37c", "domains": [ { "type": "sending", "groupId": "dmngrp_682b42fc6ef3ac50b4ca4fce", "domainName": "example.com" } ] } }, "multiple": { "value": { "organizationId": "org_6825fd937307b513490da37c", "domains": [ { "domainName": "domain1.com", "type": "sending", "groupId": "dmngrp_682b42fc6ef3ac50b4ca4fce" }, { "domainName": "domain2.com", "type": "parked", "groupId": "dmngrp_682b42d86ef3ac50b4ca4fcd" } ] } } } } } }, "responses": { "201": { "description": "Domain created successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "examples": { "success": { "value": [ { "domains": [ { "domain": "jermey.com", "domainVerified": false, "type": "sending", "policy": "missing", "logoUrl": "https://dev-assets.easydmarc.com/favicons/2025-05/jermey_1747354403003.png", "domainGroup": "group1", "domainGroupId": "dmngrp_62587f052750d56713945475" }, { "domain": "iva.com", "domainVerified": false, "type": "sending", "policy": "missing", "logoUrl": "", "domainGroup": "group1", "domainGroupId": "dmngrp_53627f052750d56713945475" } ] } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/domains/{domain}": { "servers": [], "get": { "tags": [ "Domains" ], "summary": "Get domain by ID", "operationId": "getDomainById", "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response with domain details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "put": { "tags": [ "Domains" ], "summary": "Update an existing domain", "operationId": "updateDomain", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Domain update payload. All fields must be provided.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainRequest" }, "examples": { "default": { "value": { "organizationId": "00000000-0000-0000-0000-000000000000", "type": "sending", "groupId": "ab34-c624-bc7b-7820-c8a9-cd4f-e910-3b23", "domain": "example.com" } } } } } }, "responses": { "200": { "description": "Domain updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ], "x-internal": true }, "patch": { "tags": [ "Domains" ], "summary": "Partially update a domain", "operationId": "patchDomain", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Partial update payload for the domain.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domainName": { "type": "string" }, "type": { "$ref": "#/components/schemas/DomainType" }, "groupId": { "type": "string" } } }, "examples": { "default": { "value": { "groupId": "new-group-123", "domainName": "example.com" } } } } } }, "responses": { "200": { "description": "Domain partially updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "delete": { "tags": [ "Domains" ], "summary": "Delete a domain", "operationId": "deleteDomain", "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Domain deleted successfully" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/domains/{domain}/setup": { "servers": [], "get": { "tags": [ "Domains" ], "summary": "Get setup info", "description": "Returns the DMARC record to be added to DNS\n\nSet up a DMARC record in the DNS provider account. \n\nNote: DNS propagation may take up to several hours.\n", "operationId": "get-domains-domain-setup", "parameters": [ { "name": "type", "in": "query", "description": "Record type, CNAME or TXT", "required": true, "schema": { "type": "string", "enum": [ "CNAME", "TXT" ], "examples": [ "CNAME" ] } }, { "$ref": "#/components/parameters/organizationId" }, { "name": "domain", "in": "path", "description": "Domain name", "required": true, "schema": { "type": "string", "examples": [ "domain1.com" ] } } ], "responses": { "200": { "description": "Generated DMARC record", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "examples": [ "_dmarc.domain1.com" ] }, "type": { "type": "string", "enum": [ "cname", "txt" ], "default": "txt", "examples": [ "cname" ] }, "value": { "type": "string", "examples": [ "_dmarc.domain1_com._d.easydmarc.com" ] } }, "required": [ "host", "type", "value" ] }, "examples": { "Example 1": { "value": { "host": "_dmarc.domain1.com", "type": "txt", "value": "v=DMARC1;p=none;rua=mailto:4cc3eb3955@dev-rua.easydmarc.com;ruf=mailto:4cc3eb3955@dev-rua.easydmarc.com;fo=1;" } }, "Example 2": { "value": { "host": "_dmarc.domain2.com", "type": "cname", "value": "_dmarc.domain2_com._d.easydmarc.com" } } } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "post": { "tags": [ "Domains" ], "summary": "Verify domain", "description": "Not available yet", "operationId": "post-domains-domain-setup", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "managed": { "type": "boolean" }, "tags": { "type": "object" } } } } } }, "responses": {}, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/domains/search": { "servers": [], "post": { "tags": [ "Domains" ], "summary": "🚧 Search and filter domains with advanced filtering and ordering", "operationId": "searchDomains", "requestBody": { "description": "Domain search request payload including filters, ordering, pagination, and requested properties.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainSearchRequest" }, "examples": { "basic": { "value": { "organizationId": "00000000-0000-0000-0000-000000000000", "page": 1, "order": [ { "orderBy": "volume", "direction": "desc" } ], "filter": { "operator": "AND", "conditions": [ { "field": "status", "value": "active", "operator": "eq" } ] }, "domains": [ "example.com", "example.org" ], "pageSize": 50, "properties": [ "domainName", "volume", "dmarc" ] } } } } } }, "responses": { "200": { "description": "A list of domains matching the search criteria.", "content": { "application/json": { "schema": { "type": "object", "title": "SearchDomainsOk", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DomainOverview" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/domain-groups": { "servers": [], "get": { "tags": [ "Domains" ], "summary": "List domain groups", "operationId": "listDomainGroups", "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "$ref": "#/components/parameters/pageSize" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Successful response with a list of domain groups.", "content": { "application/json": { "schema": { "type": "object", "title": "GetDomainGroupsOk", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DomainGroup" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "examples": { "success": { "value": { "data": [ { "id": "00000000-0000-0000-0000-000000000000", "name": "Group 1", "domains": [ "domain1.com", "domain2.com", "domain3.com" ] } ], "meta": { "pageSize": 10, "page": 1, "total": 1 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "post": { "tags": [ "Domains" ], "summary": "Create a new domain group", "operationId": "createDomainGroup", "requestBody": { "description": "Domain group creation payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainGroupRequest" }, "examples": { "default": { "value": { "id": "00000000-0000-0000-0000-000000000000", "organizationId": "org_68231dcfeb8e9f092a052b88", "name": "Group 1", "domains": [ "domain1.com", "domain2.com" ] } } } } } }, "responses": { "201": { "description": "Domain group created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainGroup" }, "examples": { "default": { "value": { "id": "00000000-0000-0000-0000-000000000000", "name": "Group 1", "domains": [ "domain1.com", "domain2.com", "domain3.com" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Too Many Requests" }, "500": { "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/domain-groups/{id}": { "servers": [], "get": { "tags": [ "Domains" ], "summary": "Get domain group details", "operationId": "getDomainGroupById", "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response with domain group details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainGroup" }, "examples": { "default": { "value": { "id": "00000000-0000-0000-0000-000000000000", "name": "Group 1", "domains": [ "domain1.com", "domain2.com", "domain3.com" ] } } } } } }, "403": { "description": "Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "put": { "tags": [ "Domains" ], "summary": "Update an existing domain group", "operationId": "updateDomainGroup", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Domain group update payload.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } }, "examples": { "default": { "value": { "policy": "reject", "spf_record": "v=spf1 include:example.com ~all", "bimi_record": "v=BIMI1; l=https://example.com/logo.svg", "dmarc_record": "v=DMARC1; p=reject", "favicon_path": "https://example.com/favicon.ico", "has_easy_spf": false, "total_volume": 1600, "domain_labels": "label1, label2", "spf_pass_rate": 99, "dkim_pass_rate": 97, "dkim_selectors": "default", "partner_owners": "Partner Inc.", "compliance_rate": 96, "group_object_id": "group-a", "compliant_volume": 1500, "has_managed_bimi": false, "has_managed_dkim": true, "domain_group_name": "Group A Updated", "has_managed_dmarc": true, "is_domain_verified": true, "has_managed_mta_sts": false, "non_compliant_volume": 100, "possible_dkim_selectors": "default", "previous_compliant_volume": 1400, "previous_non_compliant_volume": 200 } } } } } }, "responses": { "200": { "description": "Domain group updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainGroup" }, "examples": { "default": { "value": { "id": "00000000-0000-0000-0000-000000000000", "name": "Group 1", "domains": [ "domain1.com", "domain2.com", "domain3.com" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "delete": { "tags": [ "Domains" ], "summary": "Delete a domain group", "operationId": "deleteDomainGroup", "parameters": [ { "$ref": "#/components/parameters/organizationId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Domain group deleted successfully" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/domain-groups/{id}/domains": { "servers": [], "post": { "tags": [ "Domains" ], "summary": "🚧 Add domains to a domain group", "operationId": "addDomainsToGroup", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "List of domains to add to the group.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ] }, "examples": { "default": { "value": { "domains": [ "example1.com", "example2.com" ] } } } } } }, "responses": { "200": { "description": "Domains added to the group successfully", "content": { "application/json": { "schema": { "type": "object", "title": "AddDomainsToGroupOk", "properties": { "groupId": { "type": "string" }, "groupName": { "type": "string" }, "domainsAdded": { "type": "array", "items": { "type": "string" } } } }, "examples": { "default": { "value": { "groupId": "group-a", "groupName": "Group A", "domainsAdded": [ "example1.com", "example2.com" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ], "x-internal": true } }, "/v1/domain-groups/{id}/domains/{domainId}": { "servers": [], "delete": { "tags": [ "Domains" ], "summary": "Remove a domain from a domain group", "operationId": "deleteDomain1", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domainId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Domain removed from group successfully" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ], "x-internal": true } }, "/v1/webhooks": { "servers": [], "post": { "tags": [ "Alerting" ], "summary": "Create a new webhook", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "The webhook has been successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "422": { "description": "Validation failed" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/webhooks/owner/{ownerId}": { "servers": [], "get": { "tags": [ "Alerting" ], "summary": "Get webhook list for specific owner", "operationId": "findAllWebhooks", "parameters": [ { "name": "ownerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns all owned webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "404": { "description": "Owner not found or no webhooks exist for this owner" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/webhooks/{id}": { "servers": [], "get": { "tags": [ "Alerting" ], "summary": "Get a specific webhook", "operationId": "getWebhookByObjectId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "put": { "tags": [ "Alerting" ], "summary": "Update a webhook", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "path", "description": "Webhook object ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "The webhook has been successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "422": { "description": "Validation failed" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] }, "delete": { "tags": [ "Alerting" ], "summary": "Delete a webhook", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "description": "Webhook object ID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The webhook has been successfully deleted" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/webhooks/{id}/regenerate-secret": { "servers": [], "post": { "tags": [ "Alerting" ], "summary": "Regenerate webhook secret", "operationId": "regenerateSecret", "parameters": [ { "name": "id", "in": "path", "description": "Webhook object ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The webhook secret has been successfully regenerated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/webhooks/{id}/deliveries": { "servers": [], "get": { "tags": [ "Alerting" ], "summary": "Get the list of webhook deliveries", "operationId": "getWebhookDeliveries", "parameters": [ { "name": "id", "in": "path", "description": "Webhook object ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns webhook delivery history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/dmarc/failure-reports": { "servers": [], "get": { "tags": [ "Failure Reports" ], "summary": "Get failure reports", "description": "Returns a paginated list of DMARC RUF (failure/forensic) reports with comprehensive filtering and sorting capabilities. Authentication required. Response is paginated.", "operationId": "getFailureReports", "parameters": [ { "name": "organizationId", "in": "query", "description": "Organization ID to filter reports by", "required": true, "schema": { "type": "string", "maxLength": 255, "examples": [ "org_6464de38ebf5b013b1928408" ] } }, { "name": "domains", "in": "query", "description": "Comma-separated list of domain names to filter reports by (minimum 1 required)", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?)*\\.[a-zA-Z]{2,}(,[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?)*\\.[a-zA-Z]{2,})*$", "examples": [ "example.com,test.com" ] } }, { "name": "reportDate", "in": "query", "description": "Filter by specific report date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time", "examples": [ "2024-01-15T00:00:00Z" ] } }, { "name": "sourceIp", "in": "query", "description": "Filter by source IPv4 address", "required": false, "schema": { "type": "string", "format": "ipv4", "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$", "examples": [ "192.168.1.100" ] } }, { "name": "countryCode", "in": "query", "description": "Filter by country code (ISO 3166-1 alpha-2)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "examples": [ "US" ] } }, { "name": "reporterDomain", "in": "query", "description": "Filter by reporter domain (FQDN)", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?)*\\.[a-zA-Z]{2,}$", "examples": [ "reporter.com" ] } }, { "name": "ptr", "in": "query", "description": "Filter by PTR record (must be \"Unknown\" or a valid domain)", "required": false, "schema": { "type": "string", "examples": [ "mail.example.com" ] } }, { "name": "ptrGroup", "in": "query", "description": "Filter by PTR group (must be \"Unknown\" or a valid domain)", "required": false, "schema": { "type": "string", "examples": [ "example.com" ] } }, { "name": "dateFrom", "in": "query", "description": "Filter reports from this date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time", "examples": [ "2024-01-01T00:00:00Z" ] } }, { "name": "dateTo", "in": "query", "description": "Filter reports until this date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time", "examples": [ "2024-01-31T23:59:59Z" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination (1-based)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "examples": [ 1 ] } }, { "name": "pageSize", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10, "examples": [ 50 ] } }, { "name": "field", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "enum": [ "report_id", "domain", "header_from", "from", "to", "subject", "date", "headers_eml", "report_domain", "report_from", "report_subject", "report_email_body", "report_email_body_urls", "report_date", "source_ip", "ptr", "ptr_group", "country_code", "created" ], "default": "date", "examples": [ "report_date" ] } }, { "name": "direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "examples": [ "desc" ] } } ], "responses": { "200": { "description": "Returns paginated list of failure reports", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FailureReportListItem" } } } } ] }, "examples": { "success_response": { "summary": "Successful response with failure reports", "value": { "data": [ { "id": "507f1f77bcf86cd799439011", "domain": "example.com", "sourceIp": "192.168.1.100", "ptr": "mail.sender.com", "ptrGroup": "sender.com", "countryCode": "US", "reportDate": "2024-01-15T10:30:00Z", "reporter": "reporter.com", "fromAddress": "sender@example.com", "toAddress": "recipient@example.com", "subject": "Important Message", "attachmentCount": 2 }, { "id": "507f1f77bcf86cd799439012", "domain": "test.com", "sourceIp": "10.0.0.50", "ptr": "Unknown", "ptrGroup": "Unknown", "countryCode": "GB", "reportDate": "2024-01-15T11:45:00Z", "reporter": "another-reporter.com", "fromAddress": "user@test.com", "toAddress": "info@test.com", "subject": "Test Email", "attachmentCount": 0 } ], "meta": { "total": 245, "page": 1, "pageCount": 1, "limit": 10, "hasPreviousPage": true, "hasNextPage": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/dmarc/failure-reports/{id}": { "servers": [], "get": { "tags": [ "Failure Reports" ], "summary": "Get failure report by ID", "description": "Retrieves detailed information about a single DMARC failure report by its unique identifier. Authentication required.", "operationId": "getFailureReportById", "parameters": [ { "name": "organizationId", "in": "query", "description": "Organization ID", "required": true, "schema": { "type": "string", "maxLength": 255, "examples": [ "org_6464de38ebf5b013b1928408" ] } }, { "name": "include", "in": "query", "description": "Comma-separated list of optional fields to include in the response.\nAvailable options: rawHeaders, emailBody, addresses, downloadUrls", "required": false, "schema": { "type": "string", "pattern": "^(rawHeaders|emailBody|addresses|downloadUrls)(,(rawHeaders|emailBody|addresses|downloadUrls))*$", "examples": [ "rawHeaders,emailBody,downloadUrls" ] } }, { "name": "redaction", "in": "query", "description": "Redaction level for sensitive information", "required": false, "schema": { "type": "string", "enum": [ "strict", "none" ], "default": "strict", "examples": [ "strict" ] } }, { "name": "id", "in": "path", "description": "The MongoDB ObjectId of the failure report", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$", "examples": [ "507f1f77bcf86cd799439011" ] } } ], "responses": { "200": { "description": "Returns detailed failure report metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailureReportMetadata" }, "examples": { "complete_report": { "summary": "Complete report with all fields", "value": { "id": "507f1f77bcf86cd799439011", "domain": "example.com", "receivedAt": "2024-01-15T10:30:00Z", "message": { "from": "sender@example.com", "to": "recipient@example.com", "subject": "Important Message", "headerFrom": "sender@example.com", "sourceIp": "192.168.1.100", "ptr": "mail.sender.com", "ptrGroup": "sender.com", "emailBody": "This is the email body content...", "rawHeaders": "Received: from mail.sender.com...", "extractedUrls": [ "https://example.com/link1", "https://example.com/link2" ], "attachments": [ { "cloud": "s3", "bucket": "ruf-reports", "key": "attachments/507f1f77bcf86cd799439011/0/document.pdf", "filename": "document.pdf", "contentType": "application/pdf", "size": 102400 } ] }, "reportMetadata": { "reportId": "report-12345", "reporterDomain": "reporter.com", "reportedBy": "noreply@reporter.com", "reportSubject": "DMARC Failure Report", "reportEmailBody": "This message failed DMARC authentication...", "reportDate": "2024-01-15T10:30:00Z", "countryCode": "US", "location": { "coordinates": [ -74.006, 40.7128 ] } }, "downloadLinks": { "emlFile": "https://api2.easydmarc.com/v1.0/dmarc/failure-reports/reports/507f1f77bcf86cd799439011/eml?organizationId=org_6464de38ebf5b013b1928408", "attachments": [ { "cloud": "s3", "bucket": "ruf-reports", "key": "attachments/507f1f77bcf86cd799439011/0/document.pdf", "downloadUrl": "https://api2.easydmarc.com/v1.0/dmarc/failure-reports/reports/507f1f77bcf86cd799439011/attachments/0?organizationId=org_6464de38ebf5b013b1928408" } ], "allAttachmentsZip": "https://api2.easydmarc.com/v1.0/dmarc/failure-reports/reports/507f1f77bcf86cd799439011/attachments/all?organizationId=org_6464de38ebf5b013b1928408" } } }, "with_presigned_urls": { "summary": "Report with presigned download URLs", "value": { "id": "507f1f77bcf86cd799439011", "domain": "example.com", "receivedAt": "2024-01-15T10:30:00Z", "message": { "from": "sender@example.com", "to": "recipient@example.com", "subject": "Important Message", "headerFrom": "sender@example.com", "sourceIp": "192.168.1.100", "ptr": "mail.sender.com", "ptrGroup": "sender.com", "attachments": [ { "cloud": "s3", "bucket": "ruf-reports", "key": "attachments/507f1f77bcf86cd799439011/0/document.pdf", "filename": "document.pdf", "contentType": "application/pdf", "size": 102400 } ] }, "reportMetadata": { "reportId": "report-12345", "reporterDomain": "reporter.com", "reportedBy": "noreply@reporter.com", "reportSubject": "DMARC Failure Report", "reportDate": "2024-01-15T10:30:00Z", "countryCode": "US" }, "presignedDownloadLinks": { "emlFile": "https://s3.amazonaws.com/ruf-reports/eml/report-12345?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...", "attachments": [ { "cloud": "s3", "bucket": "ruf-reports", "key": "attachments/507f1f77bcf86cd799439011/0/document.pdf", "presignedUrl": "https://s3.amazonaws.com/ruf-reports/attachments/507f1f77bcf86cd799439011/0/document.pdf?X-Amz-Algorithm=...", "expiresAt": "2024-01-15T10:35:00Z" } ], "allAttachmentsZip": "https://s3.amazonaws.com/ruf-reports/zip/report-12345/all-attachments.zip?X-Amz-Algorithm=..." } } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "example": "no-store, private" }, "description": "Cache control header (set to 'no-store, private' when downloadUrls are included)" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/dmarc/failure-reports/{id}/eml": { "servers": [], "get": { "tags": [ "Failure Reports" ], "summary": "Download EML file for a failure report", "description": "Generates a presigned download URL for the original EML (email message) file associated with a failure report.\n\nThe URL is valid for 300 seconds (5 minutes) and must be used before expiration.\n\nAuthentication required.", "operationId": "downloadEml", "parameters": [ { "name": "organizationId", "in": "query", "description": "Organization ID", "required": true, "schema": { "type": "string", "maxLength": 255, "examples": [ "org_6464de38ebf5b013b1928408" ] } }, { "name": "id", "in": "path", "description": "The MongoDB ObjectId of the failure report", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$", "examples": [ "507f1f77bcf86cd799439011" ] } } ], "responses": { "200": { "description": "Returns presigned download URL for EML file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadUrlResponse" }, "examples": { "eml_download": { "summary": "EML download URL", "value": { "data": { "downloadUrl": "https://s3.amazonaws.com/ruf-reports/ruf-eml/report-12345?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...", "expiresAt": "2024-01-15T10:35:00Z" } } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "example": "no-store, private" }, "description": "Cache control header" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/dmarc/failure-reports/{id}/attachments/{index}": { "servers": [], "get": { "tags": [ "Failure Reports" ], "summary": "Download specific attachment from a failure report", "description": "Generates a presigned download URL for a specific attachment from a failure report.\n\nThe URL is valid for 300 seconds (5 minutes) and must be used before expiration.\nAttachment index is 0-based.\n\nAuthentication required.", "operationId": "downloadAttachment", "parameters": [ { "name": "organizationId", "in": "query", "description": "Organization ID", "required": true, "schema": { "type": "string", "maxLength": 255, "examples": [ "org_6464de38ebf5b013b1928408" ] } }, { "name": "id", "in": "path", "description": "The MongoDB ObjectId of the failure report", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$", "examples": [ "507f1f77bcf86cd799439011" ] } }, { "name": "index", "in": "path", "description": "Zero-based index of the attachment to download", "required": true, "schema": { "type": "integer", "minimum": 0, "examples": [ 0 ] } } ], "responses": { "200": { "description": "Returns presigned download URL for the attachment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadUrlResponse" }, "examples": { "attachment_download": { "summary": "Attachment download URL", "value": { "data": { "downloadUrl": "https://s3.amazonaws.com/ruf-reports/attachments/507f1f77bcf86cd799439011/0/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...", "expiresAt": "2024-01-15T10:35:00Z" } } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "example": "no-store, private" }, "description": "Cache control header" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/dmarc/failure-reports/{id}/attachments/all": { "servers": [], "get": { "tags": [ "Failure Reports" ], "summary": "Download all attachments as a ZIP archive", "description": "Generates a presigned download URL for a ZIP archive containing all attachments from a failure report.\n\nThe URL is valid for 300 seconds (5 minutes) and must be used before expiration.\n\nAuthentication required.", "operationId": "downloadAllAttachments", "parameters": [ { "name": "organizationId", "in": "query", "description": "Organization ID", "required": true, "schema": { "type": "string", "maxLength": 255, "examples": [ "org_6464de38ebf5b013b1928408" ] } }, { "name": "id", "in": "path", "description": "The MongoDB ObjectId of the failure report", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{24}$", "examples": [ "507f1f77bcf86cd799439011" ] } } ], "responses": { "200": { "description": "Returns presigned download URL for ZIP archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadUrlResponse" }, "examples": { "zip_download": { "summary": "ZIP archive download URL", "value": { "data": { "downloadUrl": "https://s3.amazonaws.com/ruf-reports/ruf-zip/report-12345/all-attachments.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...", "expiresAt": "2024-01-15T10:35:00Z" } } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "example": "no-store, private" }, "description": "Cache control header" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/v1/dmarc/failure-reports/aggregates": { "servers": [], "get": { "tags": [ "Failure Reports" ], "summary": "Get aggregated statistics for failure reports", "description": "Returns aggregated statistics and dimensional breakdowns for DMARC failure reports.\n\nFeatures:\n- Aggregate by multiple dimensions (reporter, ptrGroup, countryCode, domain)\n- Filter by domain names, date range, source IP, country code, reporter domain\n- Control top N results per dimension\n- Set minimum count threshold\n- Sort by count or key\n- Summary statistics including total reports, unique domains, unique reporters\n\nAuthentication required.", "operationId": "getFailureReportsAggregates", "parameters": [ { "name": "organizationId", "in": "query", "description": "Organization ID to filter reports by", "required": true, "schema": { "type": "string", "maxLength": 255, "examples": [ "org_6464de38ebf5b013b1928408" ] } }, { "name": "domains", "in": "query", "description": "Comma-separated list of domain names to filter reports by (minimum 1 required)", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?)*\\.[a-zA-Z]{2,}(,[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?)*\\.[a-zA-Z]{2,})*$", "examples": [ "example.com,test.com" ] } }, { "name": "dateFrom", "in": "query", "description": "Aggregate reports from this date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time", "examples": [ "2024-01-01T00:00:00Z" ] } }, { "name": "dateTo", "in": "query", "description": "Aggregate reports until this date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time", "examples": [ "2024-01-31T23:59:59Z" ] } }, { "name": "reporterDomain", "in": "query", "description": "Filter by reporter domain (FQDN)", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?(\\.[a-zA-Z0-9]([a-zA-Z0-9-_]{0,61}[a-zA-Z0-9])?)*\\.[a-zA-Z]{2,}$", "examples": [ "reporter.com" ] } }, { "name": "reportDate", "in": "query", "description": "Filter by specific report date (ISO 8601 format)", "required": false, "schema": { "type": "string", "format": "date-time", "examples": [ "2024-01-15T00:00:00Z" ] } }, { "name": "ptr", "in": "query", "description": "Filter by PTR record (must be \"Unknown\" or a valid domain)", "required": false, "schema": { "type": "string", "examples": [ "mail.example.com" ] } }, { "name": "ptrGroup", "in": "query", "description": "Filter by PTR group (must be \"Unknown\" or a valid domain)", "required": false, "schema": { "type": "string", "examples": [ "example.com" ] } }, { "name": "countryCode", "in": "query", "description": "Filter by country code (ISO 3166-1 alpha-2)", "required": false, "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "examples": [ "US" ] } }, { "name": "sourceIp", "in": "query", "description": "Filter by source IPv4 address", "required": false, "schema": { "type": "string", "format": "ipv4", "pattern": "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$", "examples": [ "192.168.1.100" ] } }, { "name": "dimensions", "in": "query", "description": "Comma-separated list of dimensions to aggregate by (minimum 1 required, must be unique)", "required": true, "schema": { "type": "string", "pattern": "^(reporter|ptrGroup|countryCode|domain)(,(reporter|ptrGroup|countryCode|domain))*$", "examples": [ "reporter,countryCode" ] } }, { "name": "topN", "in": "query", "description": "Number of top results to return per dimension", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "examples": [ 20 ] } }, { "name": "minCount", "in": "query", "description": "Minimum count threshold for results (filters out entries below this count)", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "examples": [ 5 ] } }, { "name": "field", "in": "query", "description": "Field to sort aggregation results by", "required": false, "schema": { "type": "string", "enum": [ "count", "key" ], "default": "count", "examples": [ "count" ] } }, { "name": "direction", "in": "query", "description": "Sort direction for aggregation results", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "examples": [ "desc" ] } }, { "name": "hasAttachments", "in": "query", "description": "Filter reports by attachment presence", "required": false, "schema": { "type": "boolean", "examples": [ true ] } } ], "responses": { "200": { "description": "Returns aggregated statistics and dimensional breakdowns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FailureReportsAggregates" }, "examples": { "aggregates_response": { "summary": "Aggregated statistics response", "value": { "dimensions": [ { "dimension": "reporter", "buckets": [ { "key": "reporter1.com", "count": 150 }, { "key": "reporter2.com", "count": 89 }, { "key": "reporter3.com", "count": 45 } ] }, { "dimension": "countryCode", "buckets": [ { "key": "US", "count": 180 }, { "key": "GB", "count": 67 }, { "key": "DE", "count": 37 } ] } ], "summary": { "totalReports": 284, "uniqueDomains": 5, "uniqueReporters": 12, "dateRange": { "from": "2024-01-01T00:00:00Z", "to": "2024-01-31T23:59:59Z" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://api2.easydmarc.com", "description": "Live" } ] } }, "/auth/magic-link": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "createMagicLink", "summary": "Generate login magic link", "description": "Generates a short-lived, one-time URL that authenticates a specific user into a specific organization, then redirects them to your chosen EasyDMARC URI.\n\n## Using the Magic Link\n1. Your backend calls POST /auth/magic-link with userId, organizationId, redirectUri.\n2. API returns a single-use url and expiringAt.\n3. Redirect the user (HTTP 302) or render a button that navigates to url.\n4. The user is authenticated and then redirected to redirectUri within EasyDMARC.\n\nNotes\n- Treat the returned url as a credential: never log or expose it broadly.\n- The link expires at expiringAt; do not cache beyond that time.\n- A new link should be generated per session/initiation.\n\n\n## Examples\n\n**cURL**\n```\ncurl -X POST \"https://api2.easydmarc.com/auth/magic-link\" \\\n -H \"Authorization: Bearer $EASYDMARC_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"userId\": \"c99cf9f3-f946-4707-9984-a19bf2d57841\",\n \"organizationId\": \"org_0987654321\",\n \"redirectUri\": \"https://account-console.easydmarc.com\"\n }'\n```\n\nSecurity Best Practices\n- Send the request server-to-server only; never expose your API token to the browser or client apps.\n- Do not log full magic links; if needed, mask them.\n- Prefer short validity windows for operational usage; launch the redirect immediately after generating the link.", "parameters": [], "requestBody": { "required": true, "description": "Magic link generation request with user, organization, and redirect information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkRequest" } } } }, "responses": { "200": { "description": "Successfully generated magic link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLink" } } } }, "400": { "description": "Bad Request - Invalid input or missing parameters" }, "401": { "description": "Unauthorized - Invalid or missing Bearer token" } }, "tags": [ "Authentication" ], "security": [ { "bearer": [] } ] } }, "/auth/token": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "getAuthToken", "summary": "Obtain authentication token", "description": "Authenticates your client credentials and returns a bearer token required for accessing protected API endpoints.\n\n", "parameters": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/AuthTokenRequest" } } } }, "responses": { "200": { "description": "Authenticated. A successful request returns a bearer token and related metadata:\n\n**Response Fields**\n- access_token (string): The token used to authenticate API requests. Include this in the Authorization header as Bearer .\n- expires_in (number): Token validity duration in seconds (e.g. 300 = 5 minutes).\n- refresh_expires_in (number): Always 0 – token refresh is not supported.\n- token_type (string): Always Bearer.\n- not-before-policy (number): Internal policy value (typically 0), safe to ignore.\n- scope (string): Scope of access for the token (e.g. public-api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } } }, "400": { "description": "Authentication Failed" }, "401": { "description": "Unauthorized" } }, "tags": [ "Authentication" ] } }, "/v1/organizations": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "createOrganization", "summary": "Create a new organization", "description": "Creates a new organization within the partner tenant with the specified name.", "parameters": [], "requestBody": { "required": true, "description": "Organization object that needs to be added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganization" } } } }, "responses": { "201": { "description": "Organization created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortOrganization" } } } }, "400": { "description": "Invalid request parameters - Required parameter is missing or invalid" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to create organizations" }, "429": { "description": "Too Many Requests - Rate limit exceeded" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organizations" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] }, "get": { "operationId": "getOrganizations", "summary": "List organizations", "description": "Retrieves a paginated list of organizations within the partner tenant. Use page and limit parameters to control pagination.", "parameters": [ { "name": "page", "required": false, "in": "query", "description": "Page number for pagination", "example": 1, "schema": { "minimum": 1, "default": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "example": 20, "schema": { "minimum": 1, "maximum": 50, "default": 10, "type": "number" } } ], "responses": { "200": { "description": "A list of organizations with pagination metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "description": "Array of items for the current page", "items": { "$ref": "#/components/schemas/ShortOrganization" } }, "meta": { "$ref": "#/components/schemas/PageMeta_2", "description": "Pagination metadata including total count, page count, and navigation flags" } }, "required": [ "data", "meta" ] } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions" }, "429": { "description": "Too Many Requests - Rate limit exceeded" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organizations" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] } }, "/v1/organizations/{organizationId}": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "patch": { "operationId": "patchOrganization", "summary": "Partially update existing organization", "description": "Updates the organization with the specified fields. Only provided fields will be updated.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Unique identifier of the organization", "example": "org_68231dcfeb8e9f092a052b88", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Organization object with fields to be partially updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganization" } } } }, "responses": { "200": { "description": "Organization updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortOrganization" } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to update this organization" }, "404": { "description": "Organization not found" }, "429": { "description": "Too Many Requests - Rate limit exceeded" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organizations" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] }, "get": { "operationId": "getOrganizationById", "summary": "Get organization details", "description": "Retrieves the organization details by the specified ID.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Unique identifier of the organization", "example": "org_68231dcfeb8e9f092a052b88", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShortOrganization" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to view this organization" }, "404": { "description": "Organization not found" }, "429": { "description": "Too Many Requests - Rate limit exceeded" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organizations" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] }, "delete": { "operationId": "deleteOrganization", "summary": "Delete an organization", "description": "Deletes the organization by the specified ID. This action is irreversible.", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Unique identifier of the organization to delete", "example": "org_68231dcfeb8e9f092a052b88", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Organization deleted successfully" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Insufficient permissions to delete this organization" }, "404": { "description": "Organization not found" }, "500": { "description": "Internal Server Error" } }, "tags": [ "Organizations" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] } }, "/v1/partners/plans": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "listPlans", "summary": "List plans", "description": "Returns all plans available to the partner, including pricing information, feature sets, and billing details. Use this endpoint to discover sellable plans and prices for subscription assignment.", "parameters": [], "responses": { "200": { "description": "List of plans with their prices and features", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlanV2" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" } }, "tags": [ "Billing - Subscriptions & Pricing" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] } }, "/v1/partners/subscriptions": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "listSubscriptions", "summary": "List subscriptions for an organization", "description": "Retrieves all subscriptions for a given organization, including expired and cancelled subscriptions.", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "example": "org_88xy77", "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "List of subscriptions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionV2" } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" }, "422": { "description": "Unprocessable Entity - Invalid organization ID format" } }, "tags": [ "Billing - Subscriptions & Pricing" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] } }, "/v1/partners/subscriptions/{subscriptionId}/cancel": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "cancelSubscription", "summary": "Cancel a subscription", "description": "Cancels a subscription immediately. Cannot be applied to an already cancelled subscription.", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "description": "Subscription ID", "example": "sub_12ab34", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionV2" } } } }, "401": { "description": "Unauthorized - You don't have a partner account" }, "403": { "description": "Forbidden - Organization or price does not belong to the partner" }, "404": { "description": "Subscription not found" }, "422": { "description": "Unprocessable Entity - Subscription already cancelled" } }, "tags": [ "Billing - Subscriptions & Pricing" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] } }, "/v1/partners/subscriptions/{subscriptionId}/renew": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "renewSubscription", "summary": "Renew the subscription", "description": "Updates the expiration date of an active subscription based on the assigned price billing period. Cannot be applied to a cancelled subscription.", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "description": "Subscription ID", "example": "sub_12ab34", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subscription renewed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionV2" } } } }, "400": { "description": "Invalid request or renewal not allowed" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" }, "404": { "description": "Subscription not found" }, "422": { "description": "Unprocessable Entity - Subscription is cancelled" } }, "tags": [ "Billing - Subscriptions & Pricing" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] } }, "/v1/partners/subscriptions/assign": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "assignSubscription", "summary": "Assign a subscription (partner-admin flow)", "description": "Assigns a subscription for an organization using a priceId the partner is allowed to sell. Payment is handled by the partner; this endpoint only registers the assignment.", "parameters": [], "requestBody": { "required": true, "description": "Subscription assignment data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerSubscriptionAssignRequest" } } } }, "responses": { "201": { "description": "Subscription assigned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionV2" } } } }, "400": { "description": "Validation error - Price not allowed for partner or would be a downgrade" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" }, "404": { "description": "Organization or price not found" }, "409": { "description": "Conflict - Organization already has an active incompatible subscription" } }, "tags": [ "Billing - Subscriptions & Pricing" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] } }, "/v1/partners/subscriptions/{subscriptionId}": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "updateSubscriptionPrice", "summary": "Upgrade/downgrade plan", "description": "Creates a new subscription with a new Plan/Price. The current active subscription is cancelled and replaced with the new one.", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "description": "Subscription ID", "example": "sub_12ab34", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "New price information for the subscription upgrade/downgrade", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartnerSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionV2" } } } }, "401": { "description": "Unauthorized - You don't have a partner account" }, "403": { "description": "Forbidden - Organization or price does not belong to the partner" }, "404": { "description": "Subscription with given ID does not exist" }, "422": { "description": "Unprocessable Entity - Subscription already cancelled or price ID is required" } }, "tags": [ "Billing - Subscriptions & Pricing" ], "security": [ { "oauth2": [] }, { "bearer": [] } ] } }, "/v1/dns-lookup/a": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForA", "summary": "DNS lookup for a record", "description": "DNS lookup for a record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "domain", "required": true, "in": "query", "schema": { "example": "example.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ARecord" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/a/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchA", "summary": "DNS lookup batch for a record", "description": "DNS lookup for a record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ABatchRecordsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ARecord" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/aaaa": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForAaaa", "summary": "DNS lookup for aaaa record", "description": "DNS lookup for aaaa record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "domain", "required": true, "in": "query", "schema": { "example": "example.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AaaaRecord" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/aaaa/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchAaaa", "summary": "DNS lookup batch for aaaa record", "description": "DNS lookup for aaaa record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AaaaBatchRecordsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AaaaRecord" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/ns": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForNs", "summary": "DNS lookup for ns record", "description": "DNS lookup for ns record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "domain", "required": true, "in": "query", "schema": { "example": "example.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NsRecord" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/ns/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchNs", "summary": "DNS lookup batch for ns record", "description": "DNS lookup for ns record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NsBatchRecordsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NsRecord" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/mx": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForMx", "summary": "DNS lookup for mx record", "description": "DNS lookup for mx record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "domain", "required": true, "in": "query", "schema": { "example": "example.com", "type": "string" } }, { "name": "skipAddresses", "required": false, "in": "query", "schema": { "example": true, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MxRecords" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/mx/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchMx", "summary": "DNS lookup batch for mx record", "description": "DNS lookup for mx record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MxBatchRecordsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MxRecords" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/ptr": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForPtr", "summary": "DNS lookup for ptr record", "description": "DNS lookup for ptr record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "ip", "required": true, "in": "query", "schema": { "example": "8.8.8.8", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtrRecord" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/ptr/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchPtr", "summary": "DNS lookup batch for ptr record", "description": "DNS lookup for ptr record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PtrBatchRecordsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PtrRecord" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/txt": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForTxt", "summary": "DNS lookup for txt record", "description": "DNS lookup for txt record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "domain", "required": true, "in": "query", "schema": { "example": "example.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TxtRecord" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/txt/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchTxt", "summary": "DNS lookup batch for txt record", "description": "DNS lookup for txt record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TxtBatchRecordsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TxtRecord" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/cname": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForCname", "summary": "DNS lookup for cname record", "description": "DNS lookup for cname record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "domain", "required": true, "in": "query", "schema": { "example": "example.com", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CnameRecord" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/cname/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchCname", "summary": "DNS lookup batch for cname record", "description": "DNS lookup for cname record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CnameRecordBatchRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CnameRecord" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dmarc/records-raw": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "getDmarcRecordsRaw", "summary": "Get raw DMARC records", "description": "Get raw DMARC records for a domain", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRecordsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRecord" } } } }, "400": { "description": "Bad Request" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dmarc": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForDmarc", "summary": "DNS lookup for dmarc record", "description": "DNS lookup for dmarc record type", "parameters": [ { "name": "domain", "required": true, "in": "query", "schema": { "example": "example.com", "type": "string" } }, { "name": "recommendedRua", "required": false, "in": "query", "description": "Recommended RUA address for record from platform.", "schema": { "example": "a1b2c3d4@rua.easydmarc.com", "type": "string" } }, { "name": "skipOurAddresses", "required": false, "in": "query", "schema": { "default": false, "example": true, "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRecordResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dmarc/record-by-structure": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "getDmarcRecordByStructure", "summary": "Get DMARC record by structure", "description": "Get DMARC record by providing a structure object", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRecordByStructureRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRecordResponse" } } } }, "400": { "description": "Bad Request" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dmarc/record-structure": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "getDmarcRecordStructure", "summary": "Get DMARC record structure", "description": "Get DMARC record structure for a domain", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRecordStructureRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRecordStructure" } } } }, "400": { "description": "Bad Request" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dmarc/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchDmarc", "summary": "DNS lookup batch for dmarc record", "description": "DNS lookup for dmarc record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRecordsBatchRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DmarcRecordResponse" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dkim": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForDkim", "summary": "DNS lookup for dkim record", "description": "DNS lookup for dkim record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "domain", "required": true, "in": "query", "schema": { "example": "example.com", "type": "string" } }, { "name": "selectors", "required": true, "in": "query", "schema": { "example": [ "s1", "s2", "google" ], "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DkimRecordsResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dkim/records-by-selectors": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "getDkimRecordsBySelectorsWithDomain", "summary": "Get DKIM records by selectors with domain", "description": "Get DKIM records by selectors with domain name in request body", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DkimBySelectorsWthDomainRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DkimRecordsResponse" } } } }, "400": { "description": "Bad Request" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dkim/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchDkim", "summary": "DNS lookup batch for dkim record", "description": "DNS lookup for dkim record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DkimBySelectorsWthDomainBatchRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DkimRecordsResponse" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/spf": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupForSpf", "summary": "DNS lookup for spf record", "description": "DNS lookup for spf record type", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpfRecordRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpfRecordResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/spf/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchSpf", "summary": "DNS lookup batch for spf record", "description": "DNS lookup for spf record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpfRecordBatchRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SpfRecordResponse" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/spf/lookup-result": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "getSpfRecordLookupResult", "summary": "Get SPF record lookup result", "description": "Get SPF record lookup result for a domain", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpfRecordLookupResultRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpfRecordLookupResult" } } } }, "400": { "description": "Bad Request" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/bimi": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "dnsLookupForBimi", "summary": "DNS lookup for bimi record", "description": "DNS lookup for bimi record type", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "domain", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BimiRecord" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/bimi/batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "dnsLookupBatchBimi", "summary": "DNS lookup batch for bimi record", "description": "DNS lookup for bimi record type for a list of domains", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRecordsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BimiRecord" } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/bimi/validation": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "validateBimiRecord", "summary": "Validate BIMI record", "description": "Validate a BIMI record for a domain", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BimiRecord" } } } }, "400": { "description": "Bad Request" }, "422": { "description": "Unprocessable Entity" } }, "tags": [ "DNS Lookup" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/reverse-dns": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "getReverseRecord", "summary": "Perform reverse DNS lookup", "description": "Resolves an IP address or reverse DNS name to its corresponding PTR record. Supports both IPv4 and IPv6 addresses. Returns status codes for different resolution outcomes (SUCCESS, NOTFOUND, NODATA, etc.).", "parameters": [ { "name": "maxAgeMs", "required": false, "in": "query", "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache", "schema": { "example": 5000, "type": "number" } }, { "name": "query", "required": true, "in": "query", "schema": { "example": "8.8.8.8", "type": "string" } } ], "responses": { "200": { "description": "DNS lookup response with status code and optional PTR record data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReverseDnsResponse" } } } } }, "tags": [ "DnsCore" ] } }, "/v1/dmarc/rua/reports": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Returns parsed DMARC RUA (aggregate) reports with comprehensive\nfiltering and field selection capabilities.\n\nFeatures:\n- Filter by date range, domain names, report type, and custom filters\n- Optional field selection (properties parameter)\n- Flexible sorting with multiple order fields\n- Pagination support (page/pageSize based)\n- Advanced filtering with operators (eq, ne, in, nin, gt, lt, etc.)\n\nAuthentication required. Response is paginated.", "operationId": "getReportRawData", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRawDataRequest" } } } }, "responses": { "200": { "description": "Returns raw report data", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DmarcReport" } }, "meta": { "$ref": "#/components/schemas/PageMeta_3" } } } } } }, "401": { "description": "Authentication required" }, "422": { "description": "Validation errors" } }, "security": [ { "bearer": [] } ], "summary": "Get RUA reports raw data", "tags": [ "Aggregate Reports" ] } }, "/v1/dmarc/rua/reports/{id}": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "Retrieves a single parsed DMARC RUA (aggregate) report by its\nunique UUID identifier.\n\nReturns the complete report data including authentication results,\npolicy information, and source details. Authentication required.", "operationId": "getReportById", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The UUID v4 of the DMARC report", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Returns report by ID", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DmarcReport" } }, "meta": { "$ref": "#/components/schemas/PageMeta_3" } } } } } }, "401": { "description": "Authentication required" }, "404": { "description": "Report not found" }, "422": { "description": "Validation errors" } }, "security": [ { "bearer": [] } ], "summary": "Get aggregate report by ID", "tags": [ "Aggregate Reports" ] } }, "/v1/dmarc/rua/properties": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Retrieves distinct values for a specific DMARC report field\nwithin the specified criteria.\n\nFeatures:\n- Get unique values for any DMARC report field\n (policy_domain, org_name, country_code, etc.)\n- Filter by date range, domains, and report types\n- Advanced filtering with operators\n- Pagination support with configurable page size (max 100)\n- Useful for populating dropdowns, filters, and data exploration\n\nAuthentication required. Results are paginated.", "operationId": "getDistinctProperty", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyRequest" } } } }, "responses": { "200": { "description": "Returns distinct property values", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DistinctPropertyValue" } }, "meta": { "$ref": "#/components/schemas/PageMeta_3" } } } } } }, "401": { "description": "Authentication required" }, "422": { "description": "Validation errors" } }, "security": [ { "bearer": [] } ], "summary": "Get distinct property values", "tags": [ "Aggregate Reports" ] } }, "/v1/dmarc/rua/aggregations": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Returns aggregated DMARC authentication and disposition\nstatistics within specified criteria.\n\nFeatures:\n- Aggregate by SPF/DKIM authentication results (pass/fail counts)\n- Aggregate by DMARC disposition (none/quarantine/reject counts)\n- Filter by date range, domains, and report types\n- Group results by any DMARC report field\n- Advanced filtering with operators\n- Flexible sorting with multiple order fields\n- Pagination support\n- Returns structured aggregation counts for analysis and reporting\n\nAuthentication required. Results are paginated.", "operationId": "getAggregations", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AggregationRequest" } } } }, "responses": { "200": { "description": "Returns aggregation statistics", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AggregatedData" } }, "meta": { "$ref": "#/components/schemas/PageMeta_3" } } } } } }, "401": { "description": "Authentication required" }, "422": { "description": "Validation errors" } }, "security": [ { "bearer": [] } ], "summary": "Get DMARC aggregations data", "tags": [ "Aggregate Reports" ] } }, "/v1/dmarc/rua/volume": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Retrieves aggregated email volume data for domains within a\nspecified date range.\n\nFeatures:\n- Group results by any field except 'count'\n (policy_domain, org_name, source_ip, etc.)\n- Filter by authentication results, disposition, country, and more\n- Support for multiple report types and domains\n- Flexible sorting with multiple order fields\n- Pagination with configurable page size (max 100)\n- Returns partial DmarcReportDto objects focused on volume aggregation\n\nAuthentication required. Results are paginated.", "operationId": "getVolumeData", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeRequest" } } } }, "responses": { "200": { "description": "Returns aggregated volume data", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DmarcReport" } }, "meta": { "$ref": "#/components/schemas/PageMeta_3" } } } } } }, "401": { "description": "Authentication required" }, "422": { "description": "Validation errors" } }, "security": [ { "bearer": [] } ], "summary": "Get RUA email volume data", "tags": [ "Aggregate Reports" ] } }, "/v1/dmarc/rua/volume-history": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Returns volume data aggregated by time periods (day, week, month)\nwithin a specified date range.\n\nFeatures:\n- Time-series volume data with configurable periods (day/week/month)\n- Group results by any DMARC report field\n (policy_domain, country_code, etc.)\n- Filter by authentication results, disposition, source, and more\n- Support for multiple report types and domains\n- Flexible sorting with multiple order fields\n- Pagination support\n- Each result includes volume count, date period, and grouping fields\n\nAuthentication required. Results are paginated.", "operationId": "getReportsForPeriod", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportsForPeriodRequest" } } } }, "responses": { "200": { "description": "Returns volume data by report period", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DmarcReportVolumePerPeriod" } }, "meta": { "$ref": "#/components/schemas/PageMeta_3" } } } } } }, "401": { "description": "Authentication required" }, "422": { "description": "Validation errors" } }, "security": [ { "bearer": [] } ], "summary": "Get volume data by report period", "tags": [ "Aggregate Reports" ] } }, "/v1/dmarc/rua/auth-pass-rates": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Returns DKIM and SPF authentication pass rates for domains\nwithin a specified date range.\n\nFeatures:\n- Calculate pass rates for SPF and DKIM authentication\n- Support for sender domains and parked domains\n (at least one must be provided)\n- Filter by date range and custom filters\n- Pagination support with configurable page size (max 100)\n- Returns percentage-based pass rates for analysis and reporting\n- Useful for domain authentication performance monitoring\n\nAuthentication required. Results are paginated.", "operationId": "getAuthenticationPassRate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassRateDataRequest" } } } }, "responses": { "200": { "description": "Returns authentication pass rates", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PassRate" } }, "meta": { "$ref": "#/components/schemas/PageMeta_3" } } } } } }, "401": { "description": "Authentication required" }, "422": { "description": "Validation errors" } }, "security": [ { "bearer": [] } ], "summary": "Get authentication pass rates", "tags": [ "Aggregate Reports" ] } }, "/v1/users/invite": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Invites one or more users to join an organization by sending them invitation emails. The invited users will receive an email with a link to accept the invitation and set up their account.\n\n**Features:**\n- Bulk user invitation support\n- Role assignment during invitation\n- Custom redirect URL after invitation acceptance\n- Automatic email notification to invited users\n\n**Permissions Required:**\n- Must have admin role in the organization\n- Must have user management permissions", "operationId": "invite", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInviteUsersV1" } } } }, "responses": { "200": { "description": "User invitation(s) sent successfully. Invitation emails have been dispatched to all specified addresses." }, "400": { "description": "Bad request - Invalid input parameters, malformed email addresses, or missing required fields" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Authenticated but lacking permission to invite users to this organization" } }, "security": [ { "oauth2": [] } ], "summary": "Invite user", "tags": [ "Users" ] } }, "/v1/users": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Creates one or more new users in the organization with specified roles and permissions. Unlike the invite endpoint, this creates users directly without requiring them to accept an invitation.\n\n**Key Differences from Invite:**\n- Creates users immediately without invitation flow\n- Users are active immediately\n- No email invitation is sent\n\n**Use Cases:**\n- Bulk user import from external systems\n- Automated user provisioning via integrations\n- Pre-creating accounts for known team members\n\n**Permissions Required:**\n- Must have admin role in the organization\n- Must have user creation permissions", "operationId": "create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUsers" } } } }, "responses": { "201": { "description": "User(s) created successfully. Returns a mapping of email addresses to their newly created user IDs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUsersResponse" } } } }, "400": { "description": "Bad request - Invalid input parameters, malformed email addresses, or missing required fields" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Authenticated but lacking permission to create users in this organization" }, "409": { "description": "Conflict - One or more users already exist with the provided email addresses" } }, "security": [ { "oauth2": [] } ], "summary": "Create user", "tags": [ "Users" ] } }, "/v1/users/{userId}": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "Retrieves detailed information about a specific user by their user ID within an organization context. Returns comprehensive user profile data including personal information, verification status, and avatar details.\n\n**Returned Information:**\n- User identification (ID, username, email)\n- Personal details (first name, last name)\n- Account status (email verification)\n- Profile customization (avatar, avatar color)\n\n**Permissions Required:**\n- Must have access to the specified organization\n- Must have user read permissions", "operationId": "getUser", "parameters": [ { "name": "userId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID) of the organization context. Used to verify the user's membership and access permissions.", "schema": { "format": "uuid", "example": "8a7b9c2d-1e3f-4a5b-9c8d-7e6f5a4b3c2d", "type": "string" } } ], "responses": { "200": { "description": "User information retrieved successfully. Returns complete user profile data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserBasicInfo" } } } }, "400": { "description": "Bad request - Invalid user ID or organization ID format" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Authenticated but lacking permission to view this user's information" }, "404": { "description": "Not found - User does not exist or is not a member of the specified organization" } }, "security": [ { "oauth2": [] } ], "summary": "Get User", "tags": [ "Users" ] } }, "/v1/users/revoke-organization-access": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Revokes organization access for one or more specified users. This removes users from the organization and terminates their access to all organization resources.\n\n**Important Notes:**\n- This action is immediate and cannot be undone\n- Users will lose access to all organization resources\n- User accounts are not deleted, only their organization membership is removed\n- Users can be re-invited or re-added to the organization later\n\n**Permissions Required:**\n- Must have admin role in the organization\n- Cannot revoke access for yourself\n- Cannot revoke access for the organization owner", "operationId": "post_revokeOrganizationAccess", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRevokeOrganizationAccessRequest" } } } }, "responses": { "200": { "description": "Access revoked successfully. The specified users no longer have access to the organization." }, "400": { "description": "Bad request - Invalid input parameters, malformed user IDs, or empty user list" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Authenticated but lacking permission to revoke access, or attempting to revoke own access" }, "404": { "description": "Not found - One or more specified users or the organization does not exist" } }, "security": [ { "oauth2": [] } ], "summary": "Revoke org access", "tags": [ "Users" ] } }, "/v1/users/info": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "patch": { "description": "Updates personal information for a specific user. This endpoint allows modification of user profile details such as first name and last name.\n\n**Updatable Fields:**\n- First name\n- Last name\n\n**Non-Updatable Fields:**\n- Email address (requires separate verification flow)\n- User ID\n- Username\n- Email verification status\n\n**Permissions Required:**\n- Must be the user themselves, or\n- Must have admin role in the organization", "operationId": "patch_changePersonalInfo", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePersonalInfo" } } } }, "responses": { "200": { "description": "User information updated successfully. Returns the updated user data." }, "400": { "description": "Bad request - Invalid input parameters, empty update object, or validation errors" }, "401": { "description": "Unauthorized - Missing or invalid authentication token" }, "403": { "description": "Forbidden - Authenticated but lacking permission to update this user's information" }, "404": { "description": "Not found - User with the specified ID does not exist" } }, "security": [ { "oauth2": [] } ], "summary": "Update User Info", "tags": [ "Users" ] } } }, "components": { "parameters": { "page": { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "pageSize": { "name": "pageSize", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "organizationId": { "name": "organizationId", "in": "query", "description": "The ID of the organization owning the resources", "required": true, "schema": { "$ref": "#/components/schemas/OrganizationIdField", "example": "org_682b42c954f790f7230b3ad5" } } }, "securitySchemes": { "BearerAuth": { "type": "http", "description": "Generate your access token using authentica", "scheme": "bearer", "bearerFormat": "JWT" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "responses": { "Conflict": { "description": "The request conflicts with the current state of the resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": "409", "error": "ResourceConflict", "traceId": "abc-123-xyz-789", "timestamp": "2025-10-14T17:45:00.000Z", "details": { "message": "A resource with this identifier already exists", "property": "id" } } } } } } }, "NotFound": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": "404", "error": "ResourceNotFound", "traceId": "abc-123-xyz-789", "timestamp": "2025-10-14T17:50:00.000Z", "details": { "message": "Resource of type 'User' with ID '12345' was not found", "property": "id" } } } } } } }, "Forbidden": { "description": "The client doesn't have sufficient permissions to access the resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": "403", "error": "PermissionDenied", "traceId": "abc-123-xyz-789", "timestamp": "2025-10-14T12:00:00.000Z", "details": { "message": "You don't have permission to access this resource", "property": "id" } } } } } } }, "BadRequest": { "description": "Invalid request parameters. E.g. the required parameter is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": "400", "error": "ValidationError", "traceId": "abc-123-xyz-789", "timestamp": "2025-10-14T12:30:00.000Z", "details": { "message": "The request contains invalid parameters", "property": "id" } } } } } } }, "Unauthorized": { "description": "Authentication is required or credentials are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": "401", "error": "AuthenticationError", "traceId": "abc-123-xyz-789", "timestamp": "2025-10-14T12:45:00.000Z", "details": { "message": "Authentication required to access this resource", "property": "id" } } } } } } }, "GatewayTimeout": { "description": "The server did not receive a timely response from an upstream service", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "error": "GatewayTimeout", "details": { "serviceId": "payment-processor" }, "message": "The server did not receive a timely response from an upstream service", "traceId": "abc-123-xyz-789" } } } } } }, "TooManyRequests": { "description": "The client has sent too many requests in a given time period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": "429", "error": "RateLimitExceeded", "traceId": "abc-123-xyz-789", "timestamp": "2025-10-14T13:00:00.000Z", "details": { "message": "You have exceeded the rate limit for this API", "property": "id" } } } } } } }, "MethodNotAllowed": { "description": "The HTTP method is not supported for this resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "error": "MethodNotAllowed", "details": { "allowedMethods": [ "GET", "POST" ] }, "message": "This HTTP method is not supported for this endpoint", "traceId": "abc-123-xyz-789" } } } } } }, "ServiceUnavailable": { "description": "The service is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "error": "ServiceUnavailable", "details": { "retryAfterSeconds": 300, "maintenanceScheduled": true }, "message": "The service is temporarily unavailable", "traceId": "abc-123-xyz-789" } } } } } }, "InternalServerError": { "description": "An unexpected error occurred on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": "500", "error": "InternalServerError", "traceId": "abc-123-xyz-789", "timestamp": "2025-10-14T13:15:00.000Z", "details": { "message": "An unexpected error occurred while processing your request", "property": "id" } } } } } } }, "UnprocessableEntity": { "description": "The server understands the content type but cannot process the data. \nE.g. the organization with the provided `organization_id` doesn't exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": "422", "error": "UnprocessableEntity", "traceId": "abc-123-xyz-789", "timestamp": "2025-10-14T13:30:00.000Z", "details": { "message": "Unprocessable Entity", "property": "id" } } } } } } }, "UnsupportedMediaType": { "description": "The content type specified in the request is not supported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "error": "UnsupportedMediaType", "details": { "supportedTypes": [ "application/json", "application/xml" ] }, "message": "The content type specified in the request is not supported", "traceId": "abc-123-xyz-789" } } } } } } }, "schemas": { "OrganizationIdField": { "type": "string", "examples": [ "org_689ccbd84f05b4a824134330" ] }, "FilterCondition": { "description": "A filter condition supporting nested logical operators.", "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "field": { "type": "string", "examples": [ "policy" ] }, "value": {}, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "nin", "starts_with", "ends_with", "contains" ] } }, "required": [ "field", "value", "operator" ] }, { "type": "object", "additionalProperties": false, "properties": { "operator": { "type": "string", "enum": [ "AND", "OR" ] }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } } }, "required": [ "operator", "conditions" ] } ] }, "DomainOverview": { "type": "object", "description": "Represents Domain Group", "properties": { "domain": { "type": "string" }, "policy": { "type": "string", "enum": [ "none", "missing", "quarantine", "reject" ] }, "spf": { "$ref": "#/components/schemas/RecordStatus" }, "bimi": { "$ref": "#/components/schemas/RecordStatus" }, "dmarc": { "$ref": "#/components/schemas/RecordStatus" }, "dkim": { "$ref": "#/components/schemas/RecordStatus" }, "domain_logo_url": { "type": "string" }, "volume": { "type": "number" }, "spf_pass_rate": { "type": "number" }, "dkim_pass_rate": { "type": "number" }, "dmarc_compliance": { "type": "object", "properties": { "compliant": { "$ref": "#/components/schemas/Compliant" }, "none_compliant": { "$ref": "#/components/schemas/Compliant" }, "overall_compliance": { "type": "number" } } }, "domain_group": { "type": "string" }, "domain_verified": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/DomainType" } } }, "RecordStatus": { "type": "string", "enum": [ "no-record", "warning", "valid" ], "description": "Validation status of the record." }, "Compliant": { "type": "object", "properties": { "trend": { "type": "string" }, "value": { "type": "number" }, "percentage": { "type": "number" } } }, "DomainType": { "type": "string", "enum": [ "sending", "parked" ], "description": "Either sending or parked" }, "PaginationMeta": { "type": "object", "title": "PaginationMeta", "description": "Contains pagination and other meta data for the returned data", "properties": { "total": { "type": "integer", "description": "Total items", "examples": [ 123 ] }, "limit": { "type": "integer", "description": "maximum number of items per page", "examples": [ 20 ] }, "page": { "type": "integer", "description": "Page number for pagination", "examples": [ 2 ] }, "pageCount": { "type": "integer", "description": "Total pages" }, "hasPreviousPage": { "type": "boolean" }, "hasNextPage": { "type": "boolean" } }, "x-examples": { "Example 1": { "total": 35, "limit": 20, "page": 1, "pageCount": 2, "hasPreviousPage": false, "hasNextPage": true } } }, "Domain": { "type": "object", "title": "Domain", "properties": { "domain": { "$ref": "#/components/schemas/DomainName" }, "type": { "type": "string", "enum": [ "sending", "parked" ] }, "policy": { "type": "string", "enum": [ "none", "reject", "missing", "invalid", "quarantine" ] }, "domainVerified": { "type": "boolean" }, "logoUrl": { "type": "string", "format": "uri", "examples": [ "https://assets.easydmarc.com/favicons/2025-04/easydmarc_1744732732290.png" ] }, "domainGroup": { "type": "string", "examples": [ "Default Group" ] }, "domainGroupId": { "type": "string", "pattern": "^dmngrp_[a-f0-9]{24,}$", "examples": [ "dmngrp_67457f052750d56713945475" ] } }, "x-examples": { "Example 1": { "domain": "easydmarc.com", "domainGroup": "dmngrp_68267f052750d56713945475", "domainVerified": false, "type": "sending", "policy": "reject", "logoUrl": "https://assets.easydmarc.com/favicons/2025-04/easydmarc_1744732732290.png" } } }, "DomainName": { "type": "string", "title": "DomainName", "examples": [ "easydmarc.com" ], "x-examples": { "Example 1": "domain1.com" } }, "CreateDomainRequest": { "type": "object", "properties": { "organizationId": { "$ref": "#/components/schemas/OrganizationIdField" }, "domain": { "type": "string" }, "groupId": { "type": "string" }, "type": { "type": "string", "enum": [ "sending", "parked" ] } }, "required": [ "organizationId", "domain", "groupId", "type" ] }, "DomainSearchRequest": { "type": "object", "description": "Request payload for searching domains with filters and ordering.", "properties": { "organizationId": { "$ref": "#/components/schemas/OrganizationIdField" }, "page": { "type": "integer", "description": "Page number for pagination.", "default": 1 }, "order": { "type": "array", "description": "Ordering instructions for the search.", "items": { "$ref": "#/components/schemas/Order" } }, "filter": { "description": "Filter conditions for the search.", "oneOf": [ { "$ref": "#/components/schemas/FilterCondition" }, { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } } ] }, "domains": { "type": "array", "description": "List of domains to filter.", "items": { "type": "string" } }, "pageSize": { "type": "integer", "description": "Number of items per page.", "default": 50 }, "properties": { "type": "array", "description": "List of domain properties to include in the response.", "items": { "type": "string" } } } }, "Order": { "type": "object", "description": "Ordering instruction.", "properties": { "orderBy": { "type": "string", "description": "The field to order by." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Order direction." } }, "required": [ "orderBy", "direction" ] }, "DomainGroup": { "type": "object", "title": "DomainGroup", "properties": { "id": { "type": "string", "description": "Unique ID of the domain group" }, "name": { "type": "string", "description": "Domain group name" }, "domains": { "type": "array", "description": "List of Domains assigned to the Domain Group", "items": { "type": "string" } } }, "required": [ "id", "name" ], "x-examples": { "Success": { "id": "dmngrp_68267f052750d56713945475", "name": "group1", "domains": [ "domain1.com", "domain2.com", "linnea.net", "anderson.biz" ] } } }, "CreateDomainGroupRequest": { "type": "object", "title": "CreateDomainGroupRequest", "properties": { "organizationId": { "$ref": "#/components/schemas/OrganizationIdField" }, "name": { "type": "string" } }, "required": [ "organizationId", "name" ] }, "ErrorResponse": { "type": "object", "properties": { "statusCode": { "type": "string", "description": "Request status code", "examples": [ "404" ] }, "error": { "type": "string", "description": "Error code or type identifier", "examples": [ "ResourceNotFound" ] }, "traceId": { "type": "string", "description": "Request identifier for tracking and debugging", "examples": [ "048ddaa9-0273-4aa9-9a26-5b1e28e2bbc0" ] }, "timestamp": { "type": "string", "description": "Timestamp in ISO format", "format": "date-time", "examples": [ "2025-05-16T15:35:48.863Z" ] }, "details": { "type": "object", "description": "Additional context-specific error details" } }, "x-examples": { "Example 1": { "statusCode": "404", "error": "ResourceNotFound", "message": "Organization Not Found", "traceId": "048ddaa9-0273-4aa9-9a26-5b1e28e2bbc0", "timestamp": "2025-05-16T15:35:48.863Z", "details": { "message": "Organization Not Found", "error": "Not Found" } } } }, "CreateWebhookRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the webhook", "examples": [ "Domain Events Webhook" ] }, "ownerId": { "type": "string", "description": "Object Id of Owner of the webhook", "examples": [ "partner_1234567890" ] }, "url": { "type": "string", "description": "URL where webhook events will be sent", "examples": [ "https://example.com/webhooks/easydmarc" ] }, "events": { "type": "array", "description": "List of event names this webhook should subscribe to", "examples": [ [ "domain.created", "domain.verified", "report.received" ] ], "items": { "type": "string" } }, "active": { "type": "boolean", "description": "Whether the webhook is active", "default": true, "examples": [ true ] } }, "required": [ "name", "ownerId", "url", "events" ] }, "Webhook": { "type": "object", "properties": { "objectId": { "type": "string", "description": "Unique identifier for the webhook", "examples": [ "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6" ] }, "name": { "type": "string", "description": "Name of the webhook", "examples": [ "Domain Events Webhook" ] }, "ownerId": { "type": "string", "description": "Object Id of Owner of the webhook", "examples": [ "partner_1234567890" ] }, "url": { "type": "string", "description": "URL where webhook events will be sent", "examples": [ "https://example.com/webhooks/easydmarc" ] }, "events": { "type": "array", "description": "List of event names this webhook subscribes to", "examples": [ [ "domain.created", "domain.verified", "report.received" ] ], "items": { "type": "string" } }, "active": { "type": "boolean", "description": "Whether the webhook is active", "examples": [ true ] }, "createdAt": { "type": "string", "description": "Timestamp when the webhook was created", "format": "date-time", "examples": [ "2023-01-01T00:00:00.000Z" ] }, "updatedAt": { "type": "string", "description": "Timestamp when the webhook was last updated", "format": "date-time", "examples": [ "2023-01-01T00:00:00.000Z" ] } }, "required": [ "objectId", "name", "ownerId", "url", "events", "active", "createdAt", "updatedAt" ] }, "UpdateWebhookRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the webhook", "examples": [ "Updated Domain Events Webhook" ] }, "url": { "type": "string", "description": "URL where webhook events will be sent", "examples": [ "https://new-example.com/webhooks/easydmarc" ] }, "events": { "type": "array", "description": "List of event names this webhook should subscribe to", "examples": [ [ "domain.created", "domain.verified", "report.received" ] ], "items": { "type": "string" } }, "active": { "type": "boolean", "description": "Whether the webhook is active", "examples": [ false ] } } }, "WebhookDelivery": { "type": "object", "properties": { "webhookObjectId": { "type": "number", "description": "Object ID of the webhook that was triggered" }, "eventName": { "type": "string", "description": "Name of the event that triggered the webhook" }, "payload": { "description": "Data sent with the webhook", "allOf": [ { "$ref": "#/components/schemas/WebhookEventData" } ] }, "attempts": { "type": "number", "description": "Number of delivery attempts made" }, "maxAttempts": { "type": "number", "description": "Maximum number of delivery attempts allowed" }, "nextRetryAt": { "type": "number", "description": "Timestamp for next retry attempt" }, "status": { "type": "string", "enum": [ "failed", "pending", "success" ], "description": "Current status of the delivery" }, "statusCode": { "type": "number", "description": "HTTP status code from the delivery attempt" }, "error": { "type": "string", "description": "Error message if delivery failed" }, "deliveredAt": { "type": "string", "description": "Timestamp when delivery was successful", "format": "date-time" }, "createdAt": { "type": "string", "description": "Timestamp when delivery record was created", "format": "date-time" } }, "required": [ "webhookObjectId", "eventName", "payload", "attempts", "maxAttempts", "status", "createdAt" ] }, "WebhookEventData": { "type": "object", "properties": { "data": { "examples": [ { "domain": "example.com", "verificationStatus": "verified" } ], "allOf": [ { "$ref": "#/components/schemas/DomainVerificationEvent" } ] }, "metadata": { "description": "Metadata of the webhook event", "allOf": [ { "$ref": "#/components/schemas/WebhookEventMetadata" } ] } }, "required": [ "data", "metadata" ] }, "DomainVerificationEvent": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain that was verified", "examples": [ "example.com" ] }, "verificationStatus": { "type": "string", "description": "The verification status of the domain", "examples": [ "verified" ] } }, "required": [ "domain", "verificationStatus" ] }, "WebhookEventMetadata": { "type": "object", "properties": { "eventName": { "type": "string", "description": "Name of the event", "examples": [ "domain.created" ] }, "ownerId": { "type": "string", "description": "Object ID of the owner of the webhook", "examples": [ "partner_1234567890" ] } }, "required": [ "eventName", "ownerId" ] }, "ApiResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ] }, "PageMeta": { "type": "object", "properties": { "total": { "type": "number", "default": 0 }, "page": { "type": "number", "default": 0 }, "pageCount": { "type": "number", "default": 0 }, "limit": { "type": "number", "default": 0 }, "hasPreviousPage": { "type": "boolean", "default": false }, "hasNextPage": { "type": "boolean", "default": false } }, "required": [ "total", "page", "pageCount", "limit", "hasPreviousPage", "hasNextPage" ] }, "FailureReportListItem": { "type": "object", "description": "Summary information for a failure report in list view", "properties": { "id": { "type": "string", "description": "Unique report identifier (MongoDB ObjectId)", "examples": [ "507f1f77bcf86cd799439011" ] }, "domain": { "type": "string", "description": "Domain name associated with the report", "examples": [ "example.com" ] }, "sourceIp": { "type": "string", "description": "Source IP address of the email sender", "format": "ipv4", "examples": [ "192.168.1.100" ] }, "ptr": { "type": "string", "description": "PTR record for the source IP", "examples": [ "mail.sender.com" ] }, "ptrGroup": { "type": "string", "description": "PTR group (typically the root domain of the PTR record)", "examples": [ "sender.com" ] }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "examples": [ "US" ] }, "reportDate": { "type": "string", "description": "Date and time when the report was generated", "format": "date-time", "examples": [ "2024-01-15T10:30:00Z" ] }, "reporter": { "type": "string", "description": "Domain of the entity that generated the report", "examples": [ "reporter.com" ] }, "fromAddress": { "type": "string", "description": "Email address in the From header", "format": "email", "examples": [ "sender@example.com" ] }, "toAddress": { "type": "string", "description": "Email address in the To header", "format": "email", "examples": [ "recipient@example.com" ] }, "subject": { "type": "string", "description": "Email subject line", "examples": [ "Important Message" ] }, "attachmentCount": { "type": "integer", "description": "Number of attachments in the email", "examples": [ 2 ] } }, "required": [ "id", "domain", "sourceIp", "ptr", "ptrGroup", "countryCode", "reportDate", "reporter", "fromAddress", "toAddress", "subject", "attachmentCount" ] }, "FailureReportMetadata": { "type": "object", "description": "Detailed metadata for a single failure report", "properties": { "id": { "type": "string", "description": "Unique report identifier (MongoDB ObjectId)", "examples": [ "507f1f77bcf86cd799439011" ] }, "domain": { "type": "string", "description": "Domain name associated with the report", "examples": [ "example.com" ] }, "receivedAt": { "type": "string", "description": "Timestamp when the report was received", "format": "date-time", "examples": [ "2024-01-15T10:30:00Z" ] }, "message": { "$ref": "#/components/schemas/MessageDetails" }, "reportMetadata": { "$ref": "#/components/schemas/ReportMetadata" }, "downloadLinks": { "$ref": "#/components/schemas/DownloadLinks" }, "presignedDownloadLinks": { "$ref": "#/components/schemas/PresignedDownloadLinks" } }, "required": [ "id", "domain", "receivedAt", "message", "reportMetadata" ] }, "MessageDetails": { "type": "object", "description": "Details about the email message that failed DMARC authentication", "properties": { "from": { "type": "string", "description": "From email address", "format": "email", "examples": [ "sender@example.com" ] }, "to": { "type": "string", "description": "To email address", "format": "email", "examples": [ "recipient@example.com" ] }, "subject": { "type": "string", "description": "Email subject line", "examples": [ "Important Message" ] }, "headerFrom": { "type": "string", "description": "From address from email headers", "format": "email", "examples": [ "sender@example.com" ] }, "sourceIp": { "type": "string", "description": "Source IP address", "format": "ipv4", "examples": [ "192.168.1.100" ] }, "ptr": { "type": "string", "description": "PTR record for the source IP", "examples": [ "mail.sender.com" ] }, "ptrGroup": { "type": "string", "description": "PTR group (root domain)", "examples": [ "sender.com" ] }, "emailBody": { "type": "string", "description": "Email body content (included when 'emailBody' is in include parameter)", "examples": [ "This is the email body content..." ] }, "rawHeaders": { "type": "string", "description": "Raw email headers (included when 'rawHeaders' is in include parameter)", "examples": [ "Received: from mail.sender.com by mx.example.com..." ] }, "extractedUrls": { "type": "array", "description": "URLs extracted from the email body", "examples": [ [ "https://example.com/link1", "https://example.com/link2" ] ], "items": { "type": "string", "format": "uri" } }, "attachments": { "type": "array", "description": "Email attachments metadata", "items": { "$ref": "#/components/schemas/AttachmentMetadata" } } }, "required": [ "from", "to", "subject", "headerFrom", "sourceIp", "ptr", "ptrGroup" ] }, "AttachmentMetadata": { "type": "object", "description": "Metadata for an email attachment", "properties": { "cloud": { "type": "string", "description": "Cloud storage provider", "examples": [ "s3" ] }, "bucket": { "type": "string", "description": "Storage bucket name", "examples": [ "ruf-reports" ] }, "key": { "type": "string", "description": "Storage key/path for the attachment", "examples": [ "attachments/507f1f77bcf86cd799439011/0/document.pdf" ] }, "filename": { "type": "string", "description": "Original filename of the attachment", "examples": [ "document.pdf" ] }, "contentType": { "type": "string", "description": "MIME type of the attachment", "examples": [ "application/pdf" ] }, "size": { "type": "integer", "description": "File size in bytes", "examples": [ 102400 ] } }, "required": [ "cloud", "bucket", "key" ] }, "ReportMetadata": { "type": "object", "description": "Metadata about the DMARC failure report itself", "properties": { "reportId": { "type": "string", "description": "Unique identifier for the report", "examples": [ "report-12345" ] }, "reporterDomain": { "type": "string", "description": "Domain of the reporting entity", "examples": [ "reporter.com" ] }, "reportedBy": { "type": "string", "description": "Email address of the reporting entity", "format": "email", "examples": [ "noreply@reporter.com" ] }, "reportSubject": { "type": "string", "description": "Subject line of the report email", "examples": [ "DMARC Failure Report" ] }, "reportEmailBody": { "type": "string", "description": "Body content of the report email", "examples": [ "This message failed DMARC authentication..." ] }, "reportDate": { "type": "string", "description": "Date and time when the report was generated", "format": "date-time", "examples": [ "2024-01-15T10:30:00Z" ] }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "examples": [ "US" ] }, "location": { "$ref": "#/components/schemas/GeoLocation" } }, "required": [ "reportId", "reporterDomain", "reportedBy", "reportSubject", "reportDate", "countryCode" ] }, "GeoLocation": { "type": "object", "description": "Geographic location coordinates", "properties": { "coordinates": { "type": "array", "description": "[longitude, latitude] coordinates", "minItems": 2, "maxItems": 2, "examples": [ [ -74.006, 40.7128 ] ], "items": { "type": "number" } } }, "required": [ "coordinates" ] }, "DownloadLinks": { "type": "object", "description": "Download links for report files (API URLs, not presigned)", "properties": { "emlFile": { "type": "string", "description": "API endpoint URL to download the EML file", "format": "uri", "examples": [ "https://api2.easydmarc.com/v1.0/dmarc/failure-reports/reports/507f1f77bcf86cd799439011/eml?organizationId=org_6464de38ebf5b013b1928408" ] }, "attachments": { "type": "array", "description": "Download links for individual attachments", "items": { "$ref": "#/components/schemas/AttachmentDownloadLink" } }, "allAttachmentsZip": { "type": "string", "description": "API endpoint URL to download all attachments as a ZIP archive", "format": "uri", "examples": [ "https://api2.easydmarc.com/v1.0/dmarc/failure-reports/reports/507f1f77bcf86cd799439011/attachments/all?organizationId=org_6464de38ebf5b013b1928408" ] } } }, "AttachmentDownloadLink": { "type": "object", "description": "Download link for a single attachment", "properties": { "cloud": { "type": "string", "description": "Cloud storage provider", "examples": [ "s3" ] }, "bucket": { "type": "string", "description": "Storage bucket name", "examples": [ "ruf-reports" ] }, "key": { "type": "string", "description": "Storage key/path", "examples": [ "attachments/507f1f77bcf86cd799439011/0/document.pdf" ] }, "downloadUrl": { "type": "string", "description": "API endpoint URL to download the attachment", "format": "uri", "examples": [ "https://api2.easydmarc.com/v1.0/dmarc/failure-reports/reports/507f1f77bcf86cd799439011/attachments/0?organizationId=org_6464de38ebf5b013b1928408" ] } }, "required": [ "cloud", "bucket", "key", "downloadUrl" ] }, "PresignedDownloadLinks": { "type": "object", "description": "Presigned download links for report files (direct S3 URLs with expiration)", "properties": { "emlFile": { "type": "string", "description": "Presigned S3 URL for the EML file", "format": "uri", "examples": [ "https://s3.amazonaws.com/ruf-reports/eml/report-12345?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..." ] }, "attachments": { "type": "array", "description": "Presigned download links for individual attachments", "items": { "$ref": "#/components/schemas/PresignedAttachmentLink" } }, "allAttachmentsZip": { "type": "string", "description": "Presigned S3 URL for ZIP archive of all attachments", "format": "uri", "examples": [ "https://s3.amazonaws.com/ruf-reports/zip/report-12345/all-attachments.zip?X-Amz-Algorithm=..." ] } } }, "PresignedAttachmentLink": { "type": "object", "description": "Presigned download link for a single attachment", "properties": { "cloud": { "type": "string", "description": "Cloud storage provider", "examples": [ "s3" ] }, "bucket": { "type": "string", "description": "Storage bucket name", "examples": [ "ruf-reports" ] }, "key": { "type": "string", "description": "Storage key/path", "examples": [ "attachments/507f1f77bcf86cd799439011/0/document.pdf" ] }, "presignedUrl": { "type": "string", "description": "Presigned S3 URL for direct download", "format": "uri", "examples": [ "https://s3.amazonaws.com/ruf-reports/attachments/507f1f77bcf86cd799439011/0/document.pdf?X-Amz-Algorithm=..." ] }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when the presigned URL expires", "format": "date-time", "examples": [ "2024-01-15T10:35:00Z" ] } }, "required": [ "cloud", "bucket", "key", "presignedUrl", "expiresAt" ] }, "DownloadUrlResponse": { "type": "object", "description": "Response containing a presigned download URL", "properties": { "data": { "type": "object", "properties": { "downloadUrl": { "type": "string", "description": "Presigned download URL", "format": "uri", "examples": [ "https://s3.amazonaws.com/ruf-reports/ruf-eml/report-12345?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..." ] }, "expiresAt": { "type": "string", "description": "ISO 8601 timestamp when the URL expires", "format": "date-time", "examples": [ "2024-01-15T10:35:00Z" ] } }, "required": [ "downloadUrl", "expiresAt" ] } }, "required": [ "data" ] }, "FailureReportsAggregates": { "type": "object", "description": "Aggregated statistics for failure reports", "properties": { "dimensions": { "type": "array", "description": "Aggregated data organized by requested dimensions", "items": { "$ref": "#/components/schemas/AggregateDimension" } }, "summary": { "$ref": "#/components/schemas/AggregateSummary" } }, "required": [ "dimensions", "summary" ] }, "AggregateDimension": { "type": "object", "description": "Aggregated data for a single dimension", "properties": { "dimension": { "type": "string", "enum": [ "reporter", "ptrGroup", "countryCode", "domain" ], "description": "Dimension name", "examples": [ "reporter" ] }, "buckets": { "type": "array", "description": "Buckets containing aggregated counts", "items": { "$ref": "#/components/schemas/AggregateBucket" } } }, "required": [ "dimension", "buckets" ] }, "AggregateBucket": { "type": "object", "description": "A single bucket in aggregated data", "properties": { "key": { "type": "string", "description": "Bucket key (the dimension value)", "examples": [ "reporter1.com" ] }, "count": { "type": "integer", "description": "Number of reports in this bucket", "examples": [ 150 ] } }, "required": [ "key", "count" ] }, "AggregateSummary": { "type": "object", "description": "Summary statistics for the aggregated data", "properties": { "totalReports": { "type": "integer", "description": "Total number of reports matching the filters", "examples": [ 284 ] }, "uniqueDomains": { "type": "integer", "description": "Number of unique domains in the results", "examples": [ 5 ] }, "uniqueReporters": { "type": "integer", "description": "Number of unique reporter domains", "examples": [ 12 ] }, "dateRange": { "type": "object", "description": "Date range for the aggregated data", "properties": { "from": { "type": "string", "description": "Start date of the range", "format": "date-time", "examples": [ "2024-01-01T00:00:00Z" ] }, "to": { "type": "string", "description": "End date of the range", "format": "date-time", "examples": [ "2024-01-31T23:59:59Z" ] } }, "required": [ "from", "to" ] } }, "required": [ "totalReports", "uniqueDomains", "uniqueReporters", "dateRange" ] }, "MagicLinkRequest": { "type": "object", "properties": { "userId": { "type": "string", "description": "Unique identifier of the user.", "example": "c99cf9f3-f946-4707-9984-a19bf2d57841" }, "organizationId": { "type": "string", "description": "Organization identifier associated with the user.", "example": "org_0987654321" }, "redirectUri": { "type": "string", "description": "URI to redirect after login.", "example": "https://account-console.easydmarc.com", "format": "uri" } }, "required": [ "userId", "organizationId" ] }, "MagicLink": { "type": "object", "properties": { "url": { "type": "string", "description": "Generated magic link URL.", "example": "https://uac.easydmarc.com/...", "format": "uri" }, "expiringAt": { "type": "string", "description": "Expiration time of the generated link.", "example": "2025-10-16T12:34:56Z", "format": "date-time" } }, "required": [ "url", "expiringAt" ] }, "AuthTokenRequest": { "type": "object", "properties": { "client_id": { "type": "string", "description": "Client ID you obtained in API Client management in Account Console", "example": "api.JRd7Z4qkdfyGHTR6ZtUc8dUchVQmV7d4" }, "client_secret": { "type": "string", "description": "Client Secret you obtained in API Client management in Account Console", "example": "Szt832kHiYSDLGVSMRT3r2ZJgioXWR" } }, "required": [ "client_id", "client_secret" ] }, "AuthTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string", "description": "The token used to authenticate API requests. Include this in the Authorization header as Bearer .", "example": "00000000000000..." }, "expires_in": { "type": "number", "description": "Token validity duration in seconds (e.g. 300 = 5 minutes).", "example": 300 }, "refresh_expires_in": { "type": "number", "description": "Always 0 - token refresh is not supported.", "example": 0 }, "token_type": { "type": "string", "description": "Always Bearer.", "example": "Bearer" }, "not-before-policy": { "type": "number", "description": "Internal policy value (typically 0), safe to ignore.", "example": 0 }, "scope": { "type": "string", "description": "Scope of access for the token (e.g. public-api).", "example": "public-api" } }, "required": [ "access_token", "expires_in", "refresh_expires_in", "token_type", "not-before-policy", "scope" ] }, "Object": { "type": "object", "properties": {} }, "User": { "type": "object", "properties": { "objectId": { "type": "string", "nullable": false, "description": "The unique identifier of the user.", "example": "4a3d6dd3-6694-a41b-9abc-a46fa810a298" }, "email": { "type": "string", "nullable": false, "description": "The email address of the user.", "example": "angus.young@example.com" }, "status": { "type": "string", "nullable": false, "description": "The status of the user.", "enum": [ "active", "invite_pending", "deactivated" ], "example": "active" }, "name": { "type": "string", "nullable": true, "description": "The name of the user.", "example": "Donny Darko" }, "country": { "type": "string", "nullable": true, "description": "The country of the user.", "example": "USA" }, "timezone": { "type": "string", "nullable": true, "description": "The timezone of the user.", "example": "America/New_York" }, "createdAt": { "format": "date-time", "type": "string", "nullable": true, "description": "The date and time when the user was created.", "example": "2023-10-01T12:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "nullable": true, "description": "The date and time when the user was last updated.", "example": "2023-10-01T12:00:00Z" } }, "required": [ "objectId", "email", "status" ] }, "GetAttributesResponse": { "type": "object", "properties": {} }, "Attribute": { "type": "object", "properties": { "key": { "type": "string", "description": "The key of the attribute", "example": "channel" }, "values": { "description": "The values of the attribute", "example": [ "partner", "direct" ], "type": "array", "items": { "type": "string" } } }, "required": [ "key", "values" ] }, "UpsertMeRequest": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" } }, "required": [ "userId", "email" ] }, "SsoCreate": { "type": "object", "properties": { "idp_entity_id": { "type": "string", "description": "Identity Provider entity ID from the IdP metadata. This is the unique identifier for the external SAML identity provider (e.g., Okta, Azure AD, Google Workspace)", "example": "https://idp.example.com/saml/metadata" } }, "required": [ "idp_entity_id" ] }, "CustomerUpsertRequest": { "type": "object", "properties": {} }, "OrganisationCreateRequest": { "type": "object", "properties": { "name": { "type": "string" }, "objectId": { "type": "string" } }, "required": [ "name" ] }, "VendorEnum": { "type": "string", "enum": [ "stripe_eu", "stripe", "chargebee", "chargebee_eu", "azure" ] }, "BillingInfo": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "billingEmail": { "type": "string", "nullable": true }, "addressLine": { "type": "string", "nullable": true }, "addressCountry": { "type": "string", "nullable": true }, "addressCity": { "type": "string", "nullable": true }, "addressState": { "type": "string", "nullable": true }, "addressZip": { "type": "string", "nullable": true }, "misc": { "type": "string", "nullable": true }, "customerVendor": { "nullable": true, "$ref": "#/components/schemas/VendorEnum" }, "customerId": { "type": "string", "nullable": true }, "billingDay": { "type": "number", "nullable": true }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" } }, "required": [ "name", "email", "billingEmail", "addressLine", "addressCountry", "addressCity", "addressState", "addressZip", "misc", "customerVendor", "customerId", "billingDay", "createdAt", "updatedAt" ] }, "ProductTypeEnum": { "type": "string", "enum": [ "dmarc", "sender", "inguard", "unspecified" ] }, "ProductType": { "type": "object", "properties": { "objectId": { "type": "string" }, "name": { "$ref": "#/components/schemas/ProductTypeEnum" }, "homeUrl": { "type": "string" }, "icon": { "type": "string" }, "priority": { "type": "number" } }, "required": [ "objectId", "name", "homeUrl", "icon", "priority" ] }, "SingleAttributeValue": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] }, "ResourceItem": { "type": "object", "properties": { "objectId": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/SingleAttributeValue" } } }, "required": [ "objectId", "name" ] }, "ResourceGroup": { "type": "object", "properties": { "objectId": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" }, "updatedAt": { "format": "date-time", "type": "string" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceItem" } }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/SingleAttributeValue" } } }, "required": [ "objectId", "name", "type" ] }, "Product": { "type": "object", "properties": { "objectId": { "type": "string" }, "type": { "$ref": "#/components/schemas/ProductType" }, "resourceGroups": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceGroup" } }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/SingleAttributeValue" } } }, "required": [ "objectId", "type" ] }, "Organisation": { "type": "object", "properties": { "id": { "type": "number" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" }, "senderAccess": { "type": "boolean" }, "createdAt": { "format": "date-time", "type": "string" }, "countryCode": { "type": "string", "nullable": true }, "ipSafelist": { "type": "string", "nullable": true }, "apiFeatures": { "type": "array", "items": { "type": "string", "enum": [ "dns", "dmarc", "domains", "organizations", "users" ] } }, "billingInfo": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BillingInfo" } ] }, "updatedAt": { "format": "date-time", "type": "string" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/SingleAttributeValue" } } }, "required": [ "id", "objectId", "name", "uid", "senderAccess", "createdAt", "countryCode", "ipSafelist", "billingInfo", "updatedAt" ] }, "OrganisationUserCreateRequest": { "type": "object", "properties": {} }, "PolicyIdEnum": { "type": "string", "enum": [ "none", "OrganisationCreate", "OrganisationUpdate", "OrganisationList", "OrganisationGet", "OrganisationRemove", "Organisation:OwnershipChange", "Organisation:IpSafelistManage", "Organisation:AlertManage", "Organisation:SsoManage", "Organisation:UserCreate", "Organisation:UserUpdate", "Organisation:UserList", "Organisation:UserGet", "Organisation:UserRemove", "Organisation:ProductList", "Organisation:ProductDmarcCreate", "Organisation:ProductDmarcGet", "Organisation:ProductDmarcRemove", "Organisation:ProductSenderCreate", "Organisation:ProductSenderGet", "Organisation:ProductSenderRemove", "Organisation:ProductInguardCreate", "Organisation:ProductInguardGet", "Organisation:ProductInguardRemove", "Dmarc:SubscriptionManage", "Dmarc:UserCreate", "Dmarc:UserUpdate", "Dmarc:UserList", "Dmarc:UserGet", "Dmarc:UserRemove", "Dmarc:DmnGroup:UserCreate", "Dmarc:DmnGroup:UserUpdate", "Dmarc:DmnGroup:UserList", "Dmarc:DmnGroup:UserGet", "Dmarc:DmnGroup:UserRemove", "Dmarc:DmnGroupCreate", "Dmarc:DmnGroupUpdate", "Dmarc:DmnGroupList", "Dmarc:DmnGroupGet", "Dmarc:DmnGroupRemove", "Dmarc:Domain:UserCreate", "Dmarc:Domain:UserUpdate", "Dmarc:Domain:UserList", "Dmarc:Domain:UserGet", "Dmarc:Domain:UserRemove", "Dmarc:DomainCreate", "Dmarc:DomainUpdate", "Dmarc:DomainList", "Dmarc:DomainGet", "Dmarc:DomainRemove", "Sender:UserCreate", "Sender:UserUpdate", "Sender:UserList", "Sender:UserGet", "Sender:UserRemove", "Inguard:UserCreate", "Inguard:UserUpdate", "Inguard:UserList", "Inguard:UserGet", "Inguard:UserRemove" ] }, "Action": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/PolicyIdEnum" } }, "required": [ "id" ] }, "PolicyTargetEnum": { "type": "string", "enum": [ "Account", "Organisation", "Organisation:ProductDmarc", "Dmarc:Domain", "Dmarc:DmnGroup", "Organisation:ProductSender", "Organisation:ProductInguard" ] }, "Policy": { "type": "object", "properties": { "objectId": { "type": "string" }, "name": { "type": "string" }, "target": { "$ref": "#/components/schemas/PolicyTargetEnum" }, "description": { "type": "string" } }, "required": [ "objectId", "name", "target" ] }, "Role": { "type": "object", "properties": { "objectId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "policies": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } }, "required": [ "objectId", "name", "description" ] }, "OrganisationUser": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "role": { "$ref": "#/components/schemas/Role" }, "organisationId": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "user", "role" ] }, "OrganizationDomainRequest": { "type": "object", "properties": {} }, "OrganizationDomainUpsert": { "type": "object", "properties": {} }, "CreateOrganization": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "description": "Name of the organization", "example": "Acme Inc." } }, "required": [ "name" ] }, "ShortOrganization": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the organization", "example": "org_68231dcfeb8e9f092a052b88" }, "name": { "type": "string", "description": "Name of the organization", "example": "Acme Inc." }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the organization was created", "example": "2025-05-13T10:24:15.408Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the organization was last updated", "example": "2025-05-17T11:35:15.567Z" } }, "required": [ "id", "name", "createdAt", "updatedAt" ] }, "UpdateOrganization": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "description": "New name of the organization", "example": "Acme Inc. Updated" } }, "required": [ "name" ] }, "PageMeta_2": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Maximum number of items per page", "example": 20 }, "total": { "type": "number", "description": "Total number of items across all pages", "example": 123 }, "pageCount": { "type": "number", "description": "Total number of pages", "example": 7 }, "hasPreviousPage": { "type": "boolean", "description": "Whether there is a previous page available", "example": false }, "hasNextPage": { "type": "boolean", "description": "Whether there is a next page available", "example": true } }, "required": [ "page", "limit", "total", "pageCount", "hasPreviousPage", "hasNextPage" ] }, "ProductUserUpsert": { "type": "object", "properties": {} }, "ResourceGroupBulkUpsertRequest": { "type": "object", "properties": {} }, "ResourceGroupUpsertRequest": { "type": "object", "properties": {} }, "ResourceGroupUserUpsert": { "type": "object", "properties": {} }, "DomainCreateRequest": { "type": "object", "properties": {} }, "ResourceUserUpsert": { "type": "object", "properties": {} }, "BulkDomainsCreateRequest": { "type": "object", "properties": {} }, "BulkDomainsRequest": { "type": "object", "properties": {} }, "PaymentSourceCreateRequest": { "type": "object", "properties": {} }, "PaymentIntentCreateRequest": { "type": "object", "properties": {} }, "PlanCreateRequest": { "type": "object", "properties": {} }, "ProductFamilyEnum": { "type": "string", "enum": [ "plus", "premium", "plus-new", "premium-new", "increased_plus", "increased_premium", "plus_without_unlimited", "premium_without_unlimited", "msp", "msp_trial", "msp_standard", "pax8_trial", "pax8_paid", "enterprise", "custom", "old_plus", "old_premium", "easysender_email_verification", "easysender_inbox_placement", "south_asia_premium", "south_asia_plus", "compliance", "compliance_deliverability" ] }, "CurrencyEnum": { "type": "string", "enum": [ "USD", "EUR", "GBP" ] }, "FrequencyEnum": { "type": "string", "enum": [ "m", "y", "d" ] }, "PlanTypeEnum": { "type": "string", "enum": [ "plan", "addon" ] }, "PlanFeatures": { "type": "object", "properties": { "domain_count": { "type": "number", "description": "Maximum number of domains that can be monitored under this plan", "example": 10 }, "email_volume_count": { "type": "number", "description": "Maximum email volume count allowed per month (in millions or total emails)", "example": 1000000 }, "verification_count": { "type": "number", "description": "Number of email verifications available per month", "example": 500 }, "data_retention_days": { "type": "number", "description": "Number of days the user can look back when viewing data. Does not affect data retention — only limits the visible date range (e.g., 30, 90, 365)", "example": 90 }, "public_api": { "type": "boolean", "description": "Whether public API access is enabled for programmatic integration", "example": true }, "bimi_reporting": { "type": "boolean", "description": "Whether BIMI reporting is enabled", "example": true }, "saml": { "type": "boolean", "description": "Whether SAML-based Single Sign-On authentication is available", "example": true }, "alerting": { "type": "boolean", "description": "Whether email alerting and notification features are enabled", "example": true }, "api_access": { "type": "boolean", "description": "Whether API access is granted for this plan (legacy field, prefer public_api)", "example": true }, "reputation_monitoring": { "type": "boolean", "description": "Whether reputation monitoring and blacklist checking features are available", "example": true }, "mailbox_count": { "type": "number", "description": "Number of mailboxes that can be configured for inbox placement testing", "example": 5 }, "inbox_placement_test_count": { "type": "number", "description": "Number of inbox placement tests that can be run per month", "example": 50 }, "easy_spf": { "type": "boolean", "description": "Whether EasySPF feature for simplified SPF record management is enabled", "example": true }, "domain_access": { "type": "boolean", "description": "Whether domain-level access control and permissions are available", "example": true }, "audit_log": { "type": "boolean", "description": "Whether audit logging functionality for compliance and security tracking is enabled", "example": true }, "audit_log_duration": { "type": "number", "description": "Duration in days that audit logs are retained (e.g., 30, 90, 365)", "example": 365 }, "dns_integrations": { "type": "boolean", "description": "Whether DNS integrations are enabled", "example": true }, "messaging_integrations": { "type": "boolean", "description": "Whether messaging integrations are enabled", "example": true }, "email_investigation": { "type": "boolean", "description": "Whether email investigation and forensics features are available", "example": true }, "amazon_ses_integration": { "type": "boolean", "description": "Whether Amazon SES integration for sending emails is enabled", "example": false }, "touchpoint": { "type": "boolean", "description": "Whether touchpoint tracking and engagement analytics are available", "example": true }, "touchpoint_limit": { "type": "number", "description": "Touchpoint usage limit", "example": 10000 } } }, "Plan": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique numeric identifier for the plan", "example": 101 }, "name": { "type": "string", "description": "Human-readable name of the plan (e.g., \"Premium Monthly\", \"Domain Add-on\")", "example": "Premium Monthly Plan" }, "objectId": { "type": "string", "description": "Unique object identifier with \"plan\" prefix used for external references", "example": "plan_xyz789abc456" }, "productFamily": { "description": "Product family classification that groups related plans together. Includes Plus, Premium, Enterprise, MSP variants, and custom plans", "example": "premium", "$ref": "#/components/schemas/ProductFamilyEnum" }, "type": { "description": "Type of plan distinguishing between base subscription plans and add-on features", "example": "plan", "$ref": "#/components/schemas/PlanTypeEnum" }, "features": { "description": "Comprehensive feature configuration for this plan including domain limits, email volume, retention periods, and feature flags (SAML, API access, alerting, audit logs, etc.)", "allOf": [ { "$ref": "#/components/schemas/PlanFeatures" } ] }, "productType": { "description": "Product type associated with this plan, defining the service category (e.g., DMARC monitoring, email investigation)", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ProductType" } ] }, "prices": { "description": "Available pricing options for this plan. Multiple prices can exist with different currencies, billing frequencies (monthly/annual), and billing cycles", "type": "array", "items": { "$ref": "#/components/schemas/Price" } } }, "required": [ "id", "name", "objectId", "productFamily", "type", "features" ] }, "Price": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric identifier for the price record", "example": "123" }, "objectId": { "type": "string", "description": "Unique object identifier with \"price\" prefix used for external references", "example": "price_abc123xyz789" }, "name": { "type": "string", "description": "Human-readable name describing the pricing tier or option", "example": "Premium Monthly - USD" }, "amount": { "type": "number", "description": "Price amount in the specified currency. Stored as decimal with 2 decimal places", "example": 99.99 }, "currency": { "description": "Currency code for the price amount. Supports USD, EUR, and GBP", "example": "USD", "$ref": "#/components/schemas/CurrencyEnum" }, "frequency": { "description": "Billing frequency for this price. Monthly (m), yearly (y), or daily (d)", "example": "m", "$ref": "#/components/schemas/FrequencyEnum" }, "minimumBillableItems": { "type": "number", "description": "Minimum number of items that will be billed regardless of actual usage. Used for enforcing minimum charges", "example": 10, "nullable": true }, "billingCycles": { "type": "number", "description": "Number of billing cycles for this price. Used for limited-term subscriptions or promotional periods", "example": 12, "nullable": true }, "billingPeriod": { "type": "number", "description": "Billing period multiplier. For example, 1 for standard monthly/yearly, 2 for bi-monthly, etc.", "example": 1 }, "vendorPriceId": { "type": "string", "description": "Vendor-specific price identifier used for payment gateway integration (e.g., Stripe price ID, Chargebee price ID)", "example": "price_1234567890abcdef", "nullable": true }, "vendor": { "description": "Payment vendor/gateway used for this price. Supports Stripe, Chargebee, Chargebee EU, and Azure in multiple regions", "example": "chargebee", "$ref": "#/components/schemas/VendorEnum" }, "plan": { "description": "Associated plan containing feature definitions and plan type information", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Plan" } ] }, "toolsPlanId": { "type": "number", "description": "Legacy tools plan identifier for backward compatibility with the old billing system", "example": 789 } }, "required": [ "id", "objectId", "name", "amount", "currency", "frequency", "minimumBillableItems", "billingCycles", "billingPeriod", "vendor", "toolsPlanId" ] }, "SubscriptionItemStatusEnum": { "type": "string", "enum": [ "removed", "active", "suspended" ] }, "Subscription": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique numeric identifier for the subscription", "example": 12345 }, "objectId": { "type": "string", "description": "Unique object identifier with \"sub\" prefix used for external references", "example": "sub_abc123xyz789" }, "expireDate": { "format": "date-time", "type": "string", "description": "Date when the subscription expires. Used for subscription renewal scheduling and lifecycle management", "example": "2025-12-31T23:59:59.999Z" }, "cancelledAt": { "format": "date-time", "type": "string", "description": "Date when the subscription was cancelled. Null if the subscription is still active", "example": "2025-10-01T10:30:00.000Z", "nullable": true }, "organisation": { "description": "Organisation that owns this subscription. Contains organisation details including billing information", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Organisation" } ] }, "toolsUserPlanId": { "type": "number", "description": "Legacy tools user plan identifier for backward compatibility with the old system", "example": 456, "nullable": true }, "vendorSubscriptionId": { "type": "string", "description": "Payment vendor subscription identifier (e.g., Chargebee subscription ID) used for vendor API integration", "example": "cb_sub_9876543210", "nullable": true }, "product": { "description": "Product associated with this subscription. Includes product type and resource groups", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Product" } ] }, "items": { "description": "List of subscription items representing individual plan components with pricing, features, and quantities. Each item can have different statuses and feature configurations", "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItem" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the subscription was created", "example": "2025-01-01T00:00:00.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the subscription was last updated", "example": "2025-10-09T12:00:00.000Z" } }, "required": [ "id", "objectId", "expireDate", "createdAt", "updatedAt" ] }, "SubscriptionItem": { "type": "object", "properties": { "id": { "type": "number", "description": "Unique numeric identifier for the subscription item", "example": 9876 }, "objectId": { "type": "string", "description": "Unique object identifier with \"si\" prefix used for external references", "example": "si_def456uvw123" }, "price": { "description": "Pricing information for this subscription item, including amount, currency, frequency, and associated plan details", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Price" } ] }, "status": { "description": "Current status of the subscription item. Determines if the item is active, suspended, or removed from the subscription", "example": "active", "$ref": "#/components/schemas/SubscriptionItemStatusEnum" }, "quantity": { "type": "number", "description": "Quantity of this subscription item. Used for metered billing or multiple units of the same plan component", "example": 5, "nullable": true }, "minimumBillableItems": { "type": "number", "description": "Minimum number of billable items required. Used for enforcing minimum billing thresholds regardless of actual usage", "example": 10, "nullable": true }, "features": { "description": "Plan features configuration including domain count, email volume, retention days, and boolean feature flags (SAML, API access, alerting, etc.)", "allOf": [ { "$ref": "#/components/schemas/PlanFeatures" } ] }, "subscription": { "description": "Parent subscription that this item belongs to. Contains full subscription details including organisation and other items", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/Subscription" } ] }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the subscription item was created", "example": "2025-01-15T08:30:00.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the subscription item was last updated", "example": "2025-10-09T14:22:00.000Z" } }, "required": [ "id", "objectId", "status", "features", "createdAt", "updatedAt" ] }, "SubscriptionAssignRequest": { "type": "object", "properties": {} }, "SubscriptionUpsertRequest": { "type": "object", "properties": {} }, "SubscriptionCancelRequest": { "type": "object", "properties": {} }, "SubscriptionUpdateByItemIdRequest": { "type": "object", "properties": {} }, "SubscriptionItemUpdateRequest": { "type": "object", "properties": {} }, "UserPermissionsStructured": { "type": "object", "properties": {} }, "PermissionsPutRequest": { "type": "object", "properties": {} }, "ProductUserEntity": { "type": "object", "properties": {} }, "PermissionsGetRequest": { "type": "object", "properties": {} }, "ListRequest": { "type": "object", "properties": { "order": { "type": "string" }, "offset": { "type": "number" }, "limit": { "type": "number" } } }, "IsOwnerOrAdminResponse": { "type": "object", "properties": { "isOwnerOrAdmin": { "type": "boolean" } }, "required": [ "isOwnerOrAdmin" ] }, "PriceUpdateRequest": { "type": "object", "properties": {} }, "ChargebeeEventRequest": { "type": "object", "properties": {} }, "InstallmentCreateRequest": { "type": "object", "properties": {} }, "FeatureUsageUpdateRequest": { "type": "object", "properties": {} }, "CreateApiClientRequest": { "type": "object", "properties": { "name": { "type": "string" }, "mode": { "type": "string" }, "ipAccessRestriction": { "type": "string" }, "trustedIpsOrCidrs": { "type": "string" }, "organisationId": { "type": "string" }, "partnerId": { "type": "string" }, "userId": { "type": "string" }, "apiFeatures": { "type": "array", "description": "Roles assigned to the user", "example": [ "dns", "dmarc" ], "items": { "type": "string", "enum": [ "dns", "dmarc", "domains", "organizations", "users" ] } } }, "required": [ "name", "mode", "ipAccessRestriction", "trustedIpsOrCidrs", "organisationId", "partnerId", "userId", "apiFeatures" ] }, "UpdateApiClientRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Api Client Name", "example": "New API Client" }, "mode": { "type": "string", "description": "Api Client Mode", "example": "test" }, "trustedIpsOrCidrs": { "type": "string", "description": "The list of trusted ips or CIDRs", "example": "216.58.216.75, 216.58.216.70/32" }, "ipAccessRestriction": { "type": "string", "description": "Is the API client restricted or not", "example": "restricted" }, "apiFeatures": { "type": "array", "description": "Roles assigned to the user", "example": [ "dns", "dmarc" ], "items": { "type": "string", "enum": [ "dns", "dmarc", "domains", "organizations", "users" ] } } }, "required": [ "name", "mode", "ipAccessRestriction", "apiFeatures" ] }, "ApiClientRegenerateRequest": { "type": "object", "properties": {} }, "ApiClientChangeStateRequest": { "type": "object", "properties": {} }, "PlanFeaturesV2": { "type": "object", "properties": { "domainCount": { "type": "number", "description": "Number of domains included in the plan", "example": 2 }, "emailVolumeCount": { "type": "number", "description": "Monthly email volume limit", "example": 100000 }, "verificationCount": { "type": "number", "description": "Number of verifications allowed" }, "dataRetentionDays": { "type": "number", "description": "Data retention period in days" }, "publicApi": { "type": "boolean", "description": "Whether public API access is enabled" }, "bimiReporting": { "type": "boolean", "description": "Whether BIMI reporting is enabled" }, "saml": { "type": "boolean", "description": "Whether SAML SSO is enabled" }, "alerting": { "type": "boolean", "description": "Whether alerting features are enabled" }, "apiAccess": { "type": "boolean", "description": "Whether API access is enabled" }, "reputationMonitoring": { "type": "boolean", "description": "Whether reputation monitoring is enabled" }, "mailboxCount": { "type": "number", "description": "Number of mailboxes included" }, "inboxPlacementTestCount": { "type": "number", "description": "Number of inbox placement tests allowed" }, "easySpf": { "type": "boolean", "description": "Whether EasySPF feature is enabled" }, "domainAccess": { "type": "boolean", "description": "Whether domain access feature is enabled" }, "auditLog": { "type": "boolean", "description": "Whether audit log feature is enabled" }, "auditLogDuration": { "type": "number", "description": "Audit log retention duration in days" }, "dnsIntegrations": { "type": "boolean", "description": "Whether DNS integrations are enabled" }, "emailInvestigation": { "type": "boolean", "description": "Whether email investigation feature is enabled" }, "amazonSesIntegration": { "type": "boolean", "description": "Whether Amazon SES integration is enabled" }, "touchpoint": { "type": "boolean", "description": "Whether touchpoint feature is enabled" }, "touchpointLimit": { "type": "number", "description": "Touchpoint usage limit" } } }, "PriceV2": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the price", "example": "price_plus_monthly_001" }, "name": { "type": "string", "description": "The display name of the price", "example": "Plus — Monthly" }, "amount": { "type": "number", "description": "The price amount", "example": 99 }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "USD", "enum": [ "USD", "EUR", "GBP" ] }, "frequency": { "type": "string", "description": "Billing frequency (month or year)", "example": "month", "enum": [ "m", "y", "d" ] }, "minimumBillableItems": { "type": "object", "description": "Minimum number of billable items required for this price. Used for MSP/volume-based pricing.", "example": 10, "nullable": true }, "billingCycles": { "type": "object", "description": "Number of billing cycles for the price. If null, the subscription renews indefinitely.", "example": 1, "nullable": true }, "billingPeriod": { "type": "number", "description": "The billing period value combined with frequency. For example, 1 with frequency \"month\" means monthly billing.", "example": 1 }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the price was created", "example": "2023-03-08T08:37:05.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the price was last updated", "example": "2023-03-08T08:37:05.000Z" } }, "required": [ "id", "name", "amount", "currency", "frequency", "billingPeriod", "createdAt", "updatedAt" ] }, "PlanV2": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the plan", "example": "plan_plus" }, "name": { "type": "string", "description": "The display name of the plan", "example": "Plus" }, "features": { "description": "The feature set of the plan including domain limits, email volume, and feature flags", "allOf": [ { "$ref": "#/components/schemas/PlanFeaturesV2" } ] }, "prices": { "description": "The list of prices associated with the plan. Each price represents a different billing cycle (monthly, yearly) with its amount, currency, and billing period.", "type": "array", "items": { "$ref": "#/components/schemas/PriceV2" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the plan was created", "example": "2023-03-08T08:37:05.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the plan was last updated", "example": "2023-03-08T08:37:05.000Z" } }, "required": [ "id", "name", "features", "prices", "createdAt", "updatedAt" ] }, "SubscriptionItemV2": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the subscription item", "example": "si_aa11" }, "quantity": { "type": "number", "description": "The quantity of the subscription item. Default is 1, mainly used for MSP prices.", "example": 1, "minimum": 1 }, "features": { "description": "The feature set of the subscription item. This is denormalized from the plan features but can be changed during subscription updates.", "example": { "domainCount": 10, "emailVolumeCount": 100000 }, "allOf": [ { "$ref": "#/components/schemas/PlanFeatures" } ] }, "priceId": { "type": "string", "description": "The unique identifier of the price this subscription item belongs to", "example": "price_9f39c0b7" }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the subscription item was created", "example": "2023-03-08T08:37:05.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the subscription item was last updated", "example": "2023-03-08T08:37:05.000Z" } }, "required": [ "id", "quantity", "features", "priceId", "createdAt", "updatedAt" ] }, "SubscriptionV2": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the subscription", "example": "sub_12ab34" }, "expireDate": { "format": "date-time", "type": "string", "description": "When the subscription will expire", "example": "2026-01-01T00:00:00Z" }, "cancelledAt": { "type": "object", "description": "Timestamp when the subscription was cancelled. If null, the subscription is active.", "example": null, "format": "date-time", "nullable": true }, "items": { "description": "The list of subscription items. Each subscription has at least one item.", "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItemV2" } }, "createdAt": { "format": "date-time", "type": "string", "description": "Timestamp when the subscription was created", "example": "2023-03-08T08:37:05.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Timestamp when the subscription was last updated", "example": "2023-03-08T08:37:05.000Z" } }, "required": [ "id", "expireDate", "items", "createdAt", "updatedAt" ] }, "PartnerSubscriptionAssignRequest": { "type": "object", "properties": { "priceId": { "type": "string", "description": "The unique identifier of the price to assign to the organization", "example": "price_9f39c0b7" }, "organizationId": { "type": "string", "description": "The unique identifier of the organization to assign the subscription to", "example": "org_88xy77" } }, "required": [ "priceId", "organizationId" ] }, "UpdatePartnerSubscriptionRequest": { "type": "object", "properties": { "priceId": { "type": "string", "description": "The unique identifier of the new price for the subscription upgrade/downgrade", "example": "price_premium_monthly_123" } }, "required": [ "priceId" ] }, "OrganizationDetails": { "type": "object", "properties": { "organizationObjectId": { "type": "string", "description": "Organization objectId" }, "ownerId": { "type": "string", "description": "Owner ID is ID that used for webhooks for now it is partner objectId" }, "productFamily": { "type": "string", "enum": [ "plus", "premium", "plus-new", "premium-new", "increased_plus", "increased_premium", "plus_without_unlimited", "premium_without_unlimited", "msp", "msp_trial", "msp_standard", "pax8_trial", "pax8_paid", "enterprise", "custom", "old_plus", "old_premium", "easysender_email_verification", "easysender_inbox_placement", "south_asia_premium", "south_asia_plus", "compliance", "compliance_deliverability" ] } }, "required": [ "organizationObjectId" ] }, "DomainDetails": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the domain" } }, "required": [ "name" ] }, "CheckPolicy": { "type": "object", "properties": { "policyIds": { "type": "array", "items": { "type": "string", "enum": [ "none", "OrganisationCreate", "OrganisationUpdate", "OrganisationList", "OrganisationGet", "OrganisationRemove", "Organisation:OwnershipChange", "Organisation:IpSafelistManage", "Organisation:AlertManage", "Organisation:SsoManage", "Organisation:UserCreate", "Organisation:UserUpdate", "Organisation:UserList", "Organisation:UserGet", "Organisation:UserRemove", "Organisation:ProductList", "Organisation:ProductDmarcCreate", "Organisation:ProductDmarcGet", "Organisation:ProductDmarcRemove", "Organisation:ProductSenderCreate", "Organisation:ProductSenderGet", "Organisation:ProductSenderRemove", "Organisation:ProductInguardCreate", "Organisation:ProductInguardGet", "Organisation:ProductInguardRemove", "Dmarc:SubscriptionManage", "Dmarc:UserCreate", "Dmarc:UserUpdate", "Dmarc:UserList", "Dmarc:UserGet", "Dmarc:UserRemove", "Dmarc:DmnGroup:UserCreate", "Dmarc:DmnGroup:UserUpdate", "Dmarc:DmnGroup:UserList", "Dmarc:DmnGroup:UserGet", "Dmarc:DmnGroup:UserRemove", "Dmarc:DmnGroupCreate", "Dmarc:DmnGroupUpdate", "Dmarc:DmnGroupList", "Dmarc:DmnGroupGet", "Dmarc:DmnGroupRemove", "Dmarc:Domain:UserCreate", "Dmarc:Domain:UserUpdate", "Dmarc:Domain:UserList", "Dmarc:Domain:UserGet", "Dmarc:Domain:UserRemove", "Dmarc:DomainCreate", "Dmarc:DomainUpdate", "Dmarc:DomainList", "Dmarc:DomainGet", "Dmarc:DomainRemove", "Sender:UserCreate", "Sender:UserUpdate", "Sender:UserList", "Sender:UserGet", "Sender:UserRemove", "Inguard:UserCreate", "Inguard:UserUpdate", "Inguard:UserList", "Inguard:UserGet", "Inguard:UserRemove" ] } }, "userId": { "type": "string" }, "organizationId": { "type": "string" }, "resourceGroupId": { "type": "string" }, "resourceId": { "type": "string" } }, "required": [ "policyIds", "userId" ] }, "IsActionAllowed": { "type": "object", "properties": { "isAllowed": { "type": "boolean" } }, "required": [ "isAllowed" ] }, "PartnerUser": { "type": "object", "properties": { "id": { "type": "number", "nullable": false, "description": "The unique identifier.", "example": "4a3d6dd3-6694-a41b-9abc-a46fa810a298" }, "partnerId": { "type": "string", "nullable": true, "description": "The unique identifier if the user is partner.", "example": "4a3d6dd3-6694-a41b-9abc-a46fa810a298" }, "objectId": { "type": "string", "nullable": false, "description": "The unique identifier of the user.", "example": "4a3d6dd3-6694-a41b-9abc-a46fa810a298" }, "email": { "type": "string", "nullable": false, "description": "The email address of the user.", "example": "angus.young@example.com" }, "status": { "type": "string", "nullable": false, "description": "The status of the user.", "enum": [ "active", "invite_pending", "deactivated" ], "example": "active" }, "name": { "type": "string", "nullable": true, "description": "The name of the user.", "example": "Donny Darko" }, "country": { "type": "string", "nullable": true, "description": "The country of the user.", "example": "USA" }, "timezone": { "type": "string", "nullable": true, "description": "The timezone of the user.", "example": "America/New_York" }, "createdAt": { "format": "date-time", "type": "string", "nullable": true, "description": "The date and time when the user was created.", "example": "2023-10-01T12:00:00Z" }, "updatedAt": { "format": "date-time", "type": "string", "nullable": true, "description": "The date and time when the user was last updated.", "example": "2023-10-01T12:00:00Z" } }, "required": [ "id", "objectId", "email", "status" ] }, "NotFoundException": { "type": "object", "properties": {} }, "ARecordObject": { "type": "object", "properties": {} }, "ValidationMessage": { "type": "object", "properties": { "key": { "type": "string", "description": "The key of the validation message." }, "message": { "type": "string", "description": "The description of the validation." } }, "required": [ "key", "message" ] }, "DnsValidationResult": { "type": "object", "properties": { "errors": { "description": "The validation messages for the DNS record.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "warnings": { "description": "The warning messages for the DNS record.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "info": { "description": "The info messages for the DNS record.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" } } }, "required": [ "errors", "warnings", "info" ] }, "DnsRecordStatus": { "type": "string", "description": "The status of the BIMI TXT record.", "enum": [ "SUCCESS", "NODATA", "NOTFOUND", "TIMEOUT", "ERROR", "SERVFAIL", "NXDOMAIN" ] }, "ARecord": { "type": "object", "properties": { "domain": { "type": "string", "nullable": false, "description": "The domain name of the A record.", "example": "example.com" }, "raw": { "nullable": false, "description": "The raw A records.", "example": [ "127.0.0.1", "127.0.0.2" ], "type": "array", "items": { "type": "string" } }, "object": { "description": "The parsed A record.", "allOf": [ { "$ref": "#/components/schemas/ARecordObject" } ] }, "validation": { "description": "The validation of the A record.", "allOf": [ { "$ref": "#/components/schemas/DnsValidationResult" } ] }, "queryStatus": { "example": "SUCCESS", "$ref": "#/components/schemas/DnsRecordStatus" }, "timestamp": { "type": "number", "description": "The timestamp of the A record lookup.", "example": 1704067200000 } }, "required": [ "domain", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "ABatchRecordsRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domains": { "example": [ "example.com", "example.org" ], "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ] }, "AaaaRecordObject": { "type": "object", "properties": {} }, "AaaaRecord": { "type": "object", "properties": { "domain": { "type": "string", "nullable": false, "description": "The domain name of the AAAA record.", "example": "example.com" }, "raw": { "nullable": false, "description": "The raw AAAA records.", "example": [ "2001:0000:130F:0000:0000:09C0:876A:130B", "::1" ], "type": "array", "items": { "type": "string" } }, "object": { "description": "The parsed AAAA record.", "allOf": [ { "$ref": "#/components/schemas/AaaaRecordObject" } ] }, "validation": { "description": "The validation of the AAAA record.", "allOf": [ { "$ref": "#/components/schemas/DnsValidationResult" } ] }, "queryStatus": { "example": "SUCCESS", "$ref": "#/components/schemas/DnsRecordStatus" }, "timestamp": { "type": "number", "description": "The timestamp of the AAAA record lookup.", "example": 1704067200000 } }, "required": [ "domain", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "AaaaBatchRecordsRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domains": { "example": [ "example.com", "example.org" ], "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ] }, "NsRecord": { "type": "object", "properties": { "domain": { "type": "string", "nullable": false, "description": "The domain name of the NS record.", "example": "example.com" }, "raw": { "nullable": false, "description": "The raw NS records.", "example": [ "jessica.ns.cloudflare.com", "john.ns.cloudflare.com" ], "type": "array", "items": { "type": "string" } }, "object": { "type": "object", "description": "The parsed NS record." }, "validation": { "description": "The validation of the NS record.", "allOf": [ { "$ref": "#/components/schemas/DnsValidationResult" } ] }, "queryStatus": { "type": "string", "description": "The status of the NS record.", "example": "SUCCESS" }, "timestamp": { "type": "number", "description": "The timestamp of the NS record lookup.", "example": 1704067200000 } }, "required": [ "domain", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "NsBatchRecordsRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domains": { "example": [ "example.com", "example.org" ], "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ] }, "MxRecordObject": { "type": "object", "properties": { "priority": { "type": "number", "description": "The priority of the MX record", "example": 10 }, "exchange": { "type": "string", "description": "The exchange server domain", "example": "mail.example.com" }, "addresses": { "description": "The list of IP addresses associated with the exchange server", "example": [ "1.1.1.1", "8.8.8.8" ], "type": "array", "items": { "type": "string" } }, "isValidAddresses": { "type": "boolean", "description": "Is valid addresses", "example": true } }, "required": [ "priority", "exchange", "addresses", "isValidAddresses" ] }, "MxObject": { "type": "object", "properties": { "mxRecords": { "description": "Array of MX records", "type": "array", "items": { "$ref": "#/components/schemas/MxRecordObject" } } }, "required": [ "mxRecords" ] }, "MxRecord": { "type": "object", "properties": { "domain": { "type": "string", "nullable": false, "description": "The domain name of the MX record.", "example": "example.com" }, "raw": { "type": "string", "nullable": false, "description": "The raw MX record.", "example": "" }, "object": { "description": "The parsed MX record object.", "allOf": [ { "$ref": "#/components/schemas/MxObject" } ] }, "validation": { "description": "The validation of the MX record.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "queryStatus": { "example": "SUCCESS", "$ref": "#/components/schemas/DnsRecordStatus" }, "timestamp": { "type": "number", "description": "The timestamp of the MX record lookup.", "example": 1747224799766 } }, "required": [ "domain", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "MxRecords": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com", "description": "The domain name for which MX records were retrieved" }, "records": { "description": "List of MX records for the domain", "type": "array", "items": { "$ref": "#/components/schemas/MxRecord" } } }, "required": [ "domain", "records" ] }, "MxBatchRecordsRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domains": { "example": [ "example.com", "example.org" ], "type": "array", "items": { "type": "string" } }, "skipAddresses": { "type": "boolean", "example": true } }, "required": [ "domains" ] }, "PtrRecordObject": { "type": "object", "properties": { "ptrRecords": { "description": "Array of PTR records", "example": [ "mail.example.com", "server.example.org" ], "type": "array", "items": { "type": "string" } } }, "required": [ "ptrRecords" ] }, "PtrRecord": { "type": "object", "properties": { "ip": { "type": "string", "nullable": false, "description": "The domain name of the PTR record.", "example": "8.8.8.8" }, "raw": { "type": "string", "nullable": false, "description": "The raw PTR record.", "example": "" }, "object": { "description": "The parsed PTR record object.", "allOf": [ { "$ref": "#/components/schemas/PtrRecordObject" } ] }, "validation": { "description": "The validation of the PTR record.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationMessage" } }, "queryStatus": { "type": "string", "enum": [ "SUCCESS", "NODATA", "NOTFOUND", "TIMEOUT", "ERROR", "SERVFAIL", "NXDOMAIN" ], "description": "The status of the PTR record lookup.", "example": "SUCCESS" }, "timestamp": { "type": "number", "description": "The timestamp of the PTR record lookup.", "example": 1747224799762 } }, "required": [ "ip", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "PtrBatchRecordsRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "ips": { "example": [ "8.8.8.8", "1.1.1." ], "type": "array", "items": { "type": "string" } } }, "required": [ "ips" ] }, "TxtRecordObject": { "type": "object", "properties": { "records": { "nullable": false, "description": "The raw TXT records.", "example": [ [ "v=spf1 include:_spf.google.com", "~all" ], [ "google-site-verification=abcdef12345" ] ], "type": "array", "items": { "type": "string" } } }, "required": [ "records" ] }, "TxtRecord": { "type": "object", "properties": { "domain": { "type": "string", "nullable": false, "description": "The domain name of the TXT record.", "example": "example.com" }, "raw": { "nullable": false, "description": "The raw TXT records.", "example": [ [ "v=spf1 include:_spf.google.com", "~all" ], [ "google-site-verification=abcdef12345" ] ], "type": "array", "items": { "type": "string" } }, "object": { "description": "The parsed TXT record object.", "allOf": [ { "$ref": "#/components/schemas/TxtRecordObject" } ] }, "validation": { "description": "The validation of the TXT record.", "allOf": [ { "$ref": "#/components/schemas/DnsValidationResult" } ] }, "queryStatus": { "example": "SUCCESS", "$ref": "#/components/schemas/DnsRecordStatus" }, "timestamp": { "type": "number", "description": "The timestamp of the TXT record lookup.", "example": 1704067200000 } }, "required": [ "domain", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "TxtBatchRecordsRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domains": { "example": [ "example.com", "example.org" ], "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ] }, "CnameRecord": { "type": "object", "properties": { "domain": { "type": "string", "nullable": false, "description": "The domain name of the CNAME record.", "example": "example.com" }, "raw": { "type": "string", "nullable": false, "description": "The raw CNAME record.", "example": "target.example.com." }, "object": { "type": "object", "description": "The parsed CNAME record." }, "validation": { "description": "The validation of the CNAME record.", "allOf": [ { "$ref": "#/components/schemas/ValidationMessage" } ] }, "queryStatus": { "example": "NOTFOUND", "$ref": "#/components/schemas/DnsRecordStatus" }, "timestamp": { "type": "number", "description": "The timestamp of the CNAME record lookup.", "example": 1704067200000 } }, "required": [ "domain", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "CnameRecordBatchRequest": { "type": "object", "properties": { "domains": { "example": [ "example.com", "easydmarc.com" ], "type": "array", "items": { "type": "string" } }, "maxAgeMs": { "type": "number", "description": "Max age of the cache -1:[from cache] 0:[force lookup] ( in ms)", "example": 3000 } }, "required": [ "domains" ] }, "DmarcRecordsRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domain": { "type": "string", "example": "example.com" }, "generate_dmarc_host": { "type": "boolean", "example": true, "default": true } }, "required": [ "domain" ] }, "DmarcRecord": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "records": { "example": [ "v=DMARC1; p=none; rua=mailto:adsd@mail.ru" ], "type": "array", "items": { "type": "string" } } }, "required": [ "domain", "records" ] }, "DmarcRecordTerm": { "type": "object", "properties": { "type": { "type": "number", "description": "The type of the DMARC record term", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 ] }, "tag": { "type": "string", "description": "The tag associated with the DMARC record term", "example": "v" }, "value": { "type": "string", "description": "The value of the DMARC record term" } }, "required": [ "type", "tag", "value" ] }, "DmarcDeserializedRecord": { "type": "object", "properties": { "v": { "type": "string", "description": "The DMARC version.", "example": "DMARC1" }, "p": { "type": "string", "description": "The DMARC policy for the domain.", "enum": [ "none", "reject", "quarantine" ] }, "rua": { "description": "The aggregate report URIs (RUA).", "example": [ "mailto:dmarc@example.com" ], "type": "array", "items": { "type": "string" } }, "ruf": { "description": "The forensic report URIs (RUF).", "example": [ "mailto:forensics@example.com" ], "type": "array", "items": { "type": "string" } }, "pct": { "type": "string", "description": "The percentage of messages subjected to DMARC policy.", "example": "100" }, "sp": { "type": "string", "description": "The subdomain policy for the domain.", "enum": [ "none", "reject", "quarantine" ] }, "np": { "type": "string", "description": "The non-compliant policy for the domain.", "enum": [ "none", "reject", "quarantine" ] }, "psd": { "type": "string", "description": "The PSD policy.", "enum": [ "n", "y" ] }, "aspf": { "type": "string", "description": "The alignment type for SPF.", "example": "r" }, "adkim": { "type": "string", "description": "The alignment type for DKIM.", "example": "s" }, "ri": { "type": "string", "description": "The reporting interval in seconds.", "example": "86400" }, "fo": { "description": "Failure options for forensic reporting.", "example": [ "0", "1" ], "type": "array", "items": { "type": "string" } } }, "required": [ "v", "rua", "ruf", "pct" ] }, "DmarcLookupResult": { "type": "object", "properties": { "policyStatus": { "type": "string", "description": "The policy status for the domain.", "enum": [ "none", "reject", "missing", "invalid", "quarantine" ] }, "subdomainPolicyStatus": { "type": "string", "description": "The policy status for subdomains.", "enum": [ "none", "reject", "missing", "invalid", "quarantine" ] }, "status": { "type": "number", "description": "The DNS lookup status.", "enum": [ 0, 1, 2, 3 ] }, "pct": { "type": "string", "description": "The percentage of messages subjected to DMARC policy.", "example": "100" }, "reportingStatus": { "type": "boolean", "description": "Indicates whether DMARC reporting is enabled.", "example": true } }, "required": [ "policyStatus", "subdomainPolicyStatus", "status", "pct", "reportingStatus" ] }, "DmarcRecordObj": { "type": "object", "properties": { "terms": { "type": "array", "items": { "$ref": "#/components/schemas/DmarcRecordTerm" } }, "deserializedRecord": { "description": "The deserialized DMARC record.", "allOf": [ { "$ref": "#/components/schemas/DmarcDeserializedRecord" } ] }, "lookupResult": { "description": "The DMARC lookup result.", "allOf": [ { "$ref": "#/components/schemas/DmarcLookupResult" } ] } }, "required": [ "terms", "deserializedRecord", "lookupResult" ] }, "DmarcMessage": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the error message", "enum": [ "ERROR_VERIFICATION_FAILURE", "ERROR_NO_MANAGED_CNAME_FOUND", "ERROR_NO_VALID_RECORD_FOUND", "ERROR_PUT_SPF_RECORD", "ERROR_INVALID_TERM_KEY", "ERROR_INVALID_ASPF_TERM", "ERROR_INVALID_ADKIM_TERM", "ERROR_INVALID_RUX_TERM", "ERROR_INVALID_V_TAG", "ERROR_INVALID_P_TAG", "ERROR_INVALID_SP_TAG", "ERROR_INVALID_NP_TAG", "ERROR_INVALID_PSD_TAG", "ERROR_INVALID_RI_TAG", "ERROR_INVALID_RF_TAG", "ERROR_INVALID_PCT_TAG", "ERROR_INVALID_FO_TAG", "ERROR_MISSING_V_TAG", "ERROR_MISSING_P_TAG", "ERROR_DUPLICATE_TAG", "ERROR_MULTIPLE_RECORD", "WARNING_POLICY_NONE", "WARNING_SUBDOMAIN_POLICY", "WARNING_NON_EXIST_SUBDOMAIN_POLICY", "WARNING_RUA_TAG", "WARNING_RUA_TAG_GUEST", "WARNING_PCT", "INFO_POLICY_QUARANTINE", "INFO_SUBDOMAIN_RECORD_NOT_FOUND", "INFO_EXTERNAL_VALIDATION", "CUSTOM" ] }, "args": { "type": "object", "description": "Arguments for the error messages", "additionalProperties": { "type": "string" } }, "options": { "type": "object", "description": "Additional options for the messages", "additionalProperties": { "type": "string" } } }, "required": [ "key", "args" ] }, "DmarcValidation": { "type": "object", "properties": { "warnings": { "description": "The list of errors found while parsing the DMARC record.", "type": "array", "items": { "$ref": "#/components/schemas/DmarcMessage" } }, "errors": { "description": "The list of warnings found while parsing the DMARC record.", "type": "array", "items": { "$ref": "#/components/schemas/DmarcMessage" } }, "info": { "description": "The list of info found while parsing the DMARC record.", "type": "array", "items": { "$ref": "#/components/schemas/DmarcMessage" } } }, "required": [ "warnings", "errors", "info" ] }, "DmarcRecordResponse": { "type": "object", "properties": { "domain": { "type": "string", "description": "The domain name associated with the DMARC record." }, "raw": { "type": "string", "description": "The raw DMARC record string.", "example": "v=DMARC1" }, "object": { "description": "The parsed DMARC record object.", "allOf": [ { "$ref": "#/components/schemas/DmarcRecordObj" } ] }, "validation": { "description": "Validation messages categorized by severity.", "allOf": [ { "$ref": "#/components/schemas/DmarcValidation" } ] }, "timestamp": { "type": "number", "description": "The timestamp of the DMARC record retrieval.", "example": 1704067200000 }, "queryStatus": { "$ref": "#/components/schemas/DnsRecordStatus" } }, "required": [ "domain", "raw", "object", "validation", "timestamp", "queryStatus" ] }, "DmarcRecordStructure": { "type": "object", "properties": { "recordDomainName": { "type": "string", "example": "example.com" }, "records": { "example": [ "v=DMARC1; p=none; rua=mailto:adsd@mail.ru" ], "type": "array", "items": { "type": "string" } } }, "required": [ "recordDomainName", "records" ] }, "DmarcRecordByStructureRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "dmarcRecordStructure": { "description": "DMARC record structure.", "example": { "recordDomainName": "example.com", "records": [ "v=DMARC1; p=none; rua=mailto:adsd@mail.ru" ] }, "allOf": [ { "$ref": "#/components/schemas/DmarcRecordStructure" } ] }, "recommendedRua": { "type": "string", "description": "Recommended RUA address for record from platform.", "example": "a1b2c3d4@rua.easydmarc.com" }, "skipOurAddresses": { "type": "boolean", "example": true, "default": false } }, "required": [ "dmarcRecordStructure" ] }, "DmarcRecordStructureRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domain": { "type": "string", "example": "example.com" }, "inheritRootDmarc": { "type": "boolean", "example": true, "default": true, "description": "Inherit the root DMARC record" } }, "required": [ "domain" ] }, "DmarcRecordsBatchRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domains": { "example": [ "example.com" ], "type": "array", "items": { "type": "string" } }, "generate_dmarc_host": { "type": "boolean", "example": true }, "inheritRootDmarc": { "type": "boolean", "example": true, "default": true, "description": "Inherit the root DMARC record" } }, "required": [ "domains" ] }, "DkimRecordTerm": { "type": "object", "properties": { "type": { "type": "string" }, "tag": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "tag", "value" ] }, "DkimRecordTypeEnum": { "type": "string", "enum": [ "cname", "txt" ] }, "DkimRecordEntity": { "type": "object", "properties": { "terms": { "type": "array", "items": { "$ref": "#/components/schemas/DkimRecordTerm" } }, "domain": { "type": "string" }, "isWildcard": { "type": "boolean" }, "type": { "$ref": "#/components/schemas/DkimRecordTypeEnum" }, "selector": { "type": "string" } }, "required": [ "terms", "domain", "isWildcard", "type", "selector" ] }, "DkimMessage": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the error message", "enum": [ "ERROR_INVALID_DOMAIN", "ERROR_NO_DKIM_RECORD_FOUND", "ERROR_MULTIPLE_RECORD", "ERROR_V_TAG_IS_NOT_FIRST", "ERROR_INVALID_V_TAG", "ERROR_INVALID_TERM", "ERROR_EMPTY_G_TAG", "ERROR_INVALID_H_TAG", "ERROR_INVALID_K_TAG", "ERROR_P_TAG_NOT_EXISTS", "ERROR_INVALID_P_TAG", "ERROR_INVALID_P_TAG_LENGTH", "ERROR_INVALID_S_TAG", "ERROR_INVALID_T_TAG", "ERROR_INVALID_TAG", "INFO_EMPTY_VALUE_P_TAG", "CUSTOM" ] }, "args": { "type": "object", "description": "Arguments for the error message", "additionalProperties": { "type": "string" } } }, "required": [ "key", "args" ] }, "DkimValidation": { "type": "object", "properties": { "errors": { "description": "General validation messages for DKIM", "type": "array", "items": { "$ref": "#/components/schemas/DkimMessage" } }, "warnings": { "description": "General validation warnings for DKIM", "type": "array", "items": { "$ref": "#/components/schemas/DkimMessage" } }, "info": { "description": "General information messages for DKIM", "type": "array", "items": { "$ref": "#/components/schemas/DkimMessage" } } }, "required": [ "errors", "warnings", "info" ] }, "DkimRecord": { "type": "object", "properties": { "raw": { "type": "string", "description": "Raw DKIM record string" }, "object": { "description": "Parsed DKIM record object", "allOf": [ { "$ref": "#/components/schemas/DkimRecordEntity" } ] }, "domain": { "type": "string", "description": "Domain name for the DKIM record" }, "validation": { "description": "DKIM Record validation messages", "allOf": [ { "$ref": "#/components/schemas/DkimValidation" } ] }, "queryStatus": { "example": "NODATA", "$ref": "#/components/schemas/DnsRecordStatus" }, "timestamp": { "type": "number", "description": "The timestamp of the DKIM record lookup.", "example": 1704067200000 } }, "required": [ "raw", "object", "domain", "validation", "queryStatus", "timestamp" ] }, "DkimRecordsResponse": { "type": "object", "properties": { "rootDomain": { "type": "string" }, "dkimRecords": { "type": "array", "items": { "$ref": "#/components/schemas/DkimRecord" } }, "validation": { "description": "General validation messages for DKIM", "allOf": [ { "$ref": "#/components/schemas/DkimValidation" } ] } }, "required": [ "rootDomain", "dkimRecords", "validation" ] }, "SelectorWithDomainName": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "selector": { "type": "string", "example": "google" } }, "required": [ "domain", "selector" ] }, "DkimBySelectorsWthDomainRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domain": { "type": "string", "example": "example.com" }, "selectors": { "example": [ { "domain": "example.com", "selector": "s1" }, { "domain": "example.com", "selector": "s2" }, { "domain": "example.com", "selector": "google" } ], "type": "array", "items": { "$ref": "#/components/schemas/SelectorWithDomainName" } } }, "required": [ "domain", "selectors" ] }, "DkimBySelectorsWthDomainBatchRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "items": { "example": [ { "domain": "example.com", "selectors": [ { "domain": "example.com", "selector": "s1" }, { "domain": "example.com", "selector": "s2" }, { "domain": "example.com", "selector": "google" } ] } ], "type": "array", "items": { "$ref": "#/components/schemas/DkimBySelectorsWthDomainRequest" } } }, "required": [ "items" ] }, "AOrMxSourceItem": { "type": "object", "properties": { "ip": { "type": "string", "example": "1.1.1.1" }, "title": { "type": "string", "example": "alt4.aspmx.l.google.com" } }, "required": [ "ip", "title" ] }, "SpfMessages": { "type": "string", "description": "Key of the error message", "enum": [ "SPF_DNS_RESOLVE_ERROR", "TERM_VALUE_DNS_RESOLVE_ERROR", "RECURSIVE_LOOKUP", "RECORD_NOT_FOUND", "MULTIPLE_SPF_RECORDS", "MULTIPLE_SPF_RECORDS_GLOBAL", "MISSING_VERSION_TAG", "MULTIPLE_VERSION_TAG", "DUPLICATE_DOMAIN", "INVALID_MX_RECORD", "INVALID_EXP_MECHANISM", "INVALID_REDIRECT_TERM", "DUPLICATE_REDIRECT_TERM", "DUPLICATE_MECHANISM", "PTR_USED", "UNKNOWN_MECHANISM", "TERM_MUST_BE_DOMAIN", "INVALID_IP_ADDRESS", "TERM_MUST_BE_IP4", "TERM_MUST_BE_IP6", "INVALID_CIDR", "UNSECURED_MECHANISM", "MECHANISM_AFTER_ALL", "MECHANISM_AFTER_REDIRECT", "MISSING_ALL_AND_REDIRECT_TAG", "HAS_ALL_AND_REDIRECT_TAG", "DNS_LOOKUP_COUNT", "SOURCE_DNS_LOOKUP_COUNT", "CUSTOM" ] }, "SpfMessage": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/SpfMessages" }, "args": { "type": "object", "description": "Arguments for the error message", "additionalProperties": { "type": "string" } } }, "required": [ "key", "args" ] }, "SpfValidationResult": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the validation was successful.", "example": true }, "errors": { "description": "A list of error messages.", "type": "array", "items": { "$ref": "#/components/schemas/SpfMessage" } }, "warnings": { "description": "A list of warning messages.", "type": "array", "items": { "$ref": "#/components/schemas/SpfMessage" } } }, "required": [ "success", "errors", "warnings" ] }, "AOrMxSource": { "type": "object", "properties": { "sources": { "description": "Source list", "type": "array", "items": { "$ref": "#/components/schemas/AOrMxSourceItem" } }, "validationResult": { "description": "Source validation result", "allOf": [ { "$ref": "#/components/schemas/SpfValidationResult" } ] } }, "required": [ "sources", "validationResult" ] }, "SpfRecord": { "type": "object", "properties": { "policy": { "type": "string", "example": "~" }, "recordTerms": { "description": "Detailed information about SPF record terms", "type": "array", "items": { "$ref": "#/components/schemas/SpfRecordTerm" } }, "dnsLookupCount": { "type": "number", "example": 3 } }, "required": [ "policy", "recordTerms", "dnsLookupCount" ] }, "SpfRecordTerm": { "type": "object", "properties": { "mechanism": { "description": "Mechanism of term", "example": [ "mx", "include" ], "oneOf": [ { "type": "string" }, { "enum": [ "a", "mx", "redirect", "include", "ptr", "ip4", "ip6", "exists", "exp" ] }, { "enum": [ "v", "all" ] } ] }, "source": { "description": "Detailed information about SPF record source", "oneOf": [ { "type": "null" }, { "type": "string" }, { "$ref": "#/components/schemas/AOrMxSource" }, { "$ref": "#/components/schemas/SpfRecord" } ] }, "value": { "type": "string", "example": "_spf.google.com" }, "originalTerm": { "type": "string", "example": "include:_spf.google.com" }, "domainName": { "type": "string", "example": "example.com" }, "ordering": { "type": "number", "description": "Sequence of terms" }, "validationResult": { "description": "Source validation result", "allOf": [ { "$ref": "#/components/schemas/SpfValidationResult" } ] }, "queryStatus": { "$ref": "#/components/schemas/DnsRecordStatus" } }, "required": [ "mechanism", "source", "value", "originalTerm", "domainName", "ordering", "validationResult", "queryStatus" ] }, "SpfRecordRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domain": { "type": "string", "example": "example.com" }, "isRoot": { "type": "boolean", "default": false, "example": false }, "visitedTerms": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/SpfRecordTerm" } }, "branchDomains": { "example": [ "example.com" ], "default": [], "type": "array", "items": { "type": "string" } }, "rawRecord": { "type": "string", "default": "" } }, "required": [ "domain" ] }, "SpfValidationResponse": { "type": "object", "properties": { "errors": { "description": "SPF record validation errors", "type": "array", "items": { "$ref": "#/components/schemas/SpfMessage" } }, "warnings": { "description": "SPF record validation warnings", "type": "array", "items": { "$ref": "#/components/schemas/SpfMessage" } }, "info": { "description": "SPF record validation information", "type": "array", "items": { "$ref": "#/components/schemas/SpfMessage" } } }, "required": [ "errors", "warnings", "info" ] }, "SpfRecordResponse": { "type": "object", "properties": { "domain": { "type": "string", "description": "SPF record domain name", "example": "example.com" }, "raw": { "type": "string", "description": "SPF record raw string", "example": "v=spf1 include:_spf.example.com ~all" }, "object": { "description": "SPF record object representation", "allOf": [ { "$ref": "#/components/schemas/SpfRecord" } ] }, "validation": { "description": "SPF record validation result", "allOf": [ { "$ref": "#/components/schemas/SpfValidationResponse" } ] }, "queryStatus": { "example": "SUCCESS", "$ref": "#/components/schemas/DnsRecordStatus" }, "timestamp": { "type": "number", "description": "Timestamp of the response", "example": 1704067200000 } }, "required": [ "domain", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "SpfRecordBatchRequestItem": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "isRoot": { "type": "boolean", "default": false, "example": false }, "visitedTerms": { "default": [], "type": "array", "items": { "$ref": "#/components/schemas/SpfRecordTerm" } }, "branchDomains": { "example": [ "example.com" ], "default": [], "type": "array", "items": { "type": "string" } }, "rawRecord": { "type": "string", "default": "" } }, "required": [ "domain" ] }, "SpfRecordBatchRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "items": { "example": [ { "domain": "example.com", "rawRecord": "" }, { "domain": "example2.com", "rawRecord": "v=spf1 include:_spf.example.com ~all" } ], "type": "array", "items": { "$ref": "#/components/schemas/SpfRecordBatchRequestItem" } } }, "required": [ "items" ] }, "SpfRecordLookupResultRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domain": { "type": "string", "example": "example.com" } }, "required": [ "domain" ] }, "SpfRecordLookupResult": { "type": "object", "properties": { "recordDomainName": { "type": "string", "example": "example.com" }, "records": { "example": [ "v=SPF1 include:_spf.example.com ~all" ], "type": "array", "items": { "type": "string" } } }, "required": [ "recordDomainName", "records" ] }, "BimiRecordFileTerm": { "type": "object", "properties": { "url": { "type": "string" }, "content": { "type": "string" } }, "required": [ "url", "content" ] }, "BimiRecordTermEnum": { "type": "string", "description": "The type of the BIMI record term", "enum": [ "v", "l", "a", "other" ] }, "BimiRecordTerm": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/BimiRecordTermEnum" }, "tag": { "type": "string", "description": "The tag associated with the BIMI record term", "example": "v" }, "value": { "description": "The value of the BIMI record term, which can be a Buffer, string, or specific term value type", "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/BimiRecordFileTerm" } ] } }, "required": [ "type", "tag", "value" ] }, "BimiMessages": { "type": "string", "description": "Key of the error message", "enum": [ "ERROR_MULTIPLE_RECORD", "ERROR_EMPTY_RECORD", "ERROR_INVALID_TERM", "ERROR_INVALID_V_TAG", "ERROR_INVALID_TAG_STRING", "ERROR_MISSING_V_TAG", "ERROR_MISSING_L_TAG", "ERROR_MISSING_A_TAG", "ERROR_ONLY_ONE_TAG", "ERROR_INVALID_SVG_URI", "ERROR_INVALID_SVG_PROTOCOL", "ERROR_MANAGED_VALIDATION_FAILURE", "ERROR_BIMI_CNAME_RECORD_NOT_FOUND", "ERROR_BIMI_HOST_NOT_FOUND", "ERROR_INCOMPATIBLE_SVG", "ERROR_UNABLE_TO_FETCH_SVG", "ERROR_SVG_SIZE_EXCEEDS", "ERROR_SVGS_IS_NOT_EQUAL", "ERROR_NOT_SUPPORTED_SVG_FORMAT", "ERROR_SVG_CONVERTER_HUMAN", "ERROR_SVG_CONVERTER_FETCH", "ERROR_SVG_CONVERTER_DOES_NOT_UPLOAD", "ERROR_SVG_CONVERTER_INVALID_FORMAT", "ERROR_SVG_CONVERTER_INVALID_OPTION", "ERROR_SVG_CONVERTER_INVALID_CONTENT", "ERROR_SVG_CONVERTER_IS_NOT_SQUARE", "ERROR_UNABLE_TO_FETCH_CERTIFICATE", "ERROR_INCOMPATIBLE_CERTIFICATE", "ERROR_CERTIFICATE_INVALID_PROTOCOL", "ERROR_CERTIFICATE_EXPIRED", "ERROR_CERTIFICATE_INVALID_PEM", "ERROR_CERTIFICATE_NOT_INCLUDE_DOMAIN", "WARNING_INEFFECTIVE_DMARC", "WARNING_INEFFECTIVE_DMARC_ERRORS", "WARNING_NOT_RESTRICTIVE", "WARNING_SVG_SQUARE_FORMAT", "WARNING_CERTIFICATE_WILL_EXPIRE", "CUSTOM" ] }, "BimiValidationMessage": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/BimiMessages" }, "args": { "type": "object", "description": "Arguments for the error message", "additionalProperties": { "type": "string" } } }, "required": [ "key", "args" ] }, "BimiSvgMetaData": { "type": "object", "properties": { "size": { "type": "number", "description": "The size of the SVG file.", "example": 1024 }, "title": { "type": "string", "description": "The title of the SVG file.", "example": "Logo" }, "base_profile": { "type": "string", "description": "The base profile of the SVG file.", "example": "SVG 1.1" }, "version": { "type": "string", "description": "The version of the SVG file, optional.", "example": "1.1" } }, "required": [ "size", "title", "base_profile" ] }, "BimiSvgTerm": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL associated with the metadata.", "example": "https://example.com" }, "errors": { "description": "An array of error messages.", "example": [ { "code": "ERR001", "message": "Invalid format." }, { "code": "ERR002", "message": "Missing required field." } ], "type": "array", "items": { "$ref": "#/components/schemas/BimiValidationMessage" } }, "warnings": { "description": "An array of warning messages.", "example": [ { "code": "WARN001", "message": "Optional field is empty." }, { "code": "WARN002", "message": "Field is deprecated." } ], "type": "array", "items": { "$ref": "#/components/schemas/BimiValidationMessage" } }, "metaData": { "description": "The metadata object, which can be null.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BimiSvgMetaData" } ] } }, "required": [ "url", "errors", "warnings", "metaData" ] }, "BimiCertificateMetadata": { "type": "object", "properties": { "validTo": { "format": "date-time", "type": "string", "description": "The date when the certificate becomes invalid.", "example": "2025-12-31T23:59:59.000Z" }, "validFrom": { "format": "date-time", "type": "string", "description": "The date when the certificate becomes valid.", "example": "2024-01-01T00:00:00.000Z" }, "issuerText": { "type": "string", "description": "Text describing the issuer of the certificate.", "example": "Certificate Authority Inc." }, "domainNames": { "type": "string", "description": "Domain names associated with the certificate.", "example": "example.com" }, "serialNumber": { "type": "string", "description": "The serial number of the certificate.", "example": "1234567890ABCDEF" }, "trademarkText": { "type": "string", "description": "Text describing the trademark associated with the certificate.", "example": "Trademark Example Text" }, "organizationName": { "type": "string", "description": "The organization name associated with the certificate.", "example": "Example Organization LLC" }, "certificateImage": { "type": "string", "description": "Base64-encoded image of the certificate.", "example": "data:image/png;base64,iVBORw0KGgoAAAANS..." } }, "required": [ "validTo", "validFrom", "issuerText", "domainNames", "serialNumber", "trademarkText", "organizationName", "certificateImage" ] }, "BimiCertificateTerm": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL associated with the metadata.", "example": "https://example.com" }, "errors": { "description": "An array of error messages.", "example": [ { "code": "ERR001", "message": "Invalid format." }, { "code": "ERR002", "message": "Missing required field." } ], "type": "array", "items": { "$ref": "#/components/schemas/BimiValidationMessage" } }, "warnings": { "description": "An array of warning messages.", "example": [ { "code": "WARN001", "message": "Optional field is empty." }, { "code": "WARN002", "message": "Field is deprecated." } ], "type": "array", "items": { "$ref": "#/components/schemas/BimiValidationMessage" } }, "metaData": { "description": "The metadata object, which can be null.", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BimiCertificateMetadata" } ] } }, "required": [ "url", "errors", "warnings", "metaData" ] }, "BimiRecordObject": { "type": "object", "properties": { "terms": { "type": "array", "items": { "$ref": "#/components/schemas/BimiRecordTerm" } }, "version": { "type": "string", "example": "v=BIMI1" }, "svg": { "$ref": "#/components/schemas/BimiSvgTerm" }, "certificate": { "$ref": "#/components/schemas/BimiCertificateTerm" } }, "required": [ "terms", "svg", "certificate" ] }, "BimiValidation": { "type": "object", "properties": { "warnings": { "description": "The list of errors found while parsing the BIMI record.", "example": [ { "message": "Invalid BIMI version.", "position": { "start": 0, "end": 6 } } ], "type": "array", "items": { "$ref": "#/components/schemas/BimiValidationMessage" } }, "errors": { "description": "The list of errors found while parsing the BIMI record.", "example": [ { "message": "Invalid BIMI version.", "position": { "start": 0, "end": 6 } } ], "type": "array", "items": { "$ref": "#/components/schemas/BimiValidationMessage" } }, "info": { "description": "The list of errors found while parsing the BIMI record.", "example": [ { "message": "Invalid BIMI version.", "position": { "start": 0, "end": 6 } } ], "type": "array", "items": { "$ref": "#/components/schemas/BimiValidationMessage" } } }, "required": [ "warnings", "errors", "info" ] }, "BimiRecord": { "type": "object", "properties": { "domain": { "type": "string", "nullable": false, "description": "The domain name of the BIMI record.", "example": "example.com" }, "raw": { "type": "string", "nullable": false, "description": "The raw BIMI record.", "example": "v=BIMI1; l=https://example.com/logo.svg" }, "object": { "description": "The parsed BIMI record.", "allOf": [ { "$ref": "#/components/schemas/BimiRecordObject" } ] }, "validation": { "description": "The validation of the BIMI record.", "allOf": [ { "$ref": "#/components/schemas/BimiValidation" } ] }, "queryStatus": { "example": "NOTFOUND", "$ref": "#/components/schemas/DnsRecordStatus" }, "timestamp": { "type": "number", "description": "The timestamp of the BIMI record lookup.", "example": 1704067200000 } }, "required": [ "domain", "raw", "object", "validation", "queryStatus", "timestamp" ] }, "BatchRecordsRequest": { "type": "object", "properties": { "maxAgeMs": { "type": "number", "example": 5000, "description": "The maximum age of the cache in milliseconds [0]-fetch dns, [-1]-from cache" }, "domains": { "example": [ "example.com", "example.org" ], "type": "array", "items": { "type": "string" } } }, "required": [ "domains" ] }, "ValidationRequest": { "type": "object", "properties": { "record": { "type": "string", "example": "v=BIMI1;l=https://example.com/logo.svg;a=https://example.com/cert.pem" }, "domain": { "type": "string", "example": "example.com" } }, "required": [ "record", "domain" ] }, "ReverseDnsResponse": { "type": "object", "properties": { "raw": { "description": "The raw records.", "type": "array", "items": { "type": "string" } }, "query": { "type": "string", "example": "8.8.4.4", "description": "The original IP address that was queried" }, "reverseName": { "type": "string", "example": "4.4.8.8.in-addr.arpa.", "description": "The reverse DNS name (PTR record) for the IP address" }, "domain": { "type": "string", "example": "dns.google.", "description": "The domain name that the IP address resolves to" }, "validation": { "description": "The validation of the reverse lookup", "allOf": [ { "$ref": "#/components/schemas/DnsValidationResult" } ] }, "queryStatus": { "type": "string", "enum": [ "SUCCESS", "NODATA", "NOTFOUND", "TIMEOUT", "ERROR", "SERVFAIL", "NXDOMAIN" ], "example": "SUCCESS", "description": "DNS resolution status code" } }, "required": [ "raw", "query", "reverseName", "queryStatus" ] }, "PageMeta_3": { "type": "object", "properties": { "page": { "type": "number", "minimum": 1, "default": 1 }, "limit": { "type": "number", "minimum": 1, "default": 10 }, "total": { "type": "number", "minimum": 0, "default": 0 }, "pageCount": { "type": "number", "minimum": 0, "default": 0 }, "hasPreviousPage": { "type": "boolean", "default": false }, "hasNextPage": { "type": "boolean", "default": false } }, "required": [ "page", "limit", "total", "pageCount", "hasPreviousPage", "hasNextPage" ] }, "SpfResult": { "type": "object", "properties": { "rootDomain": { "type": "string", "description": "SPF root domain", "example": "send.reports.easydmarc.com" }, "domain": { "type": "string", "description": "SPF domain", "example": "send.reports.easydmarc.com" }, "scope": { "type": "string", "description": "SPF scope", "enum": [ "helo", "mfrom" ], "example": "helo" }, "result": { "type": "string", "description": "SPF result", "enum": [ "none", "neutral", "pass", "fail", "softfail", "temperror", "permerror" ], "example": "pass" }, "isAligned": { "type": "boolean", "description": "Whether SPF is aligned", "example": true }, "isPtrAligned": { "type": "boolean", "description": "Whether PTR is aligned", "example": false } } }, "DkimResult": { "type": "object", "properties": { "rootDomain": { "type": "string", "description": "DKIM root domain", "example": "amazonses.com" }, "domain": { "type": "string", "description": "DKIM domain", "example": "amazonses.com" }, "selector": { "type": "string", "description": "DKIM selector", "example": "6gbrjpgwjskckoa6a5zn6fwqkn67xbtt" }, "result": { "type": "string", "description": "DKIM result", "enum": [ "none", "neutral", "pass", "fail", "softfail", "temperror", "permerror", "unknown" ], "example": "pass" }, "humanResult": { "type": "string", "description": "Human-readable result", "example": "" }, "isAligned": { "type": "boolean", "description": "Whether DKIM is aligned", "example": false }, "isPtrAligned": { "type": "boolean", "description": "Whether PTR is aligned", "example": true } }, "required": [ "rootDomain", "domain", "selector", "humanResult", "isAligned", "isPtrAligned" ] }, "DmarcReport": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier for the report", "example": "4f1721bd-e722-43b1-9bdd-cf7f86b6c4b5" }, "objectId": { "type": "string", "description": "Object identifier", "example": "63896330834733f685f09626" }, "dmarcFile": { "type": "string", "description": "Associated DMARC file name", "nullable": true }, "reportId": { "type": "string", "description": "Report identifier", "example": "1755652172.810369" }, "reportType": { "type": "string", "description": "Type of the report", "example": "dmarc-capable" }, "explicitReportType": { "type": "string", "description": "Explicit report type classification", "enum": [ "forwarded", "non-compliant", "threat" ], "example": "forwarded" }, "policyDomain": { "type": "string", "description": "Domain for which the policy applies", "example": "test.com" }, "startDate": { "format": "date-time", "type": "string", "description": "Report period start date", "example": "2025-08-19T00:00:00.000Z" }, "endDate": { "format": "date-time", "type": "string", "description": "Report period end date", "example": "2025-08-19T23:00:00.000Z" }, "reportDate": { "format": "date", "type": "string", "description": "Date when report was generated", "example": "2025-08-19" }, "createdAt": { "format": "date-time", "type": "string", "description": "Record creation timestamp", "example": "2025-08-20T16:12:45.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Record last update timestamp", "example": "2025-08-20T16:12:45.000Z" }, "count": { "type": "number", "description": "Number of messages matching this report entry", "example": 100 }, "disposition": { "type": "string", "description": "DMARC disposition (none, quarantine, reject)", "example": "none" }, "countryCode": { "type": "string", "description": "ISO country code of source IP", "example": "US" }, "email": { "type": "string", "description": "Associated email address", "example": "test@test.com" }, "headerFrom": { "type": "string", "description": "Header From domain", "example": "reports.easydmarc.com" }, "envelopeTo": { "type": "string", "description": "Envelope To domain", "example": "test.com" }, "envelopeFrom": { "type": "string", "description": "Envelope From domain", "example": "testing.com" }, "fo": { "type": "string", "description": "Forensic reporting options" }, "dkimAligned": { "type": "string", "description": "DKIM alignment status" }, "spfAligned": { "type": "string", "description": "SPF alignment status" }, "inboxEmail": { "type": "string", "description": "Inbox email address", "nullable": true, "example": "46436954e5@rua.easydmarc.asia" }, "location": { "type": "array", "description": "Geographic coordinates [longitude, latitude]", "items": { "type": "number" }, "nullable": true, "example": [ -122.29, 47.58 ] }, "orgDomain": { "type": "string", "description": "Organization domain" }, "orgName": { "type": "string", "description": "Organization name", "example": "test.com" }, "pct": { "type": "number", "description": "Percentage tag value from DMARC policy", "example": 100 }, "policyP": { "type": "string", "description": "DMARC policy for domain", "enum": [ "none", "quarantine", "reject" ], "example": "reject" }, "policySp": { "type": "string", "description": "DMARC policy for subdomains", "enum": [ "none", "quarantine", "reject" ], "nullable": true, "example": "none" }, "ptr": { "type": "string", "description": "PTR record value", "example": "a9-108.smtp-out.amazonses.com" }, "ptrGroup": { "type": "string", "description": "PTR group classification", "example": "amazonses.com" }, "reasonComment": { "type": "string", "description": "Reason comment for policy override", "example": "test" }, "reasonType": { "type": "string", "description": "Reason type for policy override", "enum": [ "forwarded", "sampled_out", "trusted_forwarder", "mailing_list", "local_policy", "other", "none" ], "nullable": true, "example": "forwarded" }, "senderDomain": { "type": "string", "description": "Sender domain", "example": "reports.easydmarc.com" }, "sourceIpStr": { "type": "string", "description": "Source IP address as string", "example": "::ffff:54.240.9.107" }, "sourceIp": { "type": "string", "description": "Source IP address", "example": "54.240.9.108" }, "spf": { "type": "string", "description": "SPF authentication result", "example": "pass" }, "aspf": { "type": "string", "description": "SPF alignment mode", "enum": [ "r", "s" ], "nullable": true, "example": "r" }, "spfResult": { "description": "SPF authentication result details", "allOf": [ { "$ref": "#/components/schemas/SpfResult" } ] }, "dkim": { "type": "string", "description": "DKIM authentication result", "example": "pass" }, "adkim": { "type": "string", "description": "DKIM alignment mode", "enum": [ "r", "s" ], "nullable": true, "example": "r" }, "dkimResults": { "description": "Array of DKIM authentication results", "type": "array", "items": { "$ref": "#/components/schemas/DkimResult" } }, "dkimResultsLength": { "type": "number", "description": "Number of DKIM results", "example": 1 }, "blacklisteds": { "type": "array", "description": "Array of blacklist indicators", "items": { "type": "string" }, "example": [ "test.test.net" ] } }, "required": [ "uuid", "objectId", "reportId", "reportType", "policyDomain", "startDate", "endDate", "reportDate", "createdAt", "updatedAt", "count", "disposition", "countryCode", "email", "headerFrom", "envelopeTo", "envelopeFrom", "fo", "dkimAligned", "spfAligned", "orgDomain", "orgName", "pct", "policyP", "ptr", "ptrGroup", "reasonComment", "senderDomain", "sourceIpStr", "sourceIp", "spf", "spfResult", "dkim", "dkimResults", "dkimResultsLength", "blacklisteds" ] }, "FilterValue": { "type": "object", "properties": { "name": { "type": "string", "description": "Field name to filter on", "enum": [ "policy_domain", "ptr", "ptr_group", "source_ip_str", "org_name", "country_code", "temp_id", "report_type", "count", "total_volume", "dkim_pass_rate", "spf_pass_rate", "compliance_rate", "disposition", "dmarc", "spf", "dkim", "reason_type", "sender_domain", "dkim_aligned", "dkim_selector", "dkim_domain", "dkim_result", "spf_aligned", "spf_result", "spf_domain", "spf_scope", "dkim_count", "report_id" ] }, "type": { "type": "string", "description": "Filter operator type", "enum": [ "eq", "ne", "in", "nin", "nset", "sw", "ew", "sin", "range", "gt", "gte", "lt", "lte" ] }, "value": { "type": "object", "description": "Value to filter by (type depends on operator)" } }, "required": [ "name", "type", "value" ] }, "DateRange": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date in ISO format", "example": "2025-07-24T13:24:07.352Z" }, "to": { "type": "string", "description": "End date in ISO format", "example": "2025-07-24T13:24:07.373Z" } }, "required": [ "from", "to" ] }, "OrderField": { "type": "object", "properties": { "field": { "type": "string", "description": "Field name to sort by", "enum": [ "uuid", "object_id", "temp_id", "dmarc_file", "report_id", "report_type", "explicit_report_type", "policy_domain", "start_date", "end_date", "report_date", "created_at", "updated_at", "count", "disposition", "country_code", "email", "header_from", "envelope_from", "envelope_to", "fo", "inbox_email", "location", "org_domain", "org_name", "pct", "policy_p", "policy_sp", "ptr", "ptr_group", "reason_comment", "reason_type", "sender_domain", "source_ip", "source_ip_str", "spf", "aspf", "spf_auth_root_domain", "spf_auth_domain", "spf_auth_scope", "spf_auth_result", "spf_auth_is_aligned", "spf_auth_is_ptr_aligned", "dkim", "adkim", "dkim_auth.root_domain", "dkim_auth.domain", "dkim_auth.selector", "dkim_auth.result", "dkim_auth.human_result", "dkim_auth.is_aligned", "dkim_auth.is_ptr_aligned", "dkim_results_length", "blacklisteds" ], "example": "report_date" }, "direction": { "type": "string", "description": "Sort direction", "enum": [ "asc", "desc" ], "example": "desc" } }, "required": [ "field", "direction" ] }, "ReportRawDataRequest": { "type": "object", "properties": { "domainNames": { "description": "Array of fully qualified domain names", "example": [ "example.com", "test.com" ], "type": "array", "items": { "type": "string" } }, "reportType": { "type": "string", "description": "Type of DMARC reports to retrieve", "enum": [ "dmarc-capable", "non-compliant", "threat-unknown", "forwarded" ] }, "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange" } ] }, "filters": { "type": "object", "description": "Advanced filtering options keyed by field name", "additionalProperties": { "$ref": "#/components/schemas/FilterValue" } }, "properties": { "type": "array", "description": "Optional array of specific fields to return in response", "items": { "type": "string", "enum": [ "uuid", "object_id", "temp_id", "dmarc_file", "report_id", "report_type", "explicit_report_type", "policy_domain", "start_date", "end_date", "report_date", "created_at", "updated_at", "count", "disposition", "country_code", "email", "header_from", "envelope_from", "envelope_to", "fo", "inbox_email", "location", "org_domain", "org_name", "pct", "policy_p", "policy_sp", "ptr", "ptr_group", "reason_comment", "reason_type", "sender_domain", "source_ip", "source_ip_str", "spf", "aspf", "spf_auth_root_domain", "spf_auth_domain", "spf_auth_scope", "spf_auth_result", "spf_auth_is_aligned", "spf_auth_is_ptr_aligned", "dkim", "adkim", "dkim_auth.root_domain", "dkim_auth.domain", "dkim_auth.selector", "dkim_auth.result", "dkim_auth.human_result", "dkim_auth.is_aligned", "dkim_auth.is_ptr_aligned", "dkim_results_length", "blacklisteds" ] } }, "orderFields": { "description": "Array of fields and directions for sorting results", "type": "array", "items": { "$ref": "#/components/schemas/OrderField" } }, "page": { "type": "number", "description": "Page number for pagination (1-based)", "minimum": 1, "default": 1 }, "pageSize": { "type": "number", "description": "Number of records per page", "minimum": 1, "maximum": 10000, "default": 1000 } }, "required": [ "domainNames", "reportType", "dateRange", "filters" ] }, "DistinctPropertyValue": { "type": "object", "properties": { "value": { "type": "string", "description": "The distinct property value", "example": "example.com" } }, "required": [ "value" ] }, "PropertyRequest": { "type": "object", "properties": { "domainNames": { "description": "Array of fully qualified domain names", "example": [ "example.com", "test.com" ], "type": "array", "items": { "type": "string" } }, "reportTypes": { "type": "array", "description": "Array of report types to include", "items": { "type": "string", "enum": [ "dmarc-capable", "non-compliant", "threat-unknown", "forwarded" ] } }, "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange" } ] }, "property": { "type": "string", "description": "The DMARC report field to get distinct values for", "enum": [ "uuid", "object_id", "temp_id", "dmarc_file", "report_id", "report_type", "explicit_report_type", "policy_domain", "start_date", "end_date", "report_date", "created_at", "updated_at", "count", "disposition", "country_code", "email", "header_from", "envelope_from", "envelope_to", "fo", "inbox_email", "location", "org_domain", "org_name", "pct", "policy_p", "policy_sp", "ptr", "ptr_group", "reason_comment", "reason_type", "sender_domain", "source_ip", "source_ip_str", "spf", "aspf", "spf_auth_root_domain", "spf_auth_domain", "spf_auth_scope", "spf_auth_result", "spf_auth_is_aligned", "spf_auth_is_ptr_aligned", "dkim", "adkim", "dkim_auth.root_domain", "dkim_auth.domain", "dkim_auth.selector", "dkim_auth.result", "dkim_auth.human_result", "dkim_auth.is_aligned", "dkim_auth.is_ptr_aligned", "dkim_results_length", "blacklisteds" ], "default": "policy_domain" }, "filters": { "type": "object", "description": "Advanced filtering options keyed by field name", "additionalProperties": { "$ref": "#/components/schemas/FilterValue" } }, "page": { "type": "number", "description": "Page number for pagination (1-based)", "minimum": 1, "default": 1 }, "pageSize": { "type": "number", "description": "Number of records per page (max 100)", "minimum": 1, "maximum": 100, "default": 100 } }, "required": [ "domainNames", "reportTypes", "dateRange", "property", "filters" ] }, "AggregatedData": { "type": "object", "properties": { "spfPassQty": { "type": "number", "description": "Count of emails with SPF pass", "example": 15420 }, "dkimPassQty": { "type": "number", "description": "Count of emails with DKIM pass", "example": 14850 }, "spfFailQty": { "type": "number", "description": "Count of emails with SPF fail", "example": 2340 }, "dkimFailQty": { "type": "number", "description": "Count of emails with DKIM fail", "example": 2910 }, "dispositionNoneQty": { "type": "number", "description": "Count of emails with DMARC disposition 'none'", "example": 17760 }, "dispositionRejectQty": { "type": "number", "description": "Count of emails with DMARC disposition 'reject'", "example": 0 }, "dispositionQuarantineQty": { "type": "number", "description": "Count of emails with DMARC disposition 'quarantine'", "example": 0 } }, "required": [ "spfPassQty", "dkimPassQty", "spfFailQty", "dkimFailQty", "dispositionNoneQty", "dispositionRejectQty", "dispositionQuarantineQty" ] }, "AggregationObject": { "type": "object", "properties": { "field": { "type": "string", "description": "Field to aggregate by", "enum": [ "spf", "dkim", "disposition" ] }, "value": { "type": "string", "description": "Value to match for aggregation", "enum": [ "pass", "fail", "none", "quarantine", "reject" ] } }, "required": [ "field", "value" ] }, "AggregationRequest": { "type": "object", "properties": { "domainNames": { "description": "Array of fully qualified domain names", "example": [ "example.com", "test.com" ], "type": "array", "items": { "type": "string" } }, "reportTypes": { "type": "array", "description": "Array of report types to include", "items": { "type": "string", "enum": [ "dmarc-capable", "non-compliant", "threat-unknown", "forwarded" ] } }, "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange" } ] }, "aggregations": { "description": "Array of field-value pairs to aggregate by", "type": "array", "items": { "$ref": "#/components/schemas/AggregationObject" } }, "filters": { "type": "object", "description": "Advanced filtering options keyed by field name", "additionalProperties": { "$ref": "#/components/schemas/FilterValue" } }, "groupByFields": { "type": "array", "description": "Fields to group aggregation results by", "default": [ "policy_domain" ], "items": { "type": "string", "enum": [ "uuid", "object_id", "temp_id", "dmarc_file", "report_id", "report_type", "explicit_report_type", "policy_domain", "start_date", "end_date", "report_date", "created_at", "updated_at", "count", "disposition", "country_code", "email", "header_from", "envelope_from", "envelope_to", "fo", "inbox_email", "location", "org_domain", "org_name", "pct", "policy_p", "policy_sp", "ptr", "ptr_group", "reason_comment", "reason_type", "sender_domain", "source_ip", "source_ip_str", "spf", "aspf", "spf_auth_root_domain", "spf_auth_domain", "spf_auth_scope", "spf_auth_result", "spf_auth_is_aligned", "spf_auth_is_ptr_aligned", "dkim", "adkim", "dkim_auth.root_domain", "dkim_auth.domain", "dkim_auth.selector", "dkim_auth.result", "dkim_auth.human_result", "dkim_auth.is_aligned", "dkim_auth.is_ptr_aligned", "dkim_results_length", "blacklisteds" ] } }, "orderFields": { "description": "Array of fields and directions for sorting results", "type": "array", "items": { "$ref": "#/components/schemas/OrderField" } }, "page": { "type": "number", "description": "Page number for pagination (1-based)", "minimum": 1, "default": 1 }, "pageSize": { "type": "number", "description": "Number of records per page (max 100)", "minimum": 1, "maximum": 100, "default": 100 } }, "required": [ "domainNames", "reportTypes", "dateRange", "aggregations", "filters" ] }, "VolumeRequest": { "type": "object", "properties": { "domainNames": { "description": "Array of fully qualified domain names", "example": [ "example.com", "test.com" ], "type": "array", "items": { "type": "string" } }, "reportTypes": { "type": "array", "description": "Array of report types to include in volume calculation", "items": { "type": "string", "enum": [ "dmarc-capable", "non-compliant", "threat-unknown", "forwarded" ] } }, "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange" } ] }, "filters": { "type": "object", "description": "Advanced filtering options keyed by field name", "additionalProperties": { "$ref": "#/components/schemas/FilterValue" } }, "groupByFields": { "type": "array", "description": "Fields to group volume data by (excludes count field)", "default": [ "policy_domain" ], "items": { "type": "string", "enum": [ "uuid", "object_id", "temp_id", "dmarc_file", "report_id", "report_type", "explicit_report_type", "policy_domain", "start_date", "end_date", "report_date", "created_at", "updated_at", "count", "disposition", "country_code", "email", "header_from", "envelope_from", "envelope_to", "fo", "inbox_email", "location", "org_domain", "org_name", "pct", "policy_p", "policy_sp", "ptr", "ptr_group", "reason_comment", "reason_type", "sender_domain", "source_ip", "source_ip_str", "spf", "aspf", "spf_auth_root_domain", "spf_auth_domain", "spf_auth_scope", "spf_auth_result", "spf_auth_is_aligned", "spf_auth_is_ptr_aligned", "dkim", "adkim", "dkim_auth.root_domain", "dkim_auth.domain", "dkim_auth.selector", "dkim_auth.result", "dkim_auth.human_result", "dkim_auth.is_aligned", "dkim_auth.is_ptr_aligned", "dkim_results_length", "blacklisteds" ] } }, "orderFields": { "description": "Array of fields and directions for sorting results", "type": "array", "items": { "$ref": "#/components/schemas/OrderField" } }, "page": { "type": "number", "description": "Page number for pagination (1-based)", "minimum": 1, "default": 1 }, "pageSize": { "type": "number", "description": "Number of records per page (max 100)", "minimum": 1, "maximum": 100, "default": 100 } }, "required": [ "domainNames", "reportTypes", "dateRange", "filters" ] }, "DmarcReportVolumePerPeriod": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier for the report", "example": "4f1721bd-e722-43b1-9bdd-cf7f86b6c4b5" }, "objectId": { "type": "string", "description": "Object identifier", "example": "63896330834733f685f09626" }, "dmarcFile": { "type": "string", "description": "Associated DMARC file name", "nullable": true }, "reportId": { "type": "string", "description": "Report identifier", "example": "1755652172.810369" }, "reportType": { "type": "string", "description": "Type of the report", "example": "dmarc-capable" }, "explicitReportType": { "type": "string", "description": "Explicit report type classification", "enum": [ "forwarded", "non-compliant", "threat" ], "example": "forwarded" }, "policyDomain": { "type": "string", "description": "Domain for which the policy applies", "example": "test.com" }, "startDate": { "format": "date-time", "type": "string", "description": "Report period start date", "example": "2025-08-19T00:00:00.000Z" }, "endDate": { "format": "date-time", "type": "string", "description": "Report period end date", "example": "2025-08-19T23:00:00.000Z" }, "reportDate": { "format": "date", "type": "string", "description": "Date when report was generated", "example": "2025-08-19" }, "createdAt": { "format": "date-time", "type": "string", "description": "Record creation timestamp", "example": "2025-08-20T16:12:45.000Z" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Record last update timestamp", "example": "2025-08-20T16:12:45.000Z" }, "count": { "type": "number", "description": "Number of messages matching this report entry", "example": 100 }, "disposition": { "type": "string", "description": "DMARC disposition (none, quarantine, reject)", "example": "none" }, "countryCode": { "type": "string", "description": "ISO country code of source IP", "example": "US" }, "email": { "type": "string", "description": "Associated email address", "example": "test@test.com" }, "headerFrom": { "type": "string", "description": "Header From domain", "example": "reports.easydmarc.com" }, "envelopeTo": { "type": "string", "description": "Envelope To domain", "example": "test.com" }, "envelopeFrom": { "type": "string", "description": "Envelope From domain", "example": "testing.com" }, "fo": { "type": "string", "description": "Forensic reporting options" }, "dkimAligned": { "type": "string", "description": "DKIM alignment status" }, "spfAligned": { "type": "string", "description": "SPF alignment status" }, "inboxEmail": { "type": "string", "description": "Inbox email address", "nullable": true, "example": "46436954e5@rua.easydmarc.asia" }, "location": { "type": "array", "description": "Geographic coordinates [longitude, latitude]", "items": { "type": "number" }, "nullable": true, "example": [ -122.29, 47.58 ] }, "orgDomain": { "type": "string", "description": "Organization domain" }, "orgName": { "type": "string", "description": "Organization name", "example": "test.com" }, "pct": { "type": "number", "description": "Percentage tag value from DMARC policy", "example": 100 }, "policyP": { "type": "string", "description": "DMARC policy for domain", "enum": [ "none", "quarantine", "reject" ], "example": "reject" }, "policySp": { "type": "string", "description": "DMARC policy for subdomains", "enum": [ "none", "quarantine", "reject" ], "nullable": true, "example": "none" }, "ptr": { "type": "string", "description": "PTR record value", "example": "a9-108.smtp-out.amazonses.com" }, "ptrGroup": { "type": "string", "description": "PTR group classification", "example": "amazonses.com" }, "reasonComment": { "type": "string", "description": "Reason comment for policy override", "example": "test" }, "reasonType": { "type": "string", "description": "Reason type for policy override", "enum": [ "forwarded", "sampled_out", "trusted_forwarder", "mailing_list", "local_policy", "other", "none" ], "nullable": true, "example": "forwarded" }, "senderDomain": { "type": "string", "description": "Sender domain", "example": "reports.easydmarc.com" }, "sourceIpStr": { "type": "string", "description": "Source IP address as string", "example": "::ffff:54.240.9.107" }, "sourceIp": { "type": "string", "description": "Source IP address", "example": "54.240.9.108" }, "spf": { "type": "string", "description": "SPF authentication result", "example": "pass" }, "aspf": { "type": "string", "description": "SPF alignment mode", "enum": [ "r", "s" ], "nullable": true, "example": "r" }, "spfResult": { "description": "SPF authentication result details", "allOf": [ { "$ref": "#/components/schemas/SpfResult" } ] }, "dkim": { "type": "string", "description": "DKIM authentication result", "example": "pass" }, "adkim": { "type": "string", "description": "DKIM alignment mode", "enum": [ "r", "s" ], "nullable": true, "example": "r" }, "dkimResults": { "description": "Array of DKIM authentication results", "type": "array", "items": { "$ref": "#/components/schemas/DkimResult" } }, "dkimResultsLength": { "type": "number", "description": "Number of DKIM results", "example": 1 }, "blacklisteds": { "type": "array", "description": "Array of blacklist indicators", "items": { "type": "string" }, "example": [ "test.test.net" ] }, "qty": { "type": "number", "description": "Volume quantity for the period (same as count)", "example": 15420 }, "date": { "type": "string", "description": "Date representing the time period (YYYY-MM-DD format)", "format": "date", "example": "2024-01-15" } }, "required": [ "uuid", "objectId", "reportId", "reportType", "policyDomain", "startDate", "endDate", "reportDate", "createdAt", "updatedAt", "count", "disposition", "countryCode", "email", "headerFrom", "envelopeTo", "envelopeFrom", "fo", "dkimAligned", "spfAligned", "orgDomain", "orgName", "pct", "policyP", "ptr", "ptrGroup", "reasonComment", "senderDomain", "sourceIpStr", "sourceIp", "spf", "spfResult", "dkim", "dkimResults", "dkimResultsLength", "blacklisteds", "qty", "date" ] }, "ReportsForPeriodRequest": { "type": "object", "properties": { "domainNames": { "description": "Array of fully qualified domain names", "example": [ "example.com", "test.com" ], "type": "array", "items": { "type": "string" } }, "reportTypes": { "type": "array", "description": "Array of report types to include", "items": { "type": "string", "enum": [ "dmarc-capable", "non-compliant", "threat-unknown", "forwarded" ] } }, "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange" } ] }, "filters": { "type": "object", "description": "Advanced filtering options keyed by field name", "additionalProperties": { "$ref": "#/components/schemas/FilterValue" } }, "period": { "type": "string", "description": "Time period for aggregation", "enum": [ "day", "week", "month" ], "default": "day" }, "groupByFields": { "type": "array", "description": "Fields to group volume data by", "default": [ "policy_domain" ], "items": { "type": "string", "enum": [ "uuid", "object_id", "temp_id", "dmarc_file", "report_id", "report_type", "explicit_report_type", "policy_domain", "start_date", "end_date", "report_date", "created_at", "updated_at", "count", "disposition", "country_code", "email", "header_from", "envelope_from", "envelope_to", "fo", "inbox_email", "location", "org_domain", "org_name", "pct", "policy_p", "policy_sp", "ptr", "ptr_group", "reason_comment", "reason_type", "sender_domain", "source_ip", "source_ip_str", "spf", "aspf", "spf_auth_root_domain", "spf_auth_domain", "spf_auth_scope", "spf_auth_result", "spf_auth_is_aligned", "spf_auth_is_ptr_aligned", "dkim", "adkim", "dkim_auth.root_domain", "dkim_auth.domain", "dkim_auth.selector", "dkim_auth.result", "dkim_auth.human_result", "dkim_auth.is_aligned", "dkim_auth.is_ptr_aligned", "dkim_results_length", "blacklisteds" ] } }, "orderFields": { "description": "Array of fields and directions for sorting results", "type": "array", "items": { "$ref": "#/components/schemas/OrderField" } }, "page": { "type": "number", "description": "Page number for pagination (1-based)", "minimum": 1, "default": 1 }, "pageSize": { "type": "number", "description": "Number of records per page", "minimum": 1, "default": 100 } }, "required": [ "domainNames", "reportTypes", "dateRange", "filters" ] }, "PassRate": { "type": "object", "properties": { "policyDomain": { "type": "string", "description": "The policy domain", "example": "example.com" }, "dkimPassRate": { "type": "number", "description": "DKIM authentication pass rate as a percentage (0.0-100.0)", "example": 94.5 }, "spfPassRate": { "type": "number", "description": "SPF authentication pass rate as a percentage (0.0-100.0)", "example": 97.2 }, "count": { "type": "string", "description": "Sum of total volume", "example": "1345" } }, "required": [ "policyDomain", "dkimPassRate", "spfPassRate", "count" ] }, "PassRateDataRequest": { "type": "object", "properties": { "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange" } ] }, "filters": { "type": "object", "description": "Advanced filtering options keyed by field name", "additionalProperties": { "$ref": "#/components/schemas/FilterValue" } }, "senderDomainNames": { "description": "Array of sender domain names (optional if parkedDomainNames is provided)", "example": [ "example.com", "mail.example.com" ], "type": "array", "items": { "type": "string" } }, "parkedDomainNames": { "description": "Array of parked domain names (optional if senderDomainNames is provided)", "example": [ "parked1.example.com" ], "type": "array", "items": { "type": "string" } }, "page": { "type": "number", "description": "Page number for pagination (1-based)", "minimum": 1, "default": 1 }, "pageSize": { "type": "number", "description": "Number of records per page (max 100)", "minimum": 1, "maximum": 100, "default": 100 } }, "required": [ "dateRange", "filters" ] }, "UserAvatar": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to the user's avatar image", "format": "uri" } } }, "UserAvatarColorRgb": { "type": "string", "enum": [ "#DA6969", "#FFC04D", "#FFB185", "#75CAA9", "#90E4EA", "#5C85FF", "#8DC0FF", "#FDA1E3", "#A57AF2", "#B2A9D0", "#ABB0CB" ] }, "UserAvatarColor": { "type": "object", "properties": { "color": { "allOf": [ { "$ref": "#/components/schemas/UserAvatarColorRgb" } ] } } }, "OrganisationRole": { "type": "string", "enum": [ "owner", "admin", "billing admin", "member" ] }, "InvitationStatus": { "type": "string", "enum": [ "NONE", "SENT", "DEACTIVATED" ] }, "IdpInfo": { "type": "object", "properties": { "providerName": { "type": "string" }, "isEnforcement": { "type": "boolean" }, "displayName": { "type": "string" }, "organizationName": { "type": "string" } }, "required": [ "providerName", "isEnforcement", "displayName", "organizationName" ] }, "Subscription_2": { "type": "object", "properties": {} }, "UserOrganisationProfileData": { "type": "object", "properties": { "id": { "type": "string", "example": "e1c9aca4-268a-4464-a849-7ce0f5adab80" }, "name": { "type": "string", "example": "John Tyson" }, "username": { "type": "string", "example": "johnTyson" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Tyson" }, "emailVerified": { "type": "string", "example": "example@gmail.com" }, "avatar": { "$ref": "#/components/schemas/UserAvatar" }, "avatarColor": { "$ref": "#/components/schemas/UserAvatarColor" }, "organisationRole": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/OrganisationRole" } ] }, "organizationRoles": { "type": "array", "items": { "type": "string" } }, "products": { "type": "array", "items": { "type": "string" } }, "lastActive": { "format": "date-time", "type": "string" }, "invitationStatus": { "example": "NONE", "allOf": [ { "$ref": "#/components/schemas/InvitationStatus" } ] }, "twoFAEnabled": { "type": "boolean", "example": false }, "isOrganizationAdmin": { "type": "boolean" }, "isOrganizationOwner": { "type": "boolean" }, "isSsoForced": { "type": "boolean" }, "organisationType": { "type": "string" }, "hasOnlyViewerRole": { "type": "boolean" }, "hasSsoAccess": { "type": "boolean" }, "idpInfo": { "$ref": "#/components/schemas/IdpInfo" }, "isAzureIntegrated": { "type": "boolean" }, "invitedDate": { "format": "date-time", "type": "string" }, "dmarcOrganisationSubscription": { "$ref": "#/components/schemas/Subscription_2" }, "hasPartnerOrganisation": { "type": "boolean" } }, "required": [ "id", "name", "username", "firstName", "lastName", "emailVerified", "emailVerified", "organisationRole", "products", "lastActive", "invitationStatus", "twoFAEnabled", "isOrganizationAdmin", "isOrganizationOwner", "isSsoForced", "organisationType", "hasOnlyViewerRole" ] }, "PageResponseUserOrganizationProfile": { "type": "object", "properties": { "totalCount": { "type": "number", "example": 10 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserOrganisationProfileData" } } }, "required": [ "totalCount", "items" ] }, "AccountDropdownContent": { "type": "object", "properties": { "activeOrganisation": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" } } }, "activeOrganizationProfile": { "$ref": "#/components/schemas/UserOrganisationProfileData" }, "users": { "$ref": "#/components/schemas/PageResponseUserOrganizationProfile" }, "organisationList": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" } } } } }, "required": [ "activeOrganisation", "activeOrganizationProfile", "users" ] }, "RevokeOrganizationAccessRequest": { "type": "object", "properties": { "requesterUserId": { "type": "string", "description": "The unique identifier of the user making the revocation request" }, "organizationId": { "type": "string", "description": "The unique identifier of the organization from which to revoke user access", "format": "uuid", "example": "8a7b9c2d-1e3f-4a5b-9c8d-7e6f5a4b3c2d" }, "userIds": { "description": "Array of user IDs whose access should be revoked. All users must be members of the specified organization.", "example": [ "4fd475a0-e60a-43a0-82ff-6d9532cc3e9b", "7c8d9e0f-2a3b-4c5d-8e9f-0a1b2c3d4e5f" ], "type": "array", "items": { "type": "string" } } }, "required": [ "requesterUserId", "organizationId", "userIds" ] }, "UserPersonalInfoChange": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Updated first name for the user", "minLength": 1, "maxLength": 100, "example": "Jonathan" }, "lastName": { "type": "string", "description": "Updated last name for the user", "minLength": 1, "maxLength": 100, "example": "Smith" } }, "required": [ "firstName", "lastName" ] }, "ChangePersonalInfo": { "type": "object", "properties": { "userId": { "type": "string", "description": "The unique identifier of the user whose information should be updated", "format": "uuid", "example": "4fd475a0-e60a-43a0-82ff-6d9532cc3e9b" }, "info": { "description": "Object containing the user information fields to update. Only provided fields will be updated.", "example": { "firstName": "Jonathan", "lastName": "Smith" }, "allOf": [ { "$ref": "#/components/schemas/UserPersonalInfoChange" } ] } }, "required": [ "userId", "info" ] }, "GetUserOrganizationProfileData": { "type": "object", "properties": { "requesterUserId": { "type": "string", "example": "223c8101-ff07-460d-aa99-1c3bbdc76931" }, "userId": { "type": "string", "example": "872e8564-7033-4088-81a4-5f6145bfe52f" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" } } } }, "required": [ "requesterUserId", "userId", "organization" ] }, "RoleId": { "type": "string", "enum": [ "Organisation:Owner", "Organisation:Admin", "Organisation:Editor", "Product:Admin", "Product:Editor", "Dmarc:Admin", "Dmarc:Editor", "DmnGroup:Admin", "DmnGroup:Editor", "DmnGroup:Viewer", "Domain:Admin", "Domain:Editor", "Domain:Viewer", "Sender:Admin", "Sender:Editor", "Inguard:Admin", "Inguard:Editor" ] }, "UserListFilterRequest": { "type": "object", "properties": { "query": { "type": "string", "example": "Some query" }, "role": { "allOf": [ { "$ref": "#/components/schemas/RoleId" } ] } } }, "UserListSearchRequest": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/UserListFilterRequest" } }, "required": [ "filter" ] }, "SearchOrganizationUsers": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" } } }, "requesterUserId": { "type": "string", "example": "53422f23-a89a-4d34-acd4-eca3507ec1f7" }, "request": { "$ref": "#/components/schemas/UserListSearchRequest" } }, "required": [ "organization", "requesterUserId", "request" ] }, "SearchOrganizationScimUsers": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" } } }, "request": { "$ref": "#/components/schemas/UserListSearchRequest" } }, "required": [ "organization", "request" ] }, "PermissionDirectory": { "type": "string", "enum": [ "organisation", "product", "resource-group", "resource" ] }, "Permission": { "type": "string", "enum": [ "owner", "admin", "editor", "no_access", "viewer" ] }, "UserPermission": { "type": "object", "properties": { "userId": { "type": "string", "example": "e1c9aca4-268a-4464-a849-7ce0f5adab80" }, "email": { "type": "string", "example": "example@gmail.com" }, "directory": { "example": "organisation", "allOf": [ { "$ref": "#/components/schemas/PermissionDirectory" } ] }, "objectId": { "type": "string", "example": "e1c9aca4-268a-4464-a849-7ce0f5adab80" }, "title": { "type": "string", "example": "Some title" }, "type": { "type": "string", "example": "Some type" }, "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/Permission" } ] } } }, "InviteUsers": { "type": "object", "properties": { "inviterUserId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "organizationId": { "type": "string" }, "permissionDtos": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermission" } }, "redirectUrl": { "type": "string", "example": "https://example.com/redirect" } }, "required": [ "inviterUserId", "organizationId", "permissionDtos" ] }, "UserPermissionUser": { "type": "object", "properties": { "email": { "type": "string" }, "userId": { "type": "string", "format": "uuid" } } }, "OrganizationInvitedPermission": { "type": "string", "enum": [ "admin", "no_access" ] }, "UserPermissionOrganization": { "type": "object", "properties": { "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/OrganizationInvitedPermission" } ] }, "organizationName": { "type": "string", "example": "EasyDMARC" } }, "required": [ "role" ] }, "ProductInvitedPermissionRole": { "type": "string", "enum": [ "admin", "editor", "no_access" ] }, "ProductType_2": { "type": "string", "enum": [ "dmarc", "sender", "inguard" ] }, "UserPermissionProduct": { "type": "object", "properties": { "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/ProductInvitedPermissionRole" } ] }, "productId": { "type": "string", "example": "dmarc_666a8f2eef097adfee1272d7" }, "type": { "example": "dmarc", "allOf": [ { "$ref": "#/components/schemas/ProductType_2" } ] }, "productName": { "type": "string", "example": "DMARC" } }, "required": [ "role", "productId", "type" ] }, "UserPermissionResourceGroup": { "type": "object", "properties": { "resourceGroupId": { "type": "string", "example": "resourceGroupId" }, "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/Permission" } ] }, "resourceGroupName": { "type": "string", "example": "Resource Group Title" } }, "required": [ "resourceGroupId", "role" ] }, "UserPermissionResource": { "type": "object", "properties": { "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/Permission" } ] }, "resourceGroupId": { "type": "string", "example": "resourceGroupId" }, "resourceId": { "type": "string", "example": "resourceId" }, "resourceName": { "type": "string", "example": "Resource Title" } }, "required": [ "role", "resourceGroupId", "resourceId" ] }, "UserPermissionV1": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionUser" } }, "organization": { "$ref": "#/components/schemas/UserPermissionOrganization" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionProduct" } }, "resourceGroups": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionResourceGroup" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionResource" } } }, "required": [ "users" ] }, "InviteUsersV1": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The unique identifier of the organization to which users are being invited", "format": "uuid", "example": "8a7b9c2d-1e3f-4a5b-9c8d-7e6f5a4b3c2d" }, "permissions": { "description": "Permission configuration including user list and role assignments", "allOf": [ { "$ref": "#/components/schemas/UserPermissionV1" } ] }, "redirectUrl": { "type": "string", "description": "URL to redirect users to after they accept the invitation and complete onboarding. Must be a valid HTTPS URL.", "format": "uri", "example": "https://app.easydmarc.com" }, "inviterUserId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" } }, "required": [ "organizationId", "permissions", "inviterUserId" ] }, "SetAvatarColor": { "type": "object", "properties": { "userId": { "type": "string", "example": "d4092e75-11c5-4a61-b948-f87829fe7146" }, "color": { "example": "#5C85FF", "allOf": [ { "$ref": "#/components/schemas/UserAvatarColorRgb" } ] } }, "required": [ "userId", "color" ] }, "OneTimeVerificationCodeResponse": { "type": "object", "properties": { "expiration": { "type": "object", "properties": { "years": { "type": "number", "nullable": true }, "months": { "type": "number", "nullable": true }, "weeks": { "type": "number", "nullable": true }, "days": { "type": "number", "nullable": true }, "hours": { "type": "number", "nullable": true }, "minutes": { "type": "number", "nullable": true }, "seconds": { "type": "number", "nullable": true } } } }, "required": [ "expiration" ] }, "AccountPreTerminationState": { "type": "object", "properties": {} }, "UserConsentRepresentation": { "type": "object", "properties": { "clientId": { "type": "string", "example": "client-123" }, "createDate": { "type": "string", "example": "2024-03-04T12:34:56Z" }, "grantedClientScopes": { "example": [ "openid", "profile" ], "type": "array", "items": { "type": "string" } }, "lastUpdatedDate": { "type": "number", "example": 1678901234567 } } }, "CredentialRepresentation": { "type": "object", "properties": { "createdDate": { "type": "number", "example": 1678901234567 }, "credentialData": { "type": "string", "example": "encrypted-data" }, "id": { "type": "string", "example": "credential-123" }, "priority": { "type": "number", "example": 1 }, "secretData": { "type": "string", "example": "secret-key-data" }, "temporary": { "type": "boolean", "example": false }, "type": { "type": "string", "example": "password" }, "userLabel": { "type": "string", "example": "User Label" }, "value": { "type": "string", "example": "credential-value" } } }, "FederatedIdentityRepresentation": { "type": "object", "properties": { "identityProvider": { "type": "string", "example": "google" }, "userId": { "type": "string", "example": "123456789" }, "userName": { "type": "string", "example": "john.doe" } } }, "UserRepresentation": { "type": "object", "properties": { "id": { "type": "string", "example": "e1c9aca4-268a-4464-a849-7ce0f5adab80" }, "createdTimestamp": { "type": "number", "example": 1678901234567 }, "username": { "type": "string", "example": "johndoe" }, "enabled": { "type": "boolean", "example": true }, "totp": { "type": "boolean", "example": false }, "emailVerified": { "type": "boolean", "example": true }, "disableableCredentialTypes": { "example": [ "password" ], "type": "array", "items": { "type": "string" } }, "requiredActions": { "example": [ "UPDATE_PASSWORD" ], "type": "array", "items": { "type": "string" } }, "notBefore": { "type": "number", "example": 0 }, "access": { "type": "object", "example": { "viewProfile": true, "manageAccount": false } }, "attributes": { "type": "object", "example": { "department": [ "IT" ], "country": [ "US" ] } }, "clientConsents": { "description": "List of user consent representations", "type": "array", "items": { "$ref": "#/components/schemas/UserConsentRepresentation" } }, "clientRoles": { "type": "object" }, "credentials": { "description": "List of credential representations", "type": "array", "items": { "$ref": "#/components/schemas/CredentialRepresentation" } }, "email": { "type": "string", "example": "example@gmail.com" }, "federatedIdentities": { "description": "List of federated identity representations", "type": "array", "items": { "$ref": "#/components/schemas/FederatedIdentityRepresentation" } }, "federationLink": { "type": "string" }, "firstName": { "type": "string", "example": "John" }, "groups": { "example": [ "admin", "developer" ], "type": "array", "items": { "type": "string" } }, "lastName": { "type": "string", "example": "Doe" }, "origin": { "type": "string" }, "realmRoles": { "example": [ "user" ], "type": "array", "items": { "type": "string" } }, "self": { "type": "string" }, "serviceAccountClientId": { "type": "string" } } }, "AddFederatedIdentityRequest": { "type": "object", "properties": { "kcUserId": { "type": "string", "description": "KC User ID" }, "identityUserId": { "type": "string", "description": "Identity User ID" }, "identityProvider": { "type": "string", "description": "Identity Provider" }, "email": { "type": "string", "description": "Email address" } }, "required": [ "kcUserId", "identityUserId", "identityProvider", "email" ] }, "IntegrationName": { "type": "string", "enum": [ "Acronis", "Autotask", "AzureDNS", "Cloudflare", "ConnectWise", "DNSMadeEasy", "EasyDNS", "Gandi", "Godaddy", "GoogleDNS", "GradientMSP", "HaloPSA", "Microsoft", "MS Teams", "Namecheap", "OVH", "Pax8", "Route53", "Sentinel", "Slack", "Splunk", "SyncroMSP" ], "description": "The name of the integration" }, "SendIntegrationSlackNotificationRequest": { "type": "object", "properties": { "integrationName": { "description": "The name of the integration", "allOf": [ { "$ref": "#/components/schemas/IntegrationName" } ] }, "userRepresentation": { "description": "User representation details", "allOf": [ { "$ref": "#/components/schemas/UserRepresentation" } ] }, "messageTitle": { "type": "string", "description": "Title of the message to be sent" } }, "required": [ "integrationName", "userRepresentation", "messageTitle" ] }, "Integrations": { "type": "string", "enum": [ "acronis", "autotask", "azure-dns", "cloudflare-dns", "connect-wise", "dnsmadeeasy-dns", "easydns-dns", "gandi-dns", "godaddy-dns", "google-dns", "gradient-msp", "halo-psa", "microsoft", "ms-teams", "namecheap-dns", "ovh-dns", "pax8", "route53", "sentinel", "slack", "splunk", "syncro" ], "description": "Integration name associated with the organization" }, "CreateOrganizationAndInviteOwnerRequest": { "type": "object", "properties": { "userPermission": { "description": "User permissions for the organization", "allOf": [ { "$ref": "#/components/schemas/UserPermission" } ] }, "integrationName": { "description": "Integration name associated with the organization", "example": "Azure", "allOf": [ { "$ref": "#/components/schemas/Integrations" } ] }, "organizationName": { "type": "string", "description": "Name of the organization to be created", "example": "EasyDMARC" }, "ownerFirstName": { "type": "string", "description": "Owner's first name", "example": "John" }, "firstTimeRedirectUrl": { "type": "string", "description": "First time login redirect URL", "example": "https://example.com/welcome" }, "ownerLastName": { "type": "string", "description": "Owner's last name", "example": "Smith" }, "country": { "type": "string", "description": "Country of the organization or owner", "example": "USA" }, "attributes": { "type": "object", "description": "KC user attributes", "additionalProperties": true }, "requiredActions": { "description": "List of required actions", "type": "array", "items": { "type": "string" } } }, "required": [ "userPermission", "integrationName", "organizationName", "ownerFirstName", "firstTimeRedirectUrl" ] }, "OrganizationAndOwner": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" } } }, "user": { "$ref": "#/components/schemas/UserRepresentation" } }, "required": [ "organization", "user" ] }, "AccountTerminationRequest": { "type": "object", "properties": { "surveyOption": { "type": "string", "example": "Some Survey Option" } }, "required": [ "surveyOption" ] }, "DeviceActivityListConsentScope": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayTest": { "type": "string" } } }, "DeviceActivityListConsent": { "type": "object", "properties": { "grantedScopes": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceActivityListConsentScope" } }, "createdDate": { "format": "date-time", "type": "string" }, "lastUpdatedDate": { "format": "date-time", "type": "string" } } }, "DeviceActivityListClient": { "type": "object", "properties": { "clientId": { "type": "string" }, "clientName": { "type": "string" }, "description": { "type": "string" }, "userConsentRequired": { "type": "boolean" }, "offlineAccess": { "type": "boolean" }, "rootUrl": { "type": "string" }, "baseUrl": { "type": "string" }, "effectiveUrl": { "type": "string" }, "consent": { "$ref": "#/components/schemas/DeviceActivityListConsent" }, "logoUri": { "type": "string" }, "policyUri": { "type": "string" }, "tosUri": { "type": "string" } } }, "DeviceActivityListSession": { "type": "object", "properties": { "id": { "type": "string" }, "ipAddress": { "type": "string" }, "started": { "format": "date-time", "type": "string" }, "lastAccess": { "format": "date-time", "type": "string" }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceActivityListClient" } }, "browser": { "type": "string" }, "current": { "type": "boolean" } } }, "DeviceActivityListItem": { "type": "object", "properties": { "id": { "type": "string" }, "ipAddress": { "type": "string" }, "os": { "type": "string" }, "osVersion": { "type": "string" }, "browser": { "type": "string" }, "device": { "type": "string" }, "lastAccess": { "format": "date-time", "type": "string" }, "current": { "type": "boolean" }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceActivityListSession" } }, "mobile": { "type": "boolean" } } }, "ItemsListDeviceActivityListItem": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceActivityListItem" } } }, "required": [ "items" ] }, "OtpStatus": { "type": "object", "properties": { "enabled": { "format": "date-time", "type": "string" } }, "required": [ "enabled" ] }, "AccountCredentialsStatusesResponse": { "type": "object", "properties": { "passwordCreated": { "format": "date-time", "type": "string" }, "passwordResetDate": { "format": "date-time", "type": "string" }, "recentPasswordChangeCount": { "type": "number", "example": 2, "description": "Number of password changes in the last 24 hours" } } }, "LinkAccountCanNotUnlinkReason": { "type": "string", "enum": [ "PASSWORD_NOT_SET" ] }, "LinkedAccountUnlink": { "type": "object", "properties": { "allowed": { "type": "boolean", "example": false }, "string": { "example": "PASSWORD_NOT_SET", "allOf": [ { "$ref": "#/components/schemas/LinkAccountCanNotUnlinkReason" } ] } }, "required": [ "allowed" ] }, "LinkedAccountsListItem": { "type": "object", "properties": { "connected": { "type": "boolean", "example": false }, "providerAlias": { "type": "string", "example": "Some Provider Alias" }, "providerName": { "type": "string", "example": "Some Provider Name" }, "displayName": { "type": "string", "example": "Some Display Name" }, "linkedUsername": { "type": "string", "example": "Some Linked Username" }, "social": { "type": "boolean", "example": false }, "unlink": { "$ref": "#/components/schemas/LinkedAccountUnlink" } }, "required": [ "connected", "providerAlias", "providerName", "displayName", "linkedUsername", "social" ] }, "LinkSocialIdentityProvider": { "type": "object", "properties": { "userId": { "type": "string", "example": "d2ec3ba0-7ef5-4591-a8ef-77478a7272f7" }, "clientId": { "type": "string", "example": "some_app_client_id" }, "sessionState": { "type": "string" }, "providerAlias": { "type": "string", "example": "My Alias" }, "redirectUrl": { "type": "string", "example": "https://redirect.com" } }, "required": [ "userId", "clientId", "sessionState", "providerAlias", "redirectUrl" ] }, "LinkAccountResponse": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, "PotentialOwnersGetRequest": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" } } }, "authenticatedUserId": { "type": "string", "example": "abf4e9ce-4393-4bf7-9f1e-440a0ff26755" }, "request": { "$ref": "#/components/schemas/UserListSearchRequest" } }, "required": [ "organization", "authenticatedUserId", "request" ] }, "GetPermissionsRequest": { "type": "object", "properties": { "organizationId": { "type": "string" }, "requesterId": { "type": "string" }, "request": { "$ref": "#/components/schemas/UserPermission" } }, "required": [ "organizationId", "requesterId", "request" ] }, "PermissionsPutRequest_2": { "type": "object", "properties": { "requesterId": { "type": "string" }, "organisationId": { "type": "string" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermission" } }, "forceSet": { "type": "boolean" } }, "required": [ "requesterId", "organisationId", "permissions", "forceSet" ] }, "PutPermissionsRequest": { "type": "object", "properties": { "requesterId": { "type": "string" }, "request": { "$ref": "#/components/schemas/PermissionsPutRequest_2" } }, "required": [ "requesterId", "request" ] }, "PutPermissionsUsersV1": { "type": "object", "properties": { "requesterId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "organizationId": { "type": "string" }, "permissionDtos": { "$ref": "#/components/schemas/UserPermissionV1" } }, "required": [ "requesterId", "organizationId", "permissionDtos" ] }, "OrganizationPermission": { "type": "object", "properties": { "name": { "type": "string", "example": "My Organization" }, "objectId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "role": { "type": "string", "example": "OWNER" }, "roleId": { "type": "string", "example": "org-owner-role-id" } }, "required": [ "name", "objectId", "role", "roleId" ] }, "ProductPermission": { "type": "object", "properties": { "name": { "type": "string", "example": "DMARC Analytics" }, "objectId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "role": { "type": "string", "example": "ADMIN" }, "roleId": { "type": "string", "example": "product-admin-role-id" } }, "required": [ "name", "objectId", "role", "roleId" ] }, "ResourceGroupPermission": { "type": "object", "properties": { "name": { "type": "string", "example": "My Resource Group" }, "objectId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "role": { "type": "string", "example": "VIEWER" }, "roleId": { "type": "string", "example": "resource-group-viewer-role-id" } }, "required": [ "name", "objectId", "role", "roleId" ] }, "ResourcePermission": { "type": "object", "properties": { "name": { "type": "string", "example": "example.com" }, "objectId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "role": { "type": "string", "example": "EDITOR" }, "roleId": { "type": "string", "example": "resource-editor-role-id" }, "resourceGroupId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "resourceGroupName": { "type": "string", "example": "Main Resource Group" } }, "required": [ "name", "objectId", "role", "roleId", "resourceGroupId", "resourceGroupName" ] }, "GetUserPermissionsStructuredResponse": { "type": "object", "properties": { "organization": { "nullable": true, "description": "Organization permission details", "allOf": [ { "$ref": "#/components/schemas/OrganizationPermission" } ] }, "products": { "description": "Array of product permissions", "type": "array", "items": { "$ref": "#/components/schemas/ProductPermission" } }, "resourceGroups": { "description": "Array of resource group permissions", "type": "array", "items": { "$ref": "#/components/schemas/ResourceGroupPermission" } }, "resources": { "description": "Array of resource permissions", "type": "array", "items": { "$ref": "#/components/schemas/ResourcePermission" } } }, "required": [ "products", "resourceGroups", "resources" ] }, "OrganizationOwnerChangeOneTimeCodeRequest": { "type": "object", "properties": { "requesterUserId": { "type": "string", "example": "53422f23-a89a-4d34-acd4-eca3507ec1f7" }, "organization": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" } } } }, "required": [ "requesterUserId", "organization" ] }, "OrganizationChangeOwnerRequest": { "type": "object", "properties": { "organization": { "type": "object", "properties": { "id": { "type": "string" }, "objectId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" } } }, "requesterUserId": { "type": "string", "example": "53422f23-a89a-4d34-acd4-eca3507ec1f7" }, "newOwnerId": { "type": "string", "example": "6f209e39-c9fc-45e6-a4b5-730d5d43daa6" }, "oneTimeCode": { "type": "number", "example": 6425 } }, "required": [ "organization", "requesterUserId", "newOwnerId", "oneTimeCode" ] }, "PreloadPermissionGetRequest": { "type": "object", "properties": { "organizationId": { "type": "string", "example": "org_6e9385ca-199d-49db-a18e" }, "userId": { "type": "string", "example": "d4092e75-11c5-4a61-b948-f87829fe7146" }, "directory": { "allOf": [ { "$ref": "#/components/schemas/PermissionDirectory" } ] }, "objectId": { "type": "string", "example": "e9977f6e-cf9f-456c-9449-5c2162c57658" }, "hideRoles": { "type": "boolean", "example": false }, "query": { "type": "string", "example": "Some query" }, "depth": { "type": "number", "example": 1 } }, "required": [ "organizationId", "userId" ] }, "UserPermissionStructure": { "type": "object", "properties": { "userId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "directory": { "allOf": [ { "$ref": "#/components/schemas/PermissionDirectory" } ] }, "objectId": { "type": "string", "example": "df57ff30-9f8a-4632-9836-ee455da5c8ff" }, "title": { "type": "string", "example": "Some Title" }, "type": { "type": "string", "example": "Some Title" }, "role": { "allOf": [ { "$ref": "#/components/schemas/Permission" } ] }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionStructure" } } }, "required": [ "userId" ] }, "UserBasicInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the user", "format": "uuid", "example": "358ffecc-fd82-493e-862e-2047dcc450d4" }, "username": { "type": "string", "description": "Username for the user account, typically the email address or a unique identifier", "example": "jillian_price@example.net" }, "firstName": { "type": "string", "description": "First name of the user. May be \"No name\" if not set.", "example": "Jillian" }, "lastName": { "type": "string", "description": "Last name of the user. May be \"No name\" if not set.", "example": "Price" }, "email": { "type": "string", "description": "Email address of the user", "format": "email", "example": "jillian_price@example.net" }, "emailVerified": { "type": "boolean", "description": "Indicates whether the user's email address has been verified", "example": true }, "avatar": { "description": "Avatar image information for the user. May contain URL or image data.", "allOf": [ { "$ref": "#/components/schemas/UserAvatar" } ] }, "avatarColor": { "description": "Color scheme for the user's avatar when no image is set. Used for generating colored initials.", "allOf": [ { "$ref": "#/components/schemas/UserAvatarColor" } ] } }, "required": [ "id", "username", "firstName", "lastName", "email", "emailVerified" ] }, "UserPersonalInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "username": { "type": "string", "description": "username" }, "firstName": { "type": "string", "description": "First Name" }, "lastName": { "type": "string", "description": "Last Name" }, "email": { "type": "string", "description": "Email" }, "emailVerified": { "type": "boolean", "description": "Email Verified" }, "avatar": { "description": "User Avatar", "allOf": [ { "$ref": "#/components/schemas/UserAvatar" } ] }, "avatarColor": { "description": "User Avatar Color", "allOf": [ { "$ref": "#/components/schemas/UserAvatarColor" } ] }, "terminationRequestSent": { "format": "date-time", "type": "string", "description": "Termination Request Sent" }, "organisationProfile": { "description": "Organisation Profile", "allOf": [ { "$ref": "#/components/schemas/UserOrganisationProfileData" } ] } }, "required": [ "id", "username", "firstName", "lastName", "email", "emailVerified" ] }, "UserSessionDevice": { "type": "object", "properties": { "sessionId": { "type": "string" }, "loginUsername": { "type": "string" }, "userId": { "type": "string" }, "ipAddress": { "type": "string" }, "os": { "type": "string" }, "osVersion": { "type": "string" }, "browser": { "type": "string" }, "device": { "type": "string" }, "mobile": { "type": "string" } }, "required": [ "sessionId", "loginUsername", "userId", "ipAddress", "os", "osVersion", "browser", "device", "mobile" ] }, "Attribute_2": { "type": "object", "properties": {} }, "SingleAttributeResponse": { "type": "object", "properties": {} }, "Page": { "type": "object", "properties": { "index": { "type": "number" }, "size": { "type": "number" } }, "required": [ "index", "size" ] }, "Organization": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "format": "date-time", "type": "string" } }, "required": [ "id", "name", "createdAt" ] }, "PageResponseUserOrganization": { "type": "object", "properties": { "totalCount": { "type": "number", "example": 10 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } } }, "required": [ "totalCount", "items" ] }, "PermissionRole": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] }, "PermissionOrganisation": { "type": "object", "properties": { "id": { "type": "string", "example": "org_00000000000000000000000c" }, "role": { "$ref": "#/components/schemas/PermissionRole" } }, "required": [ "id", "role" ] }, "UpdateOrganizationName": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "UserOrganizationDomainRequest": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" } }, "required": [ "domain" ] }, "ScimSecretResponse": { "type": "object", "properties": { "secret": { "type": "string", "description": "SCIM secret for the organization", "example": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456" } }, "required": [ "secret" ] }, "KeycloakUpdateEmailEvent": { "type": "object", "properties": {} }, "IamSso": { "type": "object", "properties": { "addReadTokenRoleOnCreate": { "type": "boolean" }, "alias": { "type": "string" }, "config": { "type": "object" }, "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "firstBrokerLoginFlowAlias": { "type": "string" }, "internalId": { "type": "string" }, "linkOnly": { "type": "boolean" }, "postBrokerLoginFlowAlias": { "type": "string" }, "providerId": { "type": "string" }, "storeToken": { "type": "boolean" }, "trustEmail": { "type": "boolean" }, "idpEntityId": { "type": "string" }, "singleSignOnServiceUrl": { "type": "string" } }, "required": [ "addReadTokenRoleOnCreate", "alias", "config", "displayName", "enabled", "firstBrokerLoginFlowAlias", "internalId", "linkOnly", "postBrokerLoginFlowAlias", "providerId", "storeToken", "trustEmail", "idpEntityId", "singleSignOnServiceUrl" ] }, "SsoSp": { "type": "object", "properties": { "entityId": { "type": "string" }, "acsUrl": { "type": "string" }, "idpUrl": { "type": "string" } }, "required": [ "entityId", "acsUrl", "idpUrl" ] }, "Sso": { "type": "object", "properties": { "idp": { "$ref": "#/components/schemas/IamSso" }, "sp": { "$ref": "#/components/schemas/SsoSp" }, "createdAt": { "format": "date-time", "type": "string" }, "ssoForce": { "type": "object" }, "providerName": { "type": "object" } }, "required": [ "idp", "sp", "createdAt", "ssoForce", "providerName" ] }, "UserOrganizationDomainResponse": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "isVerified": { "type": "boolean", "example": true }, "token": { "type": "string", "example": "token" } }, "required": [ "domain", "isVerified", "token" ] }, "SsoInfo": { "type": "object", "properties": { "hasSsoSetupAccess": { "type": "boolean" }, "isSsoSetup": { "type": "boolean" }, "domainInfo": { "$ref": "#/components/schemas/UserOrganizationDomainResponse" } }, "required": [ "hasSsoSetupAccess", "isSsoSetup", "domainInfo" ] }, "PublicInviteUsersV1": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The unique identifier of the organization to which users are being invited", "format": "uuid", "example": "8a7b9c2d-1e3f-4a5b-9c8d-7e6f5a4b3c2d" }, "permissions": { "description": "Permission configuration including user list and role assignments", "allOf": [ { "$ref": "#/components/schemas/UserPermissionV1" } ] }, "redirectUrl": { "type": "string", "description": "URL to redirect users to after they accept the invitation and complete onboarding. Must be a valid HTTPS URL.", "format": "uri", "example": "https://app.easydmarc.com" } }, "required": [ "organizationId", "permissions" ] }, "CreateUsers": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The unique identifier of the organization in which to create the users", "format": "uuid", "example": "8a7b9c2d-1e3f-4a5b-9c8d-7e6f5a4b3c2d" }, "permissions": { "description": "Permission configuration including user details and role assignments", "allOf": [ { "$ref": "#/components/schemas/UserPermissionV1" } ] } }, "required": [ "organizationId", "permissions" ] }, "CreateUsersResponse": { "type": "object", "properties": { "users": { "type": "object", "description": "Map of user email addresses to their newly created user IDs", "example": { "john.doe@example.com": "4fd475a0-e60a-43a0-82ff-6d9532cc3e9b", "jane.smith@example.com": "7c8d9e0f-2a3b-4c5d-8e9f-0a1b2c3d4e5f" } } }, "required": [ "users" ] }, "PublicRevokeOrganizationAccessRequest": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "The unique identifier of the organization from which to revoke user access", "format": "uuid", "example": "8a7b9c2d-1e3f-4a5b-9c8d-7e6f5a4b3c2d" }, "userIds": { "description": "Array of user IDs whose access should be revoked. All users must be members of the specified organization.", "example": [ "4fd475a0-e60a-43a0-82ff-6d9532cc3e9b", "7c8d9e0f-2a3b-4c5d-8e9f-0a1b2c3d4e5f" ], "type": "array", "items": { "type": "string" } } }, "required": [ "organizationId", "userIds" ] } } }, "x-tagGroups": [ { "name": "API", "tags": [ "Authentication", "Domains", "Alerting", "DNS Lookup", "Aggregate Reports", "Failure Reports" ] }, { "name": "Partner API", "tags": [ "Organizations", "Billing - Subscriptions & Pricing", "Users" ] }, { "name": "Other", "tags": [ "DnsCore" ] } ] }