FFraud Email API

openapi: 3.2.0
info:
  title: FFraud Email API
  version: 1.0.0
  summary: Free, open IP and email fraud intelligence.
  description: 'Check any IP or email for fraud, VPN, proxy, Tor, datacenter, and abuse history. Free for everyone, no usage caps. The public endpoints need no API key; a free key adds batch lookups, usage stats, and the community reporting API. The database behind this API is published daily as MIT-licensed open data at https://github.com/FFraud-com .


    Drop-in compatibility endpoints let you migrate off AbuseIPDB, IPQualityScore, or ipinfo by changing one URL.'
  contact:
    name: FFraud
    url: https://ffraud.com
    email: team@ffraud.com
  license:
    name: MIT
    url: https://github.com/FFraud-com/ip-fraud-database/blob/main/LICENSE
servers:
- url: https://api.ffraud.com
  description: Production
security:
- {}
- ApiKeyHeader: []
tags:
- name: Email
  description: Temporary, alias and abusive email detection, typo suggestions and mail servers.
paths:
  /public/email/check:
    post:
      tags:
      - Email
      summary: Check an email (public, no key)
      operationId: publicEmailCheck
      security:
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailCheckRequest'
      responses:
        '200':
          description: Email intelligence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailResponse'
        '400':
          $ref: '#/components/responses/Error'
  /v1/email/check:
    post:
      tags:
      - Email
      summary: Check an email (with key)
      operationId: emailCheck
      security:
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailCheckRequest'
      responses:
        '200':
          description: Email intelligence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/email/batch:
    post:
      tags:
      - Email
      summary: Check up to 100 emails (with key)
      description: One result per address, in the order sent, each with every field of the single check. The whole batch shares one request_id.
      operationId: emailBatch
      security:
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchEmailRequest'
      responses:
        '200':
          description: One result per address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchEmailResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/email/report:
    post:
      tags:
      - Email
      summary: Report an abusive email (with key)
      description: Adds the address to the community blacklist. Every merchant who checks it afterwards sees the report count and categories; who reported it stays private.
      operationId: emailReport
      security:
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailReportRequest'
      responses:
        '200':
          description: Report recorded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailReportResponse'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/email/lists:
    get:
      tags:
      - Email
      summary: Your allow and block lists (with key)
      description: The calling account's own lists of domains. They decide blocked on its keyed email checks; an entry covers the domain and every domain under it, and the more specific entry wins.
      operationId: emailListsGet
      security:
      - ApiKeyHeader: []
      responses:
        '200':
          description: The two lists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailLists'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Error'
  /v1/email/lists/{domain}:
    put:
      tags:
      - Email
      summary: Allow or block a domain (with key)
      description: Puts the domain on the allow or the block list, or moves it from the other one. Idempotent. Reaches every answer within 30 seconds; up to 1,000 entries per account.
      operationId: emailListsPut
      security:
      - ApiKeyHeader: []
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
        example: partner.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailListRequest'
      responses:
        '200':
          description: The entry as stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailListEntry'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Error'
    delete:
      tags:
      - Email
      summary: Take a domain off your lists (with key)
      operationId: emailListsDelete
      security:
      - ApiKeyHeader: []
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
        example: partner.com
      responses:
        '200':
          description: Whether there was an entry to remove.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailListRemoved'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Error'
