API Overview

The MailShield API provides programmatic access to your email security monitoring data. Use it to integrate domain monitoring, DNS checks, and report data into your existing tools and workflows.

Base URL

All API requests should be made to:

https://app.mailshield.app/api/v1

Quick Start

1. Create an API Token

Generate a token from your MailShield dashboard:

1. Go to Settings > API (organization owners and admins)
2. Click Create Token, and make it read-only if your integration only reads data
3. Copy and securely store the token (it's only shown once)

2. Make Your First Request

curl -H "Authorization: Bearer ms_your_token_here" \
  https://app.mailshield.app/api/v1/domains

3. Explore the Endpoints

• Domains: list, create, update, and delete domains
• Customers: group domains by customer, and list, create, update, and delete customers
• DNS Checks: trigger and retrieve security checks
• MTA-STS: configure MTA-STS and read the records it needs
• DKIM Selectors: list, register, and remove DKIM selectors
• Security Score: get domain security scores
• Reports: access DMARC and TLS-RPT reports
• Alerts: list your organization's alerts

Features

• RESTful Design: predictable, resource-oriented URLs
• JSON Responses: all responses are in JSON format
• Bearer Authentication: simple token-based auth, with read-only tokens for integrations that only read data
• IP Allowlisting: restrict token usage to specific IPs
• Rate Limiting: fair usage limits with clear headers
• OpenAPI Spec: import into Postman, Insomnia, and more

Pagination

List endpoints return up to 20 items by default. Use limit (up to 100) and page to page through the rest, and keep going while meta.pagination.hasMore is true. See Integration Patterns for a helper.

Response Format

All responses follow a consistent format:

Success Response

{
  "data": {
    // Response data here
  },
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "hasMore": true
    }
  }
}

Error Response

{
  "error": {
    "code": "not_found",
    "message": "Domain not found"
  }
}

API Availability

API access is available on Pro and Enterprise. Check your current plan in Settings > Billing.

Next Steps

• Authentication: learn about token management
• Rate Limiting: understand usage limits
• Error Handling: handle errors gracefully
• OpenAPI Spec: import into your favorite tools