{ "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": "Audit Log", "x-displayName": "Audit Log" }, { "name": "DNS Intelligence", "x-displayName": "DNS Intelligence" }, { "name": "Failure Reports", "x-displayName": "Failure Reports" }, { "name": "Organizations", "x-displayName": "Organizations" }, { "name": "Billing - Subscriptions & Pricing", "x-displayName": "Billing - Subscriptions & Pricing" }, { "name": "Billing - Billing Information", "x-displayName": "Billing - Billing Information" }, { "name": "Billing - Invoices", "x-displayName": "Billing - Invoices" }, { "name": "Billing - Payment Methods", "x-displayName": "Billing - Payment Methods" }, { "name": "Users", "x-displayName": "Users" } ], "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": { "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.", "operationId": "createMagicLink", "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" } }, "security": [ { "bearer": [] } ], "summary": "Generate login magic link", "tags": [ "Authentication" ] } }, "/auth/token": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Authenticates your client credentials and returns a bearer token required for accessing protected API endpoints.\n\n", "operationId": "getAuthToken", "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" } }, "summary": "Obtain authentication token", "tags": [ "Authentication" ] } }, "/v1/organizations": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Creates a new organization within the partner tenant with the specified name.", "operationId": "createOrganization", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Create a new organization", "tags": [ "Organizations" ] }, "get": { "description": "Retrieves a paginated list of organizations within the partner tenant. Use page and limit parameters to control pagination.", "operationId": "getOrganizations", "parameters": [ { "name": "order", "required": false, "in": "query", "schema": { "$ref": "#/components/schemas/OrderEnum_2" } }, { "name": "page", "required": false, "in": "query", "description": "Page number for pagination", "schema": { "minimum": 1, "default": 1, "example": 1, "type": "number" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 10, "example": 20, "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "List organizations", "tags": [ "Organizations" ] } }, "/v1/organizations/{organizationId}": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "patch": { "description": "Updates the organization with the specified fields. Only provided fields will be updated.", "operationId": "patchOrganization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Unique identifier of the organization", "schema": { "example": "org_68231dcfeb8e9f092a052b88", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Partially update existing organization", "tags": [ "Organizations" ] }, "get": { "description": "Retrieves the organization details by the specified ID.", "operationId": "getOrganizationById", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Unique identifier of the organization", "schema": { "example": "org_68231dcfeb8e9f092a052b88", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Get organization details", "tags": [ "Organizations" ] }, "delete": { "description": "Deletes the organization by the specified ID. This action is irreversible.", "operationId": "deleteOrganization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "Unique identifier of the organization to delete", "schema": { "example": "org_68231dcfeb8e9f092a052b88", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Delete an organization", "tags": [ "Organizations" ] } }, "/v1/partners/plans": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "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.", "operationId": "listPlans", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "List plans", "tags": [ "Billing - Subscriptions & Pricing" ] } }, "/v1/partners/subscriptions": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "Retrieves all subscriptions for a given organization, including expired and cancelled subscriptions.", "operationId": "listSubscriptions", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "maxLength": 128, "example": "org_88xy77", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "List subscriptions for an organization", "tags": [ "Billing - Subscriptions & Pricing" ] } }, "/v1/partners/subscriptions/{subscriptionId}/cancel": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Cancels a subscription immediately. Cannot be applied to an already cancelled subscription.", "operationId": "cancelSubscription", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "description": "Subscription ID", "schema": { "example": "sub_12ab34", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Cancel a subscription", "tags": [ "Billing - Subscriptions & Pricing" ] } }, "/v1/partners/subscriptions/{subscriptionId}/renew": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Updates the expiration date of an active subscription based on the assigned price billing period. Cannot be applied to a cancelled subscription.", "operationId": "renewSubscription", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "description": "Subscription ID", "schema": { "example": "sub_12ab34", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Renew the subscription", "tags": [ "Billing - Subscriptions & Pricing" ] } }, "/v1/partners/subscriptions/{subscriptionId}/auto-renew": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "patch": { "description": "Toggles automatic renewal for a subscription. When enabled, a scheduled job extends the expiration date based on the assigned price billing period once the term ends. Cannot be applied to a cancelled subscription.", "operationId": "updateSubscriptionAutoRenew", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "description": "Subscription ID", "schema": { "example": "sub_12ab34", "type": "string" } } ], "requestBody": { "required": true, "description": "Automatic renewal setting", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionAutoRenewRequest" } } } }, "responses": { "200": { "description": "Automatic renewal setting updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionV2" } } } }, "400": { "description": "Invalid request" }, "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Enable or disable automatic renewal", "tags": [ "Billing - Subscriptions & Pricing" ] } }, "/v1/partners/subscriptions/assign": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "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.", "operationId": "assignSubscription", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Assign a subscription (partner-admin flow)", "tags": [ "Billing - Subscriptions & Pricing" ] } }, "/v1/partners/subscriptions/{subscriptionId}": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "description": "Creates a new subscription with a new Plan/Price. The current active subscription is cancelled and replaced with the new one.", "operationId": "updateSubscriptionPrice", "parameters": [ { "name": "subscriptionId", "required": true, "in": "path", "description": "Subscription ID", "schema": { "example": "sub_12ab34", "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" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Upgrade/downgrade plan", "tags": [ "Billing - Subscriptions & Pricing" ] } }, "/v1/partners/payment-sources": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "Retrieves all payment methods (credit cards, PayPal) for a given organization.", "operationId": "listPaymentSources", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of payment sources" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "List payment sources for an organization", "tags": [ "Billing - Payment Methods" ] }, "post": { "description": "Adds a new payment method (credit card or PayPal) for an organization.", "operationId": "addPaymentSource", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSourceCreateRequest" } } } }, "responses": { "201": { "description": "Payment source added successfully" }, "400": { "description": "Invalid request - missing token or intent" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Add a payment source", "tags": [ "Billing - Payment Methods" ] } }, "/v1/partners/payment-sources/{paymentMethodId}": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "delete": { "description": "Removes a payment method from an organization.", "operationId": "removePaymentSource", "parameters": [ { "name": "paymentMethodId", "required": true, "in": "path", "description": "Payment method ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment source removed successfully" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" }, "404": { "description": "Payment source not found" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Remove a payment source", "tags": [ "Billing - Payment Methods" ] } }, "/v1/partners/invoices": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "Retrieves all invoices for a given organization.", "operationId": "listInvoices", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of invoices to return", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of invoices" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "List invoices for an organization", "tags": [ "Billing - Invoices" ] } }, "/v1/partners/invoices/{invoiceId}": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "Retrieves a specific invoice by ID.", "operationId": "getInvoice", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "description": "Invoice ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice details" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" }, "404": { "description": "Invoice not found" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Get invoice details", "tags": [ "Billing - Invoices" ] } }, "/v1/partners/invoices/{invoiceId}/pdf": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "Returns a URL to download the invoice as PDF.", "operationId": "getInvoicePdfUrl", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "description": "Invoice ID", "schema": { "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice PDF URL", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" }, "404": { "description": "Invoice not found" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Get invoice PDF URL", "tags": [ "Billing - Invoices" ] } }, "/v1/partners/billing/info": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "Retrieves billing address and payment details for a given organization.", "operationId": "get_getBillingInfo", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Billing information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInfo" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Get billing information for an organization", "tags": [ "Billing - Billing Information" ] }, "post": { "description": "Creates or updates billing address and payment details for an organization.", "operationId": "upsertBillingInfo", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "External organization ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Billing information updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInfo" } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "403": { "description": "Forbidden - Organization does not belong to the partner" } }, "security": [ { "oauth2": [] }, { "bearer": [] } ], "summary": "Create or update billing information", "tags": [ "Billing - Billing Information" ] } }, "/v1/audit-log": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "\n Query audit logs with comprehensive filtering options.\n\n **Filtering by user:** Use 'userIds' parameter with comma-separated user IDs or 'userEmails' parameter with comma-separated user emails.\n\n **Filtering by domain:** Use 'domainIds' parameter with comma-separated domain IDs.\n\n **Filtering by domain group:** Use 'domainGroupIds' parameter with comma-separated domain group IDs.\n\n **Filtering by action category:** Use 'actionCategories' parameter with one or more of:\n - DOMAINS: Domain-related actions\n - DOMAIN_GROUPS: Domain group actions\n - MANAGED_SERVICES: Managed DMARC, BIMI, MTA-STS, EasySPF actions\n - USER_MANAGEMENT: User invitation, revocation, permission changes\n - BILLING: Billing details, plan upgrades, cancellations\n - SECURITY_FEATURES: MFA setup/removal\n - ORGANIZATION_SECURITY: SSO setup, account termination\n - LOGIN_AND_LOGOUT: Login, logout, device actions\n - INTEGRATIONS: Integration connections, token generation\n - ALERTING: Alert creation, modification, deletion\n - RUF: Failure report actions\n - RUA: Aggregate report actions\n - PERSONAL_SETTINGS: Name changes\n - REPORTING: Scheduled report actions, whitelabel, SMTP setup\n - LABEL_MANAGEMENT: Label creation, modification, deletion\n\n **Filtering by specific actions:** Use 'actions' parameter with specific AuditLogAction values.\n\n **Date range:** Use 'startDate' and 'endDate' parameters (ISO 8601 format).\n ", "operationId": "getAuditLogs", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "Organization ID to query audit logs for", "schema": { "type": "string" } }, { "name": "userIds", "required": false, "in": "query", "description": "Filter by user IDs", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "userEmails", "required": false, "in": "query", "description": "Filter by user emails", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "domainIds", "required": false, "in": "query", "description": "Filter by domain IDs", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "domainGroupIds", "required": false, "in": "query", "description": "Filter by domain group IDs", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "actions", "required": false, "in": "query", "description": "Filter by specific actions", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogAction_2" } } }, { "name": "actionCategories", "required": false, "in": "query", "description": "Filter by action categories (DOMAINS, DOMAIN_GROUPS, MANAGED_SERVICES, USER_MANAGEMENT, BILLING, SECURITY_FEATURES, ORGANIZATION_SECURITY, LOGIN_AND_LOGOUT, INTEGRATIONS, ALERTING, RUF, RUA, PERSONAL_SETTINGS, REPORTING, LABEL_MANAGEMENT)", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogActionCategory" } } }, { "name": "entityTypes", "required": false, "in": "query", "description": "Filter by entity types", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityType_2" } } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date for the date range filter", "schema": { "format": "date-time", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date for the date range filter", "schema": { "format": "date-time", "type": "string" } }, { "name": "sortDirection", "required": false, "in": "query", "description": "Sort direction for results", "schema": { "$ref": "#/components/schemas/SortDirection_2" } }, { "name": "page", "required": false, "in": "query", "description": "Page number (1-indexed)", "schema": { "default": 1, "type": "number" } }, { "name": "pageSize", "required": false, "in": "query", "description": "Number of items per page", "schema": { "default": 20, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Free-text search across user name/email, entity labels, and old/new value labels (case-insensitive).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully returned audit logs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogPageResponse_2" } } } }, "400": { "description": "Request is invalid." }, "401": { "description": "Request authentication is required." }, "403": { "description": "Request is not authorized." } }, "security": [ { "oauth2": [] } ], "summary": "Get audit logs with filters", "tags": [ "Audit Log" ] } }, "/v1/audit-log/export": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "description": "\n Export audit logs with the same filtering options as the query endpoint.\n Returns audit logs as a CSV file.\n ", "operationId": "exportAuditLogs", "parameters": [ { "name": "organizationId", "required": true, "in": "query", "description": "Organization ID to export audit logs for", "schema": { "type": "string" } }, { "name": "userIds", "required": false, "in": "query", "description": "Filter by user IDs", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "userEmails", "required": false, "in": "query", "description": "Filter by user emails", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "domainIds", "required": false, "in": "query", "description": "Filter by domain IDs", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "domainGroupIds", "required": false, "in": "query", "description": "Filter by domain group IDs", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "actions", "required": false, "in": "query", "description": "Filter by specific actions", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogAction_2" } } }, { "name": "actionCategories", "required": false, "in": "query", "description": "Filter by action categories", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogActionCategory" } } }, { "name": "entityTypes", "required": false, "in": "query", "description": "Filter by entity types", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityType_2" } } }, { "name": "startDate", "required": false, "in": "query", "description": "Start date for the date range filter", "schema": { "format": "date-time", "type": "string" } }, { "name": "endDate", "required": false, "in": "query", "description": "End date for the date range filter", "schema": { "format": "date-time", "type": "string" } }, { "name": "sortDirection", "required": false, "in": "query", "description": "Sort direction for results", "schema": { "$ref": "#/components/schemas/SortDirection_2" } }, { "name": "search", "required": false, "in": "query", "description": "Free-text search across user name/email, entity labels, and old/new value labels (case-insensitive).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully exported audit logs. Returns CSV content as text." }, "400": { "description": "Request is invalid." }, "401": { "description": "Request authentication is required." }, "403": { "description": "Request is not authorized." } }, "security": [ { "oauth2": [] } ], "summary": "Export audit logs to CSV", "tags": [ "Audit Log" ] } }, "/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/dmarc/verification-status-batch": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "getVerificationStatusBatch", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DmarcRuxBatchRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DomainVerificationStatusResponse" } } } } } }, "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/dns-intelligence/checks": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "get": { "operationId": "listDnsIntelligenceChecks", "summary": "List available DNS Intelligence checks", "description": "Returns the camelCase identifiers of every check the worker registry advertises. Use one of these as `check` in `POST /dns-intelligence/run`.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } } }, "tags": [ "DNS Intelligence" ], "security": [ { "bearer": [] } ] } }, "/v1/dns-lookup/dns-intelligence/run": { "servers": [ { "url": "https://api2.easydmarc.com" } ], "post": { "operationId": "runDnsIntelligenceCheck", "summary": "Run a DNS Intelligence check against a domain", "description": "Issues a NATS request to the dns-intelligence worker and returns the typed reply. Verdicts are returned as data; only transport, worker, and protocol failures map to non-2xx.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCheckRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCheckResponse" } } } }, "400": { "description": "Unknown check or worker rejected the request shape." }, "422": { "description": "Worker reported INVALID_INPUT." }, "502": { "description": "Worker INTERNAL or protocol decode failure." }, "503": { "description": "NATS unreachable or no worker subscribed." }, "504": { "description": "Request or worker deadline exceeded." } }, "tags": [ "DNS Intelligence" ], "security": [ { "bearer": [] } ] } }, "/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" }, "oauth2": { "type": "oauth2", "flows": { "implicit": { "authorizationUrl": "https://uac.easydmarc.dev/realms/easydmarc/protocol/openid-connect/auth", "scopes": { "openid": "openid", "profile": "profile", "email": "email", "offline_access": "offline_access" } } }, "scheme": "bearer" } }, "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" } } } } } } }, "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" } } } } } } }, "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" } } } } } } } }, "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" ] }, "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, "allOf": [ { "$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" ] }, "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" ] }, "OrderEnum_2": { "type": "string", "enum": [ "ASC", "DESC" ] }, "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" }, "partnerId": { "type": "string", "description": "Partner object ID to link to this organization", "example": "partner_abc123" } }, "required": [ "name" ] }, "PaymentSourceCreateRequest": { "type": "object", "properties": {} }, "PlanFeatures_2": { "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 }, "email_investigation_report_count": { "type": "number", "description": "Number of email investigations allowed" }, "custom_dashboards": { "type": "boolean", "description": "Whether custom dashboards feature is enabled" }, "reputation_intelligence_integrations": { "type": "boolean", "description": "Whether reputation intelligence integrations feature is enabled" }, "email_preview_suite": { "type": "boolean", "description": "Whether email preview suite feature is enabled" }, "alert_management": { "type": "boolean", "description": "Whether alert management feature is enabled" }, "sso": { "type": "boolean", "description": "Whether SSO (Single Sign-On) feature is enabled" }, "sendgrid_integration": { "type": "boolean", "description": "Whether SendGrid integration is enabled" }, "mailgun_integration": { "type": "boolean", "description": "Whether Mailgun integration is enabled" }, "esp_integrations": { "type": "boolean", "description": "Whether ESP integrations (Amazon SES, SendGrid, Mailgun) are enabled" } } }, "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" }, "espIntegrations": { "type": "boolean", "description": "Whether ESP integrations (Amazon SES, SendGrid, Mailgun) are enabled" } } }, "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_2" } ] }, "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 }, "autoRenew": { "type": "boolean", "description": "Whether the subscription renews automatically when its term ends. When true, a scheduled job extends the expiration date based on the assigned price billing period.", "example": true, "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" ] }, "UpdateSubscriptionAutoRenewRequest": { "type": "object", "properties": { "autoRenew": { "type": "boolean", "description": "Whether the subscription should be renewed automatically when its term ends. When true, a scheduled job extends the expiration date based on the assigned price billing period.", "example": true } }, "required": [ "autoRenew" ] }, "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" }, "autoRenew": { "type": "boolean", "description": "Whether the subscription should be renewed automatically when its term ends. When true, a scheduled job extends the expiration date based on the assigned price billing period. Defaults to true.", "example": true, "default": true } }, "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" ] }, "UserRole_2": { "type": "string", "enum": [ "Organization Owner", "Organization Admin", "Product Admin", "Product Editor", "Domain Group Admin", "Domain Group Editor", "Domain Admin", "Domain Editor", "Domain Group Viewer", "Domain Viewer" ] }, "ActionPerformerResponse_2": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "fullName": { "type": "string" }, "role": { "allOf": [ { "$ref": "#/components/schemas/UserRole_2" } ] }, "avatar": { "type": "string" }, "avatarColor": { "type": "string" } }, "required": [ "id", "email", "fullName", "role" ] }, "CountryResponse_2": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "flagUrl": { "type": "string" } }, "required": [ "name", "code" ] }, "AuditLogAction_2": { "type": "string", "enum": [ "UNKNOWN", "DOMAIN_ADDED", "DOMAIN_REMOVED", "DOMAIN_MOVED_TO_GROUP", "GROUP_MOVE_TO_WORKSPACE", "DOMAIN_GROUP_ADDED", "DOMAIN_GROUP_REMOVED", "DOMAIN_GROUP_NAME_EDITED", "MANAGED_DMARC_ACTIVATED", "MANAGED_DMARC_RECORD_CHANGED", "FAILURE_REPORT_DISABLED", "FAILURE_REPORT_ENABLED", "MANAGED_BIMI_ACTIVATED", "MANAGED_BIMI_RECORD_CHANGED", "MANAGED_MTA_STS_ACTIVATED", "MANAGED_MTA_STS_RECORD_CHANGED", "EASY_SPF_SOURCE_ADDED", "EASY_SPF_SOURCE_REMOVED", "EASY_SPF_SOURCE_NAME_UPDATED", "EASY_SPF_PART_TYPE_UPDATED", "EASY_SPF_PART_VALUE_UPDATED", "EASY_SPF_SOURCE_ENABLED", "EASY_SPF_SOURCE_DISABLED", "EASY_SPF_ACTIVATED", "USER_INVITED_AS_ADMIN", "USER_INVITED_AS_EDITOR", "USER_INVITED_AS_VIEWER", "USER_REVOKED_FROM_ORGANIZATION", "USER_PERMISSION_CHANGED", "BILLING_DETAILS_ADDED", "PRODUCT_PLAN_UPGRADED", "BILLING_CANCELLATION_REQUESTED", "INTEGRATION_TOKEN_GENERATED", "INTEGRATION_CONNECTED", "INTEGRATION_DISCONNECTED", "LOGGED_IN", "LOGGED_OUT", "LOGGED_IN_ERROR", "ADDED_MFA", "REMOVED_MFA", "SETUP_SSO", "LOGGED_IN_SSO", "REGISTERED_SSO", "CHANGED_FULL_NAME", "CHANGED_LAST_NAME", "CHANGED_FIRST_NAME", "REQUESTED_ACCOUNT_TERMINATION", "LOGGED_IN_NEW_DEVICE", "LOGGED_OUT_DEVICE", "LOGGED_OUT_FROM_ALL_DEVICES", "DISCONNECTED_SOCIAL_ACCOUNT", "LEFT_ORGANIZATION", "AGGREGATE_REPORT_FILE_UPLOADED", "TLS_REPORT_FILE_UPLOADED", "DOMAIN_OR_IP_REPUTATION_MONITORING_ADDED", "DOMAIN_OR_IP_REPUTATION_MONITORING_REMOVED", "CREATED_ALERT", "EDITED_ALERT_NAME", "ADDED_RECIPIENTS_FOR_ALERT", "REMOVED_RECIPIENTS_FOR_ALERT", "ADDED_DOMAINS_FOR_ALERT", "REMOVED_DOMAINS_FOR_ALERT", "DELETED_ALERT", "ENABLED_ALERT", "DISABLED_ALERT", "DELETED_ALERT_LOG", "MARKED_ALERT_LOG_RESOLVED", "APPLIED_LABEL", "REMOVED_LABEL", "CREATED_LABEL", "EDITED_LABEL_NAME", "DELETED_LABEL", "CREATED_SCHEDULED_REPORT", "ADDED_ENTITY_FOR_SCHEDULED_REPORT", "REMOVED_ENTITY_FOR_SCHEDULED_REPORT", "DELETED_SCHEDULED_REPORT", "EDITED_TIMEZONE_FOR_SCHEDULED_REPORT", "EDITED_FREQUENCY_FOR_SCHEDULED_REPORT", "FEDERATED_IDENTITY_LINK", "ENABLED_WHITELABEL_SETTINGS_FOR_REPORTING", "DISABLED_WHITELABEL_SETTINGS_FOR_REPORTING", "CREATED_SMTP_SETUP_FOR_REPORTING", "EDITED_SMTP_SETUP_FOR_REPORTING", "DELETED_SMTP_SETUP_FOR_REPORTING", "RENEWED_SUBSCRIPTION" ] }, "EntityType_2": { "type": "string", "enum": [ "domain", "domain_group", "workspace", "partner", "organization", "vendor", "sso", "login", "user", "link", "product", "role", "plan", "record", "source_name", "source_type", "source_value", "logout", "text", "social", "device", "ip", "email", "slack", "ms_teams", "alert_name", "label_name", "timezone", "frequency", "dns_record", "dns_domain" ] }, "ActionItemResponse_2": { "type": "object", "properties": { "label": { "type": "string" }, "entityType": { "allOf": [ { "$ref": "#/components/schemas/EntityType_2" } ] }, "id": { "type": "string" }, "imgPath": { "type": "string" } }, "required": [ "label", "entityType" ] }, "SortDirection_2": { "type": "string", "enum": [ "ASC", "DESC" ] }, "AuditLogOs_2": { "type": "string", "enum": [ "MAC", "WINDOWS", "LINUX", "OTHER" ] }, "AuditLogBrowser_2": { "type": "string", "enum": [ "CHROME", "SAFARI", "OPERA", "FIREFOX", "OTHER" ] }, "AuditLogDevice_2": { "type": "string", "enum": [ "PC", "PHONE", "OTHER" ] }, "PlatformResponse_2": { "type": "object", "properties": { "os": { "allOf": [ { "$ref": "#/components/schemas/AuditLogOs_2" } ] }, "browser": { "allOf": [ { "$ref": "#/components/schemas/AuditLogBrowser_2" } ] }, "device": { "allOf": [ { "$ref": "#/components/schemas/AuditLogDevice_2" } ] } }, "required": [ "os", "browser", "device" ] }, "AuditLogResponse_2": { "type": "object", "properties": { "id": { "type": "string" }, "user": { "$ref": "#/components/schemas/ActionPerformerResponse_2" }, "date": { "format": "date-time", "type": "string" }, "actionDate": { "format": "date-time", "type": "string" }, "action": { "allOf": [ { "$ref": "#/components/schemas/AuditLogAction_2" } ] }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/ActionItemResponse_2" } }, "entity": { "type": "array", "items": { "$ref": "#/components/schemas/ActionItemResponse_2" } }, "country": { "$ref": "#/components/schemas/CountryResponse_2" }, "ip": { "type": "string" }, "platform": { "$ref": "#/components/schemas/PlatformResponse_2" }, "os": { "type": "string" }, "browser": { "type": "string" }, "device": { "type": "string" }, "onData": { "type": "array", "items": { "$ref": "#/components/schemas/ActionItemResponse_2" } }, "from": { "$ref": "#/components/schemas/ActionItemResponse_2" }, "to": { "$ref": "#/components/schemas/ActionItemResponse_2" } }, "required": [ "id", "user", "date", "actionDate", "action", "entities", "entity", "country", "ip", "platform", "os", "browser", "device" ] }, "AuditLogPageResponse_2": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogResponse_2" } }, "totalCount": { "type": "number", "description": "Total number of records matching the query" }, "currentPage": { "type": "number", "description": "Current page number (1-based)" }, "totalPages": { "type": "number", "description": "Total number of pages" } }, "required": [ "data", "totalCount", "currentPage", "totalPages" ] }, "AuditLogActionCategory": { "type": "string", "enum": [ "DOMAINS", "DOMAIN_GROUPS", "MANAGED_SERVICES", "USER_MANAGEMENT", "BILLING", "SECURITY_FEATURES", "ORGANIZATION_SECURITY", "LOGIN_AND_LOGOUT", "INTEGRATIONS", "ALERTING", "RUF", "RUA", "PERSONAL_SETTINGS", "REPORTING", "LABEL_MANAGEMENT" ] }, "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_NONE", "WARNING_NON_EXIST_SUBDOMAIN_POLICY_NONE", "WARNING_RUA_TAG", "WARNING_RUA_TAG_GUEST", "WARNING_PCT", "INFO_POLICY_QUARANTINE", "INFO_SUBDOMAIN_POLICY_QUARANTINE", "INFO_NON_EXIST_SUBDOMAIN_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" ] }, "DmarcRuxBatchRequest": { "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" } }, "rux": { "type": "number", "example": "rua", "enum": [ 5, 6 ] } }, "required": [ "domains", "rux" ] }, "DomainVerificationStatusResponse": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" }, "hasRux": { "type": "boolean", "example": true } }, "required": [ "domain", "hasRux" ] }, "DkimTermEnum": { "type": "string", "enum": [ "v", "g", "h", "k", "n", "p", "s", "t" ] }, "DkimRecordTerm": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/DkimTermEnum" }, "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_REDIRECT_TERM", "DUPLICATE_REDIRECT_TERM", "DUPLICATE_MECHANISM", "PTR_USED", "UNKNOWN_MECHANISM", "TERM_MUST_BE_DOMAIN", "INVALID_IP_ADDRESS", "INVALID_EXP_MECHANISM", "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", "DNS_LOOKUP_LIMIT", "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" }, "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" }, "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", "avp", "lps", "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_INVALID_AVP_TAG", "ERROR_INVALID_LPS_TAG", "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" }, "avp": { "type": "string", "enum": [ "personal", "brand" ], "example": "brand", "description": "Avatar Preference tag value." }, "lps": { "type": "string", "example": "sales-,support-", "description": "Local-Part Selector tag value." } }, "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" ] }, "RunCheckRequest": { "type": "object", "properties": { "check": { "type": "string", "description": "Camel-case check name from the dns-intelligence-client-sdk catalogue (e.g. caaMissing, dnssecChain, ttlOutOfRange).", "example": "caaMissing" }, "domain": { "type": "string", "example": "easydmarc.com" }, "params": { "type": "object", "description": "Per-check parameters object. Shape depends on `check`; pass `{}` when the check needs no input.", "example": {} }, "region": { "type": "string", "description": "Worker region tag. Absent ⇒ global routing (the default for nearly every call).", "example": "eu-west-1" }, "timeoutMs": { "type": "number", "description": "Per-call timeout in ms. Wins over the service default (10s).", "example": 5000 }, "tenantId": { "type": "string", "description": "Tenant identifier propagated to the worker as `tenant_id`." }, "traceparent": { "type": "string", "description": "W3C `traceparent` header pass-through." }, "tracestate": { "type": "string", "description": "W3C `tracestate` header pass-through." }, "requestId": { "type": "string", "description": "Optional client-supplied request id. Auto-generated UUID v4 when absent." }, "correlationId": { "type": "string", "description": "Payload-level correlation id, distinct from the `request_id` header." }, "idempotencyKey": { "type": "string", "description": "Header `idempotency_key`. Pass a stable value to dedupe retries upstream." } }, "required": [ "check", "domain" ] }, "RunCheckResponse": { "type": "object", "properties": { "verdict": { "type": "number", "enum": [ 0, 1, 2, 3, 4 ], "description": "PASS / WARN / FAIL / INCONCLUSIVE / UNSPECIFIED. Returned as data — never thrown." }, "checkName": { "type": "string", "description": "Wire-format check name (snake_case)." }, "checkLogicVersion": { "type": "string" }, "queriedAt": { "type": "string", "format": "date-time" }, "region": { "type": "string" }, "elapsedMs": { "type": "number", "description": "Worker-reported elapsed milliseconds." }, "reasonCodes": { "type": "array", "items": { "type": "string" } }, "notes": { "description": "Worker notes.", "type": "array", "items": { "type": "object" } }, "correlationId": { "type": "string" }, "evidence": { "type": "object", "description": "Structured evidence — shape varies by check. Refer to the proto Evidence oneof for the variant matching `check`." } }, "required": [ "verdict", "checkName", "checkLogicVersion", "region", "elapsedMs", "reasonCodes", "notes", "correlationId" ] }, "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_3": { "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_3" } ] }, "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_3" } ] }, "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_3" } ] }, "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" ] }, "DomainWithReportTypes": { "type": "object", "properties": { "domainName": { "type": "string", "description": "Fully qualified domain name", "example": "example.com" }, "reportTypes": { "type": "array", "description": "Array of report types for this domain", "items": { "type": "string", "enum": [ "dmarc-capable", "non-compliant", "threat-unknown", "forwarded" ] } } }, "required": [ "domainName", "reportTypes" ] }, "VolumeRequest": { "type": "object", "properties": { "domainsWithReportTypes": { "description": "Array of domains with their report types", "type": "array", "items": { "$ref": "#/components/schemas/DomainWithReportTypes" } }, "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange_3" } ] }, "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": [ "domainsWithReportTypes", "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": { "domainsWithReportTypes": { "description": "Array of domains with their report types", "type": "array", "items": { "$ref": "#/components/schemas/DomainWithReportTypes" } }, "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange_3" } ] }, "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": [ "domainsWithReportTypes", "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": { "domainsWithReportTypes": { "description": "Array of domains with their report types", "type": "array", "items": { "$ref": "#/components/schemas/DomainWithReportTypes" } }, "dateRange": { "description": "Date range filter", "allOf": [ { "$ref": "#/components/schemas/DateRange_3" } ] }, "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": [ "domainsWithReportTypes", "dateRange", "filters" ] }, "UserAvatar_5": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to the user's avatar image", "format": "uri" } } }, "UserAvatarColorRgb_4": { "type": "string", "enum": [ "#DA6969", "#FFC04D", "#FFB185", "#75CAA9", "#90E4EA", "#5C85FF", "#8DC0FF", "#FDA1E3", "#A57AF2", "#B2A9D0", "#ABB0CB" ] }, "UserAvatarColor_4": { "type": "object", "properties": { "color": { "allOf": [ { "$ref": "#/components/schemas/UserAvatarColorRgb_4" } ] } } }, "UserPersonalInfoChange_2": { "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_2" } ] } }, "required": [ "userId", "info" ] }, "Permission_2": { "type": "string", "enum": [ "owner", "admin", "editor", "no_access", "viewer" ] }, "UserPermissionUser_2": { "type": "object", "properties": { "email": { "type": "string" }, "userId": { "type": "string", "format": "uuid" } } }, "OrganizationInvitedPermission_2": { "type": "string", "enum": [ "admin", "no_access" ] }, "UserPermissionOrganization_2": { "type": "object", "properties": { "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/OrganizationInvitedPermission_2" } ] }, "organizationName": { "type": "string", "example": "EasyDMARC" } }, "required": [ "role" ] }, "ProductInvitedPermissionRole_2": { "type": "string", "enum": [ "admin", "editor", "no_access" ] }, "ProductType_5": { "type": "string", "enum": [ "dmarc", "sender", "inguard" ] }, "UserPermissionProduct_2": { "type": "object", "properties": { "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/ProductInvitedPermissionRole_2" } ] }, "productId": { "type": "string", "example": "dmarc_666a8f2eef097adfee1272d7" }, "type": { "example": "dmarc", "allOf": [ { "$ref": "#/components/schemas/ProductType_5" } ] }, "productName": { "type": "string", "example": "DMARC" } }, "required": [ "role", "productId", "type" ] }, "UserPermissionResourceGroup_2": { "type": "object", "properties": { "resourceGroupId": { "type": "string", "example": "resourceGroupId" }, "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/Permission_2" } ] }, "resourceGroupName": { "type": "string", "example": "Resource Group Title" } }, "required": [ "resourceGroupId", "role" ] }, "UserPermissionResource_2": { "type": "object", "properties": { "role": { "example": "admin", "allOf": [ { "$ref": "#/components/schemas/Permission_2" } ] }, "resourceGroupId": { "type": "string", "example": "resourceGroupId" }, "resourceId": { "type": "string", "example": "resourceId" }, "resourceName": { "type": "string", "example": "Resource Title" } }, "required": [ "role", "resourceGroupId", "resourceId" ] }, "UserPermissionV1_2": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionUser_2" } }, "organization": { "$ref": "#/components/schemas/UserPermissionOrganization_2" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionProduct_2" } }, "resourceGroups": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionResourceGroup_2" } }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/UserPermissionResource_2" } } }, "required": [ "users" ] }, "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_5" } ] }, "avatarColor": { "description": "Color scheme for the user's avatar when no image is set. Used for generating colored initials.", "allOf": [ { "$ref": "#/components/schemas/UserAvatarColor_4" } ] } }, "required": [ "id", "username", "firstName", "lastName", "email", "emailVerified" ] }, "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_2" } ] }, "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_2" } ] } }, "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" ] } }, "examples": {}, "headers": {}, "requestBodies": {} }, "x-tagGroups": [ { "name": "API", "tags": [ "Authentication", "Domains", "Alerting", "DNS Lookup", "Aggregate Reports", "Audit Log", "DNS Intelligence", "Failure Reports" ] }, { "name": "Partner API", "tags": [ "Organizations", "Billing - Subscriptions & Pricing", "Billing - Billing Information", "Billing - Invoices", "Billing - Payment Methods", "Users" ] } ] }