components:
  schemas:
    EmailListRemoved:
      type: object
      properties:
        domain:
          type: string
          example: partner.com
        removed:
          type: boolean
    EmailListEntry:
      type: object
      properties:
        domain:
          type: string
          example: partner.com
        list:
          type: string
          enum:
          - allow
          - block
    EmailReportRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          example: scammer@example.org
        category:
          type: string
          enum:
          - chargebacks
          - carding
          - account_abuse
          - refund_fraud
          - identity_theft
          - spam
          - phishing
          - other
          default: other
        comment:
          type: string
          description: A short note for our review.
    EmailResponse:
      type: object
      required:
      - request_id
      - email
      - normalized_email
      - domain
      - did_you_mean
      - is_disposable
      - detection_source
      - safe_domain
      - valid_format
      - is_role_address
      - is_forwarder
      - is_alias_service
      - mx_found
      - mx_records
      - email_type
      properties:
        request_id:
          type: string
          example: req_1a186b70c2f731df36e7c60
          description: The id of this request. Quote it to support to have the check traced. Every address of a batch shares one.
        email:
          type: string
          example: jane.doe+shop@mailinator.com
          description: The address as sent, with outer spaces removed.
        normalized_email:
          type:
          - string
          - 'null'
          example: jane.doe@mailinator.com
          description: 'The address as one mailbox: lowercased, the +tag removed, googlemail.com read as gmail.com and the dots removed on gmail.com. Null when the address is invalid.'
        domain:
          type: string
          example: mailinator.com
        did_you_mean:
          type:
          - string
          - 'null'
          example: null
          description: The corrected address when the domain is one keystroke from a big provider (john@gmial.com gives john@gmail.com). Changes no other field.
        is_disposable:
          type: boolean
          description: True for temporary and alias addresses alike; email_type tells them apart.
        detection_source:
          type: string
          enum:
          - none
          - safe_domain
          - alias_provider
          - alias_provider_mx
          - database
          - pattern
          - mx_host
          - mx_ip
          - provider_live
          - business_mx
          - cleared
          - known_spammer
          - no_mx
          - reserved
          - invalid
          description: 'The check that decided the answer. no_mx: the domain does not exist or accepts no mail, so the address is invalid.'
        safe_domain:
          type: boolean
          description: A major mail provider on the allow list; never disposable.
        valid_format:
          type: boolean
        is_role_address:
          type: boolean
          description: e.g. admin@, support@, info@
        is_forwarder:
          type: boolean
          description: Mail for the domain is passed on to a mailbox somewhere else.
        is_alias_service:
          type: boolean
          description: The forwarding service gives one person unlimited addresses. The yes or no for an alias.
        forwarder_service:
          type: string
          example: Proton Pass
          description: The name of the forwarding service, when it can be named.
        mx_found:
          type:
          - boolean
          - 'null'
          description: The domain publishes mail servers (MX records). Null when the lookup did not finish.
        mx_records:
          type: array
          maxItems: 4
          items:
            type: string
          example:
          - mail.mailinator.com
          - mail2.mailinator.com
          description: The mail servers, best first.
        is_known_spammer:
          type: boolean
          description: This exact address was reported for spam or abuse.
        reason:
          type: string
          description: One sentence a person can read, explaining the answer.
        email_type:
          type: string
          enum:
          - temp
          - alias
          - normal
          - invalid
          description: temp (throwaway inbox), alias (forwarding address, unlimited per person), normal or invalid.
        blocked:
          type: boolean
          description: 'Keyed calls only: whether the account refuses this address, from its own allow and block lists first, then its dashboard switches. An invalid address is always blocked.'
        allowlisted:
          type: boolean
          description: 'Keyed calls only: the domain, or one above it, is on the account''s allow list.'
        blocklisted:
          type: boolean
          description: 'Keyed calls only: the domain, or one above it, is on the account''s block list.'
        community_blacklisted:
          type: boolean
        blacklist_reports:
          type: integer
        blacklist_reasons:
          type: array
          items:
            type: string
    EmailCheckRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          example: test@mailinator.com
    BatchEmailResponse:
      type: object
      properties:
        request_id:
          type: string
          example: req_1a186b7a91c40f2e8d3b5a6
        results:
          type: array
          items:
            $ref: '#/components/schemas/EmailResponse'
          description: One result per address, in the order sent.
        total:
          type: integer
          example: 2
    EmailListRequest:
      type: object
      required:
      - list
      properties:
        list:
          type: string
          enum:
          - allow
          - block
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error_code:
          type: integer
          example: 1002
        error:
          type: string
          example: INVALID_API_KEY
        message:
          type: string
          example: The API key provided is not valid.
    EmailLists:
      type: object
      properties:
        allow:
          type: array
          items:
            type: string
          example:
          - partner.com
        block:
          type: array
          items:
            type: string
          example:
          - unwanted-domain.com
        limit:
          type: integer
          example: 1000
          description: Entries one account may hold across both lists.
    BatchEmailRequest:
      type: object
      required:
      - emails
      properties:
        emails:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
          example:
          - jane@gmail.com
          - jane@passmail.com
    EmailReportResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        email:
          type: string
          example: scammer@example.org
        total_reports:
          type: integer
          example: 3
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your FFraud API key (ff_live_...). Create one free at https://ffraud.com/register .
    AbuseIpdbKey:
      type: apiKey
      in: header
      name: Key
      description: Your FFraud API key, sent in AbuseIPDB's `Key` header for the compatibility endpoint.
    IpinfoToken:
      type: apiKey
      in: query
      name: token
      description: Your FFraud API key, sent as ipinfo's `token` query param.
externalDocs:
  description: Full docs
  url: https://ffraud.com/docs