EmailKind Signup API

openapi: 3.2.0
info:
  title: EmailKind Signup API
  version: 1.0.0
  description: Classify email addresses and domains by provider and type (business, personal, disposable, education, role) using passive DNS analysis. No email is ever sent.
  contact:
    name: EmailKind
    url: https://emailkind.com/contact
  license:
    name: Proprietary
servers:
- url: https://emailkind.com/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Signup
paths:
  /signup:
    post:
      operationId: signup
      summary: Start a programmatic signup and get a free API key
      description: 'Step 1 of 2. Emails a confirmation code to the address and stores nothing: no account exists until the code comes back. Send the code to /signup/confirm to receive a live free-tier API key (100 lookups/month). Intended for AI agents and scripts, which cannot use the HTML signup form. Limited to 5 requests per hour per IP and 3 codes per hour per address.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
      responses:
        '202':
          description: A confirmation code was emailed. The response is identical whether or not the address already has an account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupResponse'
        '400':
          description: Malformed body, invalid address, or a disposable domain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many signups from this IP, or too many codes sent to this address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Signup temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Signup
  /signup/confirm:
    post:
      operationId: signupConfirm
      summary: Exchange the confirmation code for an API key
      description: Step 2 of 2. Creates the account if it does not exist and returns a live API key, shown once and not recoverable. The code expires 15 minutes after /signup and may be attempted 5 times before the signup is cancelled.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupConfirmRequest'
      responses:
        '201':
          description: Account confirmed and API key issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupConfirmResponse'
        '400':
          description: Code incorrect, expired, or never issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The account already holds the maximum number of keys for its plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many incorrect codes; the signup was cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Signup
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        request_id:
          type: string
        error:
          type: object
          properties:
            code:
              type: string
              example: MISSING_PARAMETER
            message:
              type: string
    SignupConfirmRequest:
      type: object
      required:
      - email
      - code
      properties:
        email:
          type: string
          format: email
          description: The same address used for /signup.
          example: agent@example.com
        code:
          type: string
          description: The code from the email. Case-insensitive; spaces and dashes are ignored.
          example: K7M2QXAB
    SignupRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
          description: Where the confirmation code is sent. Must be a real, non-disposable address.
          example: agent@example.com
        lang:
          type: string
          enum:
          - en
          - fr
          default: en
          description: Language of the confirmation email.
    SignupResponse:
      type: object
      properties:
        success:
          type: boolean
        request_id:
          type: string
        status:
          type: string
          example: verification_sent
        expires_in:
          type: integer
          description: Seconds the code remains valid.
          example: 900
        next:
          type: string
          example: POST /v1/signup/confirm
        message:
          type: string
    SignupConfirmResponse:
      type: object
      properties:
        success:
          type: boolean
        request_id:
          type: string
        api_key:
          type: string
          description: Live API key. Returned once and never again — store it as a secret.
          example: sk_live_...
        plan:
          type: string
          example: free
        monthly_limit:
          type: integer
          description: Lookups per month. 0 means unlimited.
          example: 100
        burst_limit:
          type: integer
          description: Requests per minute.
          example: 10
        docs:
          type: string
          format: uri
        warning:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued in the dashboard, sent as ''Authorization: Bearer sk_live_...''.'