Guides & Tutorials

Practical guides to help you integrate with the MimeProtect API.

Getting Started with the MimeProtect API

This guide walks you through creating an API key, making your first API call, and handling responses properly.

Create an API Key

Generate an API key with the appropriate scopes for your integration

API keys are scoped to specific permissions to follow the principle of least privilege. Only request the scopes you actually need for your integration.

api-setup.js

// First, create an API key in the MimeProtect dashboard:
// 1. Go to Settings > API Keys
// 2. Click "Create API Key"
// 3. Select the required scopes:
//    - domains:read - View domain information
//    - domains:write - Create and delete domains
//    - reports:read - Access DMARC/TLS-RPT reports
//    - alerts:read - View security alerts
//    - alerts:write - Update alert status
//    - scans:trigger - Initiate domain scans

// Store your API key securely
const API_KEY = process.env.MIMEPROTECT_API_KEY;
const BASE_URL = "https://mimeprotect.io/api/v1";

Security tip: Never commit API keys to version control. Use environment variables or a secrets manager.

Make Your First API Call

List all domains in your organization

list-domains.js

// Make your first API call to list domains
async function listDomains() {
  const response = await fetch(`${BASE_URL}/domains`, {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error.message}`);
  }

  const result = await response.json();
  return result;
}

// Example response:
// {
//   "data": [
//     {
//       "id": "dom_abc123",
//       "domain": "example.com",
//       "verified": true,
//       "healthStatus": "healthy",
//       ...
//     }
//   ],
//   "meta": {
//     "page": 1,
//     "limit": 20,
//     "total": 1,
//     "totalPages": 1
//   }
// }

Handle Responses and Errors

Build a robust API client with proper error handling

api-client.js

// Robust error handling for API responses
class MimeProtectError extends Error {
  constructor(message, code, status) {
    super(message);
    this.code = code;
    this.status = status;
    this.name = "MimeProtectError";
  }
}

async function apiRequest(endpoint, options = {}) {
  const url = `${BASE_URL}${endpoint}`;

  const response = await fetch(url, {
    ...options,
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  // Handle non-JSON responses (like 204 No Content)
  if (response.status === 204) {
    return null;
  }

  const data = await response.json();

  if (!response.ok) {
    throw new MimeProtectError(
      data.error?.message || "Unknown error",
      data.error?.code || "UNKNOWN_ERROR",
      response.status
    );
  }

  return data;
}

// Usage example with error handling
async function safeFetch() {
  try {
    const domains = await apiRequest("/domains");
    console.log("Domains:", domains.data);
  } catch (error) {
    if (error instanceof MimeProtectError) {
      console.error(`API Error [${error.code}]: ${error.message}`);

      // Handle specific error codes
      switch (error.code) {
        case "UNAUTHORIZED":
          console.error("Check your API key");
          break;
        case "RATE_LIMITED":
          console.error("Too many requests, slow down");
          break;
        case "NOT_FOUND":
          console.error("Resource not found");
          break;
        default:
          console.error("Unexpected error occurred");
      }
    } else {
      throw error;
    }
  }
}

You're ready to go!

Now that you understand the basics, explore the other guides to learn about specific features like domain management, alerts, and reports.