openapi: 3.0.3 info: title: Email Authentication Compliance API version: 1.0.0 description: Checks any domain's SPF, DKIM, DMARC and MX records and returns a structured deliverability report, a 0-100 deliverability score, and plain-English fixes. Built for SaaS founders, ESPs, and agencies auditing sender domains. paths: /api/v1/account/keys/: get: operationId: account_keys_list description: |- GET /api/v1/account/keys/ - list this account's keys (masked). POST /api/v1/account/keys/ - issue an additional key (e.g. one per environment); returns the plaintext secret once. parameters: - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer tags: - account security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedAPIKeyList' description: '' post: operationId: account_keys_create description: |- GET /api/v1/account/keys/ - list this account's keys (masked). POST /api/v1/account/keys/ - issue an additional key (e.g. one per environment); returns the plaintext secret once. tags: - account security: - ApiKeyAuth: [] responses: '201': content: application/json: schema: $ref: '#/components/schemas/APIKey' description: '' /api/v1/account/keys/{key_id}/revoke/: post: operationId: account_keys_revoke_create description: |- POST /api/v1/account/keys//revoke/ - deactivate a key. Soft-delete (is_active=False) rather than hard delete, so revoked keys stay in the audit trail and any in-flight requests fail cleanly via the authentication layer's is_active check instead of a dangling FK. parameters: - in: path name: key_id schema: type: string format: uuid required: true tags: - account security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/APIKey' description: '' /api/v1/account/me/: get: operationId: account_me_retrieve description: |- GET /api/v1/account/me/ - the authenticated account's own profile, tier, and usage counter. tags: - account security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/Account' description: '' /api/v1/billing/checkout/: post: operationId: billing_checkout_create description: |- POST /api/v1/billing/checkout/ - body: {"plan": "pro"|"business"} Returns a Paddle-hosted checkout URL to redirect the customer to. Tier is NOT flipped here - only the webhook handler below does that, once Paddle confirms the transaction actually completed. tags: - billing security: - ApiKeyAuth: [] responses: '200': description: No response body /api/v1/billing/webhook/paddle/: post: operationId: billing_webhook_paddle_create description: |- POST /api/v1/billing/webhook/paddle/ - Paddle calls this directly, so it can't carry our API-key auth; authenticity instead comes from verifying the Paddle-Signature header against PADDLE_WEBHOOK_SECRET (see billing/signature.py). tags: - billing security: - {} responses: '200': description: No response body /api/v1/check/: post: operationId: check_create description: Checks a domain's SPF, DKIM, DMARC, and MX DNS records. Free tier gets full raw detection results; Pro/Business also get a 0-100 Deliverability Score and actionable fix recommendations with exact DNS records to add. tags: - check requestBody: content: application/json: schema: $ref: '#/components/schemas/DomainCheckRequestRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/DomainCheckRequestRequest' multipart/form-data: schema: $ref: '#/components/schemas/DomainCheckRequestRequest' required: true security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/DomainCheckResponse' description: '' /api/v1/check-results/{result_id}/export/: get: operationId: check_results_export_retrieve description: Returns the JSON report shown below by default or with export_format=json. With export_format=pdf, returns a binary application/pdf file download instead (not representable as a JSON schema - same report, rendered as a document). parameters: - in: query name: export_format schema: type: string enum: - json - pdf - in: path name: result_id schema: type: string format: uuid required: true tags: - check-results security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/CheckResultExportResponse' description: '' /api/v1/check/bulk/: post: operationId: check_bulk_create description: |- POST /api/v1/check/bulk/ - agencies checking many client domains in one call. Pro/Business only; max domain count is tier-limited. tags: - check requestBody: content: application/json: schema: $ref: '#/components/schemas/BulkCheckRequestRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/BulkCheckRequestRequest' multipart/form-data: schema: $ref: '#/components/schemas/BulkCheckRequestRequest' required: true security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/BulkCheckResponse' description: '' /api/v1/domains/: get: operationId: domains_list description: |- GET /api/v1/domains/ - this account's check history, one row per domain with its most recent score. parameters: - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer tags: - domains security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedDomainList' description: '' /api/v1/domains/{domain_id}/checks/: get: operationId: domains_checks_list description: |- GET /api/v1/domains//checks/ - full check history for one domain, newest first - what monitoring's change detection is built on, and what lets an agency show a client "we fixed this on March 3rd". parameters: - in: path name: domain_id schema: type: string format: uuid required: true - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer tags: - domains security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedCheckResultList' description: '' /api/v1/monitoring/: get: operationId: monitoring_list description: |- GET /api/v1/monitoring/ - list this account's monitored domains. POST /api/v1/monitoring/ - start monitoring a domain (creates the Domain record too if this account hasn't checked it before). tags: - monitoring security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: type: array items: $ref: '#/components/schemas/MonitoringSubscription' description: '' post: operationId: monitoring_create description: |- GET /api/v1/monitoring/ - list this account's monitored domains. POST /api/v1/monitoring/ - start monitoring a domain (creates the Domain record too if this account hasn't checked it before). tags: - monitoring requestBody: content: application/json: schema: $ref: '#/components/schemas/MonitoringSubscriptionCreateRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/MonitoringSubscriptionCreateRequest' multipart/form-data: schema: $ref: '#/components/schemas/MonitoringSubscriptionCreateRequest' required: true security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/MonitoringSubscription' description: '' /api/v1/monitoring/{subscription_id}/: get: operationId: monitoring_retrieve description: |- GET/PATCH/DELETE /api/v1/monitoring// DELETE deactivates rather than hard-deletes, preserving delivery/check history for the domain. parameters: - in: path name: subscription_id schema: type: string format: uuid required: true tags: - monitoring security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/MonitoringSubscription' description: '' patch: operationId: monitoring_partial_update description: |- GET/PATCH/DELETE /api/v1/monitoring// DELETE deactivates rather than hard-deletes, preserving delivery/check history for the domain. parameters: - in: path name: subscription_id schema: type: string format: uuid required: true tags: - monitoring requestBody: content: application/json: schema: $ref: '#/components/schemas/PatchedMonitoringSubscriptionPatchRequestRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/PatchedMonitoringSubscriptionPatchRequestRequest' multipart/form-data: schema: $ref: '#/components/schemas/PatchedMonitoringSubscriptionPatchRequestRequest' security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/MonitoringSubscription' description: '' delete: operationId: monitoring_destroy description: |- GET/PATCH/DELETE /api/v1/monitoring// DELETE deactivates rather than hard-deletes, preserving delivery/check history for the domain. parameters: - in: path name: subscription_id schema: type: string format: uuid required: true tags: - monitoring security: - ApiKeyAuth: [] responses: '204': description: No response body /api/v1/monitoring/{subscription_id}/logs/: get: operationId: monitoring_logs_list description: |- GET /api/v1/monitoring//logs/ - webhook delivery history, for debugging "why didn't I get notified". parameters: - name: page required: false in: query description: A page number within the paginated result set. schema: type: integer - in: path name: subscription_id schema: type: string format: uuid required: true tags: - monitoring security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedWebhookDeliveryLogList' description: '' /api/v1/monitoring/{subscription_id}/test/: post: operationId: monitoring_test_create description: |- POST /api/v1/monitoring//test/ - fires a signed test payload at the configured webhook_url so the customer can confirm their receiving endpoint + signature verification works before relying on it. parameters: - in: path name: subscription_id schema: type: string format: uuid required: true tags: - monitoring security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/TestWebhookResponse' description: '' /api/v1/signup/: post: operationId: signup_create description: |- POST /api/v1/signup/ - public, no API key required. Creates a free-tier Account and its first APIKey in one call so a new user goes from "nothing" to "has a working key" in a single request - every extra step here is a drop-off point for a self-serve API product. tags: - signup requestBody: content: application/json: schema: $ref: '#/components/schemas/SignupRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SignupRequest' multipart/form-data: schema: $ref: '#/components/schemas/SignupRequest' required: true security: - {} responses: '201': content: application/json: schema: $ref: '#/components/schemas/Signup' description: '' /api/v1/tools/generate-dmarc/: post: operationId: tools_generate_dmarc_create description: |- POST /api/v1/tools/generate-dmarc/ - builds a ready-to-paste DMARC TXT record for the requested policy/reporting configuration. tags: - tools requestBody: content: application/json: schema: $ref: '#/components/schemas/DMARCGeneratorRequestRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/DMARCGeneratorRequestRequest' multipart/form-data: schema: $ref: '#/components/schemas/DMARCGeneratorRequestRequest' required: true security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/GeneratedDMARCResponse' description: '' /api/v1/tools/generate-spf/: post: operationId: tools_generate_spf_create description: |- POST /api/v1/tools/generate-spf/ - "I send via X + Y" -> exact SPF TXT record. Paid: this is the tool that turns a detected problem into a 5-second fix instead of a trip to the RFC. tags: - tools requestBody: content: application/json: schema: $ref: '#/components/schemas/SPFGeneratorRequestRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SPFGeneratorRequestRequest' multipart/form-data: schema: $ref: '#/components/schemas/SPFGeneratorRequestRequest' security: - ApiKeyAuth: [] responses: '200': content: application/json: schema: $ref: '#/components/schemas/GeneratedSPFResponse' description: '' components: schemas: APIKey: type: object description: Read-only view of an existing key - never exposes the secret. properties: id: type: string format: uuid readOnly: true name: type: string readOnly: true prefix: type: string readOnly: true is_active: type: boolean readOnly: true created_at: type: string format: date-time readOnly: true last_used_at: type: string format: date-time readOnly: true nullable: true required: - created_at - id - is_active - last_used_at - name - prefix Account: type: object properties: id: type: string format: uuid readOnly: true email: type: string format: email readOnly: true company_name: type: string readOnly: true tier: allOf: - $ref: '#/components/schemas/TierEnum' readOnly: true subscription_status: allOf: - $ref: '#/components/schemas/SubscriptionStatusEnum' readOnly: true total_requests: type: integer readOnly: true created_at: type: string format: date-time readOnly: true limits: type: string readOnly: true required: - company_name - created_at - email - id - limits - subscription_status - tier - total_requests AdkimEnum: enum: - r - s type: string description: |- * `r` - r * `s` - s AllQualifierEnum: enum: - '-' - '~' - '?' - + type: string description: |- * `-` - - * `~` - ~ * `?` - ? * `+` - + AspfEnum: enum: - r - s type: string description: |- * `r` - r * `s` - s BlacklistIPResult: type: object properties: listed: type: boolean listed_on: type: array items: type: string required: - listed - listed_on BlacklistResult: type: object properties: checked: type: boolean reason: type: string nullable: true is_blacklisted: type: boolean ips_checked: type: array items: type: string results: type: object additionalProperties: $ref: '#/components/schemas/BlacklistIPResult' description: Keyed by IP address. required: - checked - ips_checked - is_blacklisted BulkCheckRequestRequest: type: object properties: domains: type: array items: type: string minLength: 1 maxLength: 253 minItems: 1 required: - domains BulkCheckResponse: type: object properties: count: type: integer results: type: array items: $ref: '#/components/schemas/DomainCheckResponse' description: 'One entry per requested domain, in the shape of a normal check response. A domain that failed to check entirely (rare - e.g. an unexpected DNS error) appears instead as {"domain": ..., "error": "check_failed"}.' required: - count - results CheckResult: type: object properties: id: type: string format: uuid readOnly: true domain: type: string readOnly: true checked_at: type: string format: date-time readOnly: true spf: readOnly: true dkim: readOnly: true dmarc: readOnly: true mx: readOnly: true blacklist: readOnly: true score: type: integer readOnly: true score_breakdown: readOnly: true recommendations: readOnly: true required: - blacklist - checked_at - dkim - dmarc - domain - id - mx - recommendations - score - score_breakdown - spf CheckResultExportResponse: type: object description: |- GET /api/v1/check-results//export/ with export_format=json (the default). export_format=pdf returns a binary application/pdf download instead - not representable as a JSON schema, described in the endpoint's text description instead. properties: domain: type: string checked_at: type: string format: date-time spf: $ref: '#/components/schemas/SPFResult' dkim: $ref: '#/components/schemas/DKIMResult' dmarc: $ref: '#/components/schemas/DMARCResult' mx: $ref: '#/components/schemas/MXResult' blacklist: $ref: '#/components/schemas/BlacklistResult' score: type: integer score_breakdown: type: array items: $ref: '#/components/schemas/ScoreCategory' recommendations: type: array items: $ref: '#/components/schemas/Recommendation' exported_at: type: string format: date-time required: - checked_at - dkim - dmarc - domain - exported_at - mx - recommendations - score - score_breakdown - spf DKIMResult: type: object properties: present: type: boolean checked_selectors: type: array items: type: string selectors: type: object additionalProperties: $ref: '#/components/schemas/DKIMSelectorResult' description: Keyed by selector name, only selectors that resolved. warnings: type: array items: type: string required: - checked_selectors - present - selectors - warnings DKIMSelectorResult: type: object properties: selector: type: string present: type: boolean valid: type: boolean raw: type: string nullable: true key_type: type: string nullable: true public_key_present: type: boolean errors: type: array items: type: string required: - errors - key_type - present - public_key_present - raw - selector - valid DMARCGeneratorRequestRequest: type: object properties: domain: type: string minLength: 1 maxLength: 253 policy: allOf: - $ref: '#/components/schemas/PolicyEnum' default: none pct: type: integer maximum: 100 minimum: 0 default: 100 rua: type: array items: type: string format: email minLength: 1 ruf: type: array items: type: string format: email minLength: 1 subdomain_policy: nullable: true oneOf: - $ref: '#/components/schemas/SubdomainPolicyEnum' - $ref: '#/components/schemas/NullEnum' adkim: allOf: - $ref: '#/components/schemas/AdkimEnum' default: r aspf: allOf: - $ref: '#/components/schemas/AspfEnum' default: r required: - domain DMARCResult: type: object properties: present: type: boolean valid: type: boolean raw: type: string nullable: true policy: type: string nullable: true subdomain_policy: type: string nullable: true pct: type: integer rua: type: array items: type: string ruf: type: array items: type: string adkim: type: string aspf: type: string errors: type: array items: type: string warnings: type: array items: type: string required: - adkim - aspf - errors - pct - policy - present - raw - rua - ruf - subdomain_policy - valid - warnings DNSRecordSuggestion: type: object properties: type: type: string host: type: string nullable: true value: type: string nullable: true required: - host - type - value Domain: type: object properties: id: type: string format: uuid readOnly: true name: type: string readOnly: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true latest_score: type: string readOnly: true required: - created_at - id - latest_score - name - updated_at DomainCheckRequestRequest: type: object properties: domain: type: string minLength: 1 maxLength: 253 check_blacklist: type: boolean default: false required: - domain DomainCheckResponse: type: object description: |- The shape of POST /api/v1/check/'s response. score/grade/ score_breakdown/recommendations are nullable because free-tier accounts get them stripped to None (see domains.views._strip_paid_fields) rather than omitted - client code doesn't need tier-conditional parsing. properties: domain: type: string domain_exists: type: boolean spf: $ref: '#/components/schemas/SPFResult' dkim: $ref: '#/components/schemas/DKIMResult' dmarc: $ref: '#/components/schemas/DMARCResult' mx: $ref: '#/components/schemas/MXResult' blacklist: allOf: - $ref: '#/components/schemas/BlacklistResult' description: Only present when check_blacklist=true was requested. score: type: integer nullable: true grade: type: string nullable: true score_breakdown: type: array items: $ref: '#/components/schemas/ScoreCategory' nullable: true recommendations: type: array items: $ref: '#/components/schemas/Recommendation' nullable: true upgrade_message: type: string description: Only present on free-tier responses. required: - dkim - dmarc - domain - domain_exists - grade - mx - recommendations - score - score_breakdown - spf FrequencyEnum: enum: - daily - weekly type: string description: |- * `daily` - Daily * `weekly` - Weekly GeneratedDMARCResponse: type: object properties: record: type: string host: type: string required: - host - record GeneratedSPFResponse: type: object properties: record: type: string unrecognized_esps: type: array items: type: string warnings: type: array items: type: string required: - record - unrecognized_esps - warnings MXRecord: type: object properties: priority: type: integer host: type: string required: - host - priority MXResult: type: object properties: present: type: boolean valid: type: boolean is_null_mx: type: boolean records: type: array items: $ref: '#/components/schemas/MXRecord' errors: type: array items: type: string required: - errors - present - records - valid MonitoringSubscription: type: object properties: id: type: string format: uuid readOnly: true domain: type: string readOnly: true frequency: allOf: - $ref: '#/components/schemas/FrequencyEnum' readOnly: true webhook_url: type: string format: uri readOnly: true active: type: boolean readOnly: true last_checked_at: type: string format: date-time readOnly: true nullable: true consecutive_webhook_failures: type: integer readOnly: true created_at: type: string format: date-time readOnly: true required: - active - consecutive_webhook_failures - created_at - domain - frequency - id - last_checked_at - webhook_url MonitoringSubscriptionCreateRequest: type: object properties: domain: type: string minLength: 1 maxLength: 253 frequency: allOf: - $ref: '#/components/schemas/FrequencyEnum' default: daily webhook_url: type: string format: uri minLength: 1 maxLength: 500 required: - domain - webhook_url NullEnum: enum: - null PaginatedAPIKeyList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/APIKey' PaginatedCheckResultList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/CheckResult' PaginatedDomainList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/Domain' PaginatedWebhookDeliveryLogList: type: object required: - count - results properties: count: type: integer example: 123 next: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=4 previous: type: string nullable: true format: uri example: http://api.example.org/accounts/?page=2 results: type: array items: $ref: '#/components/schemas/WebhookDeliveryLog' PatchedMonitoringSubscriptionPatchRequestRequest: type: object description: |- Documents PATCH /api/v1/monitoring// - the view applies these fields ad-hoc from request.data rather than running them through a serializer at runtime, so this exists purely for accurate OpenAPI docs of what's actually accepted. properties: frequency: $ref: '#/components/schemas/FrequencyEnum' webhook_url: type: string format: uri minLength: 1 maxLength: 500 active: type: boolean PolicyEnum: enum: - none - quarantine - reject type: string description: |- * `none` - none * `quarantine` - quarantine * `reject` - reject Recommendation: type: object properties: priority: type: string category: type: string issue: type: string fix: type: string dns_record: allOf: - $ref: '#/components/schemas/DNSRecordSuggestion' nullable: true required: - category - dns_record - fix - issue - priority SPFGeneratorRequestRequest: type: object properties: esps: type: array items: type: string minLength: 1 extra_includes: type: array items: type: string minLength: 1 extra_ip4: type: array items: type: string minLength: 1 all_qualifier: allOf: - $ref: '#/components/schemas/AllQualifierEnum' default: '~' SPFMechanism: type: object properties: qualifier: type: string mechanism: type: string value: type: string nullable: true required: - mechanism - qualifier - value SPFResult: type: object properties: present: type: boolean valid: type: boolean raw: type: string nullable: true mechanisms: type: array items: $ref: '#/components/schemas/SPFMechanism' includes: type: array items: type: string all_qualifier: type: string nullable: true dns_lookup_count: type: integer errors: type: array items: type: string warnings: type: array items: type: string required: - all_qualifier - dns_lookup_count - errors - includes - mechanisms - present - raw - valid - warnings ScoreCategory: type: object properties: category: type: string max_points: type: integer points_earned: type: integer reasons: type: array items: type: string required: - category - max_points - points_earned - reasons Signup: type: object description: |- Public signup: creates a free-tier Account plus its first APIKey. No password/login involved - the API key IS the credential. properties: email: type: string format: email maxLength: 254 company_name: type: string maxLength: 255 required: - email SignupRequest: type: object description: |- Public signup: creates a free-tier Account plus its first APIKey. No password/login involved - the API key IS the credential. properties: email: type: string format: email minLength: 1 maxLength: 254 company_name: type: string maxLength: 255 required: - email SubdomainPolicyEnum: enum: - none - quarantine - reject type: string description: |- * `none` - none * `quarantine` - quarantine * `reject` - reject SubscriptionStatusEnum: enum: - none - active - past_due - canceled type: string description: |- * `none` - No subscription * `active` - Active * `past_due` - Past due * `canceled` - Canceled TestWebhookResponse: type: object properties: success: type: boolean status_code: type: integer nullable: true error: type: string required: - error - status_code - success TierEnum: enum: - free - pro - business type: string description: |- * `free` - Free * `pro` - Pro * `business` - Business WebhookDeliveryLog: type: object properties: id: type: string format: uuid readOnly: true sent_at: type: string format: date-time readOnly: true event_type: type: string readOnly: true success: type: boolean readOnly: true status_code: type: integer readOnly: true nullable: true error: type: string readOnly: true required: - error - event_type - id - sent_at - status_code - success securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: 'API key issued by POST /api/v1/signup/. Send it as the X-API-Key header on every request. (Authorization: Api-Key is also accepted, but Swagger UI''s Authorize dialog fills in X-API-Key.)'