OpenAPI Specification

MailShield provides a complete OpenAPI 3.1 specification for the API, enabling easy integration with API tools like Swagger UI, Postman, Insomnia, and more.

Specification URL

The OpenAPI specification is available at:

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

Interactive Documentation

Explore the API interactively using our built-in API documentation:

Open API Explorer

The API explorer allows you to:

• Browse all available endpoints
• View request/response schemas
• Test API calls directly in your browser
• Generate code snippets for various languages

---

Importing to Postman

Method 1: Import from URL

1. Open Postman
2. Click Import in the top left
3. Select the Link tab
4. Enter: https://app.mailshield.app/api/v1/openapi.json
5. Click Continue and then Import

Method 2: Import from File

1. Download the spec: curl -o mailshield-openapi.json https://app.mailshield.app/api/v1/openapi.json
2. Open Postman
3. Click Import > Upload Files
4. Select the downloaded mailshield-openapi.json
5. Click Import

Setting Up Authentication

After importing:

1. Click on the imported collection
2. Go to the Authorization tab
3. Select Bearer Token as the type
4. Enter your API token
5. Save the collection

All requests in the collection will now use your token.

---

Importing to Insomnia

1. Open Insomnia
2. Click Create > Import from URL
3. Enter: https://app.mailshield.app/api/v1/openapi.json
4. Click Fetch and Import

Configure Environment

1. Click No Environment > Manage Environments
2. Create a new environment with:

   {
     "baseUrl": "https://app.mailshield.app/api/v1",
     "token": "your-api-token-here"
   }

3. Update requests to use and

---

Importing to Bruno

Bruno is a fast, Git-friendly API client.

1. Create a new collection
2. Right-click the collection > Import
3. Select OpenAPI V3 Spec
4. Enter the URL or upload the JSON file
5. Configure authentication in collection settings

---

Using with Swagger UI

You can run Swagger UI locally with the MailShield spec:

docker run -p 8080:8080 \
  -e SWAGGER_JSON_URL=https://app.mailshield.app/api/v1/openapi.json \
  swaggerapi/swagger-ui

Then open http://localhost:8080 in your browser.

---

Generating Client SDKs

Use the OpenAPI spec to generate client libraries in your preferred language:

Using OpenAPI Generator

# Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

# Generate Python client
openapi-generator-cli generate \
  -i https://app.mailshield.app/api/v1/openapi.json \
  -g python \
  -o ./mailshield-python-client

# Generate TypeScript client
openapi-generator-cli generate \
  -i https://app.mailshield.app/api/v1/openapi.json \
  -g typescript-fetch \
  -o ./mailshield-ts-client

# Generate Go client
openapi-generator-cli generate \
  -i https://app.mailshield.app/api/v1/openapi.json \
  -g go \
  -o ./mailshield-go-client

Available Generators

OpenAPI Generator supports 50+ languages including:

• Python, Ruby, PHP, Java, C#
• TypeScript, JavaScript
• Go, Rust, Swift, Kotlin
• And many more

See the full list of generators.

---

Specification Details

Version

The API follows Semantic Versioning. The current version is 1.0.

Format

• Specification Version: OpenAPI 3.1.0
• Format: JSON
• Authentication: Bearer token (documented in spec)

Schema Validation

You can validate your API requests against the schema:

# Using spectral for linting
npm install -g @stoplight/spectral-cli
spectral lint https://app.mailshield.app/api/v1/openapi.json

---

Changelog

v1.0 (Current)

• Initial API release
• Domain management (CRUD)
• DNS security checks
• Security scoring
• DMARC and TLS-RPT reports
• Alert retrieval