mailboxlayer API — Verification

naftiko: "1.0.0-alpha2"

info:
  label: "mailboxlayer API — Verification"
  description: >-
    Email Verification — Verification. 1 operation. Lead operation: Verify Email Address.
    Self-contained Naftiko capability covering one mailboxlayer business surface.
  tags:
    - Mailboxlayer
    - Email Verification
    - Verification
  created: "2026-05-30"
  modified: "2026-05-30"

binds:
  - namespace: env
    keys:
      MAILBOXLAYER_ACCESS_KEY: MAILBOXLAYER_ACCESS_KEY

capability:

  # 1. Consumes - the upstream HTTP API this capability speaks to
  consumes:
    - type: http
      namespace: "mailboxlayer-verification"
      baseUri: "https://apilayer.net/api"
      description: "mailboxlayer API — Verification business capability. Self-contained, no shared references."
      authentication:
        type: apikey
        key: access_key
        value: "{{env.MAILBOXLAYER_ACCESS_KEY}}"
        placement: query
      resources:
        - name: "check"
          path: "/check"
          operations:
            - name: "checkEmail"
              method: GET
              description: "Verifies a single email address (syntax, MX, SMTP, catch-all, role, disposable, free, score)."
              inputParameters:
                - name: "email"
                  in: query
                  type: string
                  required: true
                  description: "The email address to verify."
                - name: "smtp"
                  in: query
                  type: integer
                  required: false
                  description: "Set to 0 to skip the real-time SMTP check (default 1)."
                - name: "format"
                  in: query
                  type: integer
                  required: false
                  description: "Set to 1 to pretty-print the JSON response (default 0)."
                - name: "callback"
                  in: query
                  type: string
                  required: false
                  description: "JSONP callback function name."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  # 2. REST exposer - one Spectral-compliant resource per consumed op
  exposes:
    - type: rest
      namespace: "mailboxlayer-verification-rest"
      port: 8080
      description: "REST adapter for mailboxlayer API — Verification. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/check"
          name: "check"
          description: "REST surface for email verification check."
          operations:
            - method: GET
              name: "checkEmail"
              description: "Verifies a single email address."
              call: "mailboxlayer-verification.checkEmail"
              with:
                email: "rest.email"
                smtp: "rest.smtp"
                format: "rest.format"
                callback: "rest.callback"
              outputParameters:
                - type: object
                  mapping: "$."

  # 3. MCP exposer - one verb-noun tool per consumed op
    - type: mcp
      namespace: "mailboxlayer-verification-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for mailboxlayer API — Verification. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "verify-email"
          description: "Verify a single email address: syntax, MX records, SMTP check, catch-all, role, disposable, free, and a 0-1 deliverability score."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "mailboxlayer-verification.checkEmail"
          with:
            email: "tools.email"
            smtp: "tools.smtp"
            format: "tools.format"
            callback: "tools.callback"
          outputParameters:
            - type: object
              mapping: "$."