{
  "openapi": "3.1.0",
  "info": {
    "title": "CheckDisposable Email API",
    "version": "1.0.0",
    "description": "HTTP API to detect disposable, temporary, and throwaway email addresses (mailinator, guerrillamail, 10minutemail, temp-mail, yopmail, tempr.email, and 120k+ others) at signup. Single GET request, Bearer auth, sub-50ms median response.",
    "termsOfService": "https://checkdisposable.email/terms",
    "contact": {
      "name": "CheckDisposable Email Support",
      "email": "hello@checkdisposable.email",
      "url": "https://checkdisposable.email"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://checkdisposable.email/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.checkdisposable.email",
      "description": "Production"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/check": {
      "get": {
        "operationId": "checkEmail",
        "summary": "Check if an email is disposable",
        "description": "Returns is_disposable=true when the email domain matches a known disposable / temporary / throwaway email provider. Median response time: 47 ms. Free tier: 500 checks/month, no credit card. Paid: $9/month for unlimited checks.",
        "tags": [
          "check"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "email",
            "required": true,
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "test@mailinator.com",
            "description": "The email address to check."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful check.",
            "headers": {
              "X-RateLimit-Plan": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "free",
                    "unlimited",
                    "lifetime"
                  ]
                }
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "string"
                }
              },
              "X-RateLimit-Burst-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Burst-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CheckResult"
                },
                "examples": {
                  "disposable": {
                    "summary": "Disposable address",
                    "value": {
                      "email": "test@mailinator.com",
                      "domain": "mailinator.com",
                      "is_disposable": true,
                      "blocked": true,
                      "reason": "Domain is a known disposable / temporary email provider.",
                      "duration_ms": 47
                    }
                  },
                  "clean": {
                    "summary": "Clean address",
                    "value": {
                      "email": "founder@stripe.com",
                      "domain": "stripe.com",
                      "is_disposable": false,
                      "blocked": false,
                      "reason": "Domain is not flagged as disposable.",
                      "duration_ms": 19
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request (missing or malformed email).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failure (missing or invalid API key).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. `rate_limit_exceeded` for per-second burst, `plan_limit` for monthly cap.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              }
            }
          },
          "502": {
            "description": "Upstream unreachable. Recommended client behavior: fail open.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "cde_live_xxx",
        "description": "Get a free API key at https://app.checkdisposable.email/signup (500 checks/month, no credit card)."
      }
    },
    "schemas": {
      "CheckResult": {
        "type": "object",
        "required": [
          "email",
          "domain",
          "is_disposable",
          "blocked",
          "duration_ms"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "example": "test@mailinator.com"
          },
          "domain": {
            "type": "string",
            "example": "mailinator.com"
          },
          "is_disposable": {
            "type": "boolean",
            "description": "true when the domain is a known disposable / throwaway / temporary email provider. This is the only field you need to branch on."
          },
          "blocked": {
            "type": "boolean",
            "description": "Mirror of is_disposable for backward compatibility."
          },
          "reason": {
            "type": "string"
          },
          "duration_ms": {
            "type": "integer",
            "example": 47
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "bad_request",
              "auth_required",
              "invalid_api_key",
              "plan_limit",
              "rate_limit_exceeded",
              "upstream_error"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "check",
      "description": "Disposable email detection. The only thing this API does."
    }
  ],
  "externalDocs": {
    "description": "Full integration guide for LLMs",
    "url": "https://checkdisposable.email/llms-full.txt"
  }
}