openapi: 3.0.3
info:
  title: EmailRep Reports Reputation API
  version: '1.0'
  description: EmailRep is an email-address reputation and threat-intelligence API operated by Sublime Security, Inc. It crawls and enriches data across social media profiles, professional networking sites, dark-web credential leaks, data breaches, phishing kits, phishing emails, spam lists, open mail relays, spam traps, domain age and reputation, and deliverability signals to predict the risk associated with any email address. Callers issue a `GET /{email}` lookup to receive a reputation verdict, a `suspicious` flag, a `references` count, and a detailed signal block, or `POST /report` to submit observations of malicious email behavior back into the reputation graph.
  contact:
    name: Sublime Security
    url: https://sublimesecurity.com
    email: support@sublimesecurity.com
  license:
    name: EmailRep Terms of Use
    url: https://emailrep.io/terms
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
- url: https://emailrep.io
  description: EmailRep production API
security:
- ApiKeyAuth: []
- {}
tags:
- name: Reputation
  description: Query email address reputation and threat-intelligence signals.
paths:
  /{email}:
    get:
      operationId: queryEmailReputation
      summary: EmailRep Query Email Reputation
      description: Look up reputation, suspiciousness, references, and detailed intelligence signals for an email address. Returns a `reputation` of `high`, `medium`, `low`, or `none`, a boolean `suspicious` flag, a `references` count, and a `details` block covering blacklisting, malicious activity, credential leaks, data breaches, domain reputation, deliverability, MX validity, SPF/DMARC posture, spoofability, free-provider/disposable classification, and online profile observations. Use `summary=true` to additionally receive a human-readable `summary` field.
      tags:
      - Reputation
      parameters:
      - name: email
        in: path
        required: true
        description: The email address to query.
        schema:
          type: string
          format: email
        example: bill@microsoft.com
      - name: summary
        in: query
        required: false
        description: When `true`, include a human-readable `summary` field in the response.
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '200':
          description: Reputation lookup succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailReputation'
              examples:
                QueryEmailReputation200Example:
                  summary: Default queryEmailReputation 200 response
                  x-microcks-default: true
                  value:
                    email: bill@microsoft.com
                    reputation: high
                    suspicious: false
                    references: 79
                    details:
                      blacklisted: false
                      malicious_activity: false
                      malicious_activity_recent: false
                      credentials_leaked: true
                      credentials_leaked_recent: false
                      data_breach: true
                      first_seen: 07/01/2008
                      last_seen: 05/24/2019
                      domain_exists: true
                      domain_reputation: high
                      new_domain: false
                      days_since_domain_creation: 10341
                      suspicious_tld: false
                      spam: false
                      free_provider: false
                      disposable: false
                      deliverable: true
                      accept_all: true
                      valid_mx: true
                      spoofable: false
                      spf_strict: true
                      dmarc_enforced: true
                      profiles:
                      - myspace
                      - spotify
                      - twitter
                      - pinterest
                      - flickr
                      - linkedin
                      - vimeo
                      - angellist
        '400':
          description: Bad request — invalid email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded for the caller's plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    EmailReputationDetails:
      type: object
      title: EmailReputationDetails
      description: Detailed intelligence signals about the email address and its domain.
      properties:
        blacklisted:
          type: boolean
          description: The email is believed to be malicious or spammy.
          example: false
        malicious_activity:
          type: boolean
          description: The email has exhibited malicious behavior (e.g. phishing or fraud).
          example: false
        malicious_activity_recent:
          type: boolean
          description: Malicious behavior observed within the last 90 days.
          example: false
        credentials_leaked:
          type: boolean
          description: Credentials for the email were leaked at some point (data breach, paste, dark web, etc.).
          example: true
        credentials_leaked_recent:
          type: boolean
          description: Credentials were leaked within the last 90 days.
          example: false
        data_breach:
          type: boolean
          description: The email appeared in a known data breach.
          example: true
        first_seen:
          type: string
          description: First date the email was observed in a breach, credential leak, or exhibiting malicious or spammy behavior. `never` if never seen.
          example: 07/01/2008
        last_seen:
          type: string
          description: Last date the email was observed in a breach, credential leak, or exhibiting malicious or spammy behavior. `never` if never seen.
          example: 05/24/2019
        domain_exists:
          type: boolean
          description: Whether the email's domain is a valid, resolvable domain.
          example: true
        domain_reputation:
          type: string
          description: Reputation verdict for the email's domain. `n/a` when the domain is a free provider, disposable, or does not exist.
          enum:
          - high
          - medium
          - low
          - n/a
          example: high
        new_domain:
          type: boolean
          description: The domain was registered within the last year.
          example: false
        days_since_domain_creation:
          type: integer
          description: Days since the domain was created.
          example: 10341
        suspicious_tld:
          type: boolean
          description: The domain uses a top-level domain associated with abuse.
          example: false
        spam:
          type: boolean
          description: The email has exhibited spammy behavior (e.g. spam traps, login form abuse).
          example: false
        free_provider:
          type: boolean
          description: The email uses a free email provider (e.g. Gmail, Yahoo, Outlook).
          example: false
        disposable:
          type: boolean
          description: The email uses a temporary or disposable provider.
          example: false
        deliverable:
          type: boolean
          description: The address is deliverable based on SMTP probes and MX checks.
          example: true
        accept_all:
          type: boolean
          description: The mail server has a default accept-all policy.
          example: true
        valid_mx:
          type: boolean
          description: The domain has a valid MX record.
          example: true
        spoofable:
          type: boolean
          description: The email address can be spoofed (e.g. SPF is not strict or DMARC is not enforced).
          example: false
        spf_strict:
          type: boolean
          description: SPF record is sufficiently strict to prevent spoofing.
          example: true
        dmarc_enforced:
          type: boolean
          description: DMARC is configured correctly and enforced.
          example: true
        profiles:
          type: array
          description: Online profiles where the email has been observed.
          items:
            type: string
          example:
          - myspace
          - spotify
          - twitter
          - pinterest
          - flickr
          - linkedin
          - vimeo
          - angellist
    Error:
      type: object
      title: Error
      description: Error envelope returned for failed requests.
      required:
      - status
      properties:
        status:
          type: string
          description: Outcome of the request.
          enum:
          - fail
          example: fail
        reason:
          type: string
          description: Human-readable failure reason.
          example: invalid email address
    EmailReputation:
      type: object
      title: EmailReputation
      description: Reputation verdict, suspicious flag, references count, and detailed intelligence signal block returned for an email-address query.
      required:
      - email
      - reputation
      - suspicious
      - references
      - details
      properties:
        email:
          type: string
          format: email
          description: The queried email address, echoed back.
          example: bill@microsoft.com
        reputation:
          type: string
          description: Overall reputation verdict for the address.
          enum:
          - high
          - medium
          - low
          - none
          example: high
        suspicious:
          type: boolean
          description: Whether the email should be treated as suspicious or risky.
          example: false
        references:
          type: integer
          description: Total number of positive and negative reputation sources observed for the address or its associated domain. Not all references are direct mentions of the address.
          example: 79
        summary:
          type: string
          description: Human-readable summary of the reputation verdict. Returned only when the caller passes `summary=true`.
          example: high reputation, seen on 8 profiles, found in 1 data breach
        details:
          $ref: '#/components/schemas/EmailReputationDetails'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Key
      description: EmailRep API key issued at https://emailrep.io/key. Free tier is available; the Commercial and Enterprise tiers raise the per-month and per-day quotas. The key is passed in the `Key` HTTP header on every request.