API Documentation

Overview

This API is built using the OpenAPI 3.1.0 specification. It provides various endpoints for account management, alerts, authentication, and domain-related operations.

Base URL

The base URL for all endpoints:

Version 1: https://api.monitordmarc.com/v1

Authentication

Most endpoints are secured using OAuth2 Password Bearer token authentication. To access these endpoints, you need to obtain an access token first using the /auth/token endpoint.  The token received can then be used to make requests user the “Authentication Bearer” header.

Get Token

• Endpoint: POST /v1/auth/token
• Description: Get an access token for authentication to the rest of the MonitorDMARC API
• Request Body:
  • username (string, required)
  • password (string, required)
  • grant_type (string, optional, pattern: “password”)

Renew Token

• Endpoint: GET /v1/auth/renewtoken
• Description: Renew an existing access token.  This must be done prior to the current token expiring
• Authentication: Required

Endpoints

Account

Get Account

• • Endpoint: GET /v1/account/
  • Description: Get current user’s account information
  • Authentication: Required

Alerts

Get Alerts

• • Endpoint: GET /v1/alerts/
  • Description: Get all alerts for the account
  • Authentication: Required
  • Query Parameters:
    • showall (boolean, optional, default: false)

Clear Alert

• • Endpoint: PUT /v1/alerts/{alertid}/clear
  • Description: Clear a specific alert
  • Authentication: Required
  • Path Parameters:
    • alertid (string, required)
  • Query Parameters:
    • domainname (string, required)
    • cleared (boolean, required)

Domains

Get All Domains

• • Endpoint: GET /v1/domains/
  • Description: Retrieve all domains
  • Authentication: Required

Add Domain

• • Endpoint: POST /v1/domains/
  • Description: Add a new domain
  • Authentication: Required
  • Request Body:
    • domainname (string, required)
    • users (array of strings, optional)

Get Domain

• • Endpoint: GET /v1/domains/{domain_id}
  • Description: Get information about a specific domain
  • Authentication: Required
  • Path Parameters:
    • domain_id (string, required)

Update Domain

• • Endpoint: PUT /v1/domains/{domain_id}
  • Description: Update a specific domain
  • Authentication: Required
  • Path Parameters:
    • domain_id (string, required)
  • Request Body:
    • domain (string, required)
    • users (array of strings, required)
    • deleted (boolean, required)
    • valtries (integer, required)
    • status (string, required)

Delete Domain

• • Endpoint: DELETE /v1/domains/{domain_id}
  • Description: Delete a specific domain
  • Authentication: Required
  • Path Parameters:
    • domain_id (string, required)

Verify Domain

• • Endpoint: GET /v1/domains/{domain_id}/verify
  • Description: Verify a specific domain
  • Authentication: Required
  • Path Parameters:
    • domain_id (string, required)

Monitoring

The API provides endpoints for monitoring various aspects of a domain, including SPF, DMARC, BIMI, and DKIM. Each monitoring type has GET, POST, and PUT operations for retrieving, creating, and updating monitors respectively.

Tools

Check BIMI

• • Endpoint: GET /v1/tools/bimi/
  • Description: Check BIMI for a domain
  • Query Parameters:
    • domain (string, required)

Create BIMI

• • Endpoint: POST /v1/tools/bimi/
  • Description: Create a BIMI record
  • Request Body:
    • domainname (string, required)
    • svguri (string, required)
    • vmcuri (string, required)

Check DKIM

• • Endpoint: GET /v1/tools/dkim/
  • Description: Check DKIM for a domain
  • Query Parameters:
    • domain (string, required)
    • selector (string, required)

Create DKIM

• • Endpoint: POST /v1/tools/dkim/
  • Description: Create a DKIM record
  • Request Body:
    • domainname (string, required)
    • selectorname (string, required)
    • keytype (string, must be “rsa”)
    • keylength (integer, enum: [1024, 1280, 1536, 1792, 2048])
    • flags (string, enum: [“y”, “s”, “None”])
    • hashalg (string, enum: [“sha1”, “sha256”])
    • identity (string, required)

Check DMARC

• • Endpoint: GET /v1/tools/dmarc/
  • Description: Check DMARC for a domain
  • Query Parameters:
    • domain (string, required)

Create DMARC

• • Endpoint: POST /v1/tools/dmarc/
  • Description: Create a DMARC record
  • Request Body:
    • domainname (string, required)
    • policy (string, enum: [“none”, “quarantine”, “reject”])
    • rua (array of strings)
    • ruf (array of strings)
    • freport (array of strings, enum: [“spfanddkim”, “spfordkim”, “spf”, “dkim”])
    • spfstrict (string, enum: [“r”, “s”])
    • dkimstrict (string, enum: [“r”, “s”])
    • pct (integer)

Check SPF

• • Endpoint: GET /v1/tools/spf/
  • Description: Check SPF for a domain
  • Query Parameters:
    • domain (string, required)

Create SPF

• • Endpoint: POST /v1/tools/spf/
  • Description: Create an SPF record
  • Request Body:
    • domainname (string, required)
    • sendfromweb (boolean, required)
    • sendfrommx (boolean, required)
    • ip4 (array of strings, optional)
    • ip6 (array of strings, optional)
    • thirdparty (array of strings, optional)
    • strict (string, enum: [“none”, “pass”, “neutral”, “softfail”, “fail”])

Analyze Email

• • Endpoint: POST /v1/tools/emailanalyze/
  • Description: Analyze an email
  • Request Body:
    • emaildata (string, required)

Statistics

Get Total Failures

• • Endpoint: GET /v1/stats/totalfailures
  • Description: Get total failures statistics
  • Authentication: Required
  • Query Parameters:
    • domain (string, optional)

Get Failures By IP

• • Endpoint: GET /v1/stats/failuresbyip
  • Description: Get failures statistics by IP
  • Authentication: Required
  • Query Parameters:
    • domain (string, optional)

Get Failures By Country

• • Endpoint: GET /v1/stats/failuresbycountry
  • Description: Get failures statistics by country
  • Authentication: Required
  • Query Parameters:
    • domain (string, optional)

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. In case of validation errors, a 422 Unprocessable Entity status is returned with details about the validation errors.