openapi: 3.0.0
info:
  title: api.emaildetective.io API
  description: |-
    EmailDetective.io is an API focusing on validating email addresses and providing a score based off how suspicious an email address is.

    To get started register a new user (make sure to verify your email) and then you can can start getting email information.

  termsOfService: http://emaildetective.io/terms
  contact:
    url: https://emaildetective.io/contact
  version: 1.0.0
externalDocs:
  description: Find out more about emaildetective.io
  url: https://emaildetective.io
servers:
- url: https://api.emaildetective.io
tags:
- name: email info
  description: Email information endpoints

paths:
  /emails/{emailAddress}:
    get:
      tags:
      - email info
      operationId: getEmailAddressInfo
      x-roles:
      - user
      - admin
      summary: Get information and legitimacy score for an email address
      parameters:
      - name: emailAddress
        in: path
        description: email address
        required: true
        schema:
          type: string
      description: |-
        Get information about an email address.

        - `email`: The email address being validated. Example: `"user123@example.com"`.
        - `user`: The user portion of the email address, which is everything before the "@" symbol. Example: `"user123"`.
        - `domain`: The domain portion of the email address, which is everything after the "@" symbol. Example: `"example.com"`.
        - `valid_email`: Indicates whether the email address format is valid. Example: `true`.
        - `valid_spf`: Indicates whether the email domain has a valid SPF (Sender Policy Framework) record. Example: `true`.
        - `valid_dmarc`: Indicates whether the email domain has a valid DMARC (Domain-based Message Authentication, Reporting & Conformance) record. Example: `true`.
        - `valid_mx`: Indicates whether the email domain has valid MX (Mail Exchange) records. Example: `true`.
        - `valid_tld`: If the TLD (Top Level Domain) specified in the email is valid. A TLD is .com, .org, .net, etc
        - `nonsense`: Flags whether the email is nonsensical or randomly generated. Example: `false`.
        - `role`: Indicates whether the email address is associated with a role (e.g., `admin@example.com`). Example: `false`.
        - `free`: Indicates whether the email is from a free email provider (e.g., Gmail, Yahoo). Example: `true`.
        - `disposable`: Indicates whether the email address is from a disposable email service. Example: `false`.
        - `score`: The total score of the email address. The lower the score the more likely the email address is suspicious or not valid. This is is an integer between 0 and 100. An example of a suspicous score would be 35, an example of a non-suspicous score would be 85.
        - `suspicion_rating`: The rating of the email address. Valid value are HIGH, MEDIUM, LOW.
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailInfoResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/400ErrorResponse"
        "401":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/401ErrorResponse"
        "429":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/429ErrorResponse"
        "500":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/500ErrorResponse"
      security:
      - api_key: []
  /emails:
    post:
      tags:
      - email info
      operationId: getBulkEmailAddressInfo
      x-roles:
      - user
      - admin
      summary: Get information and legitimacy score for many email address
      description: |-
        Get information about many email address.

        - `email`: The email address being validated. Example: `"user123@example.com"`.
        - `user`: The user portion of the email address, which is everything before the "@" symbol. Example: `"user123"`.
        - `domain`: The domain portion of the email address, which is everything after the "@" symbol. Example: `"example.com"`.
        - `valid_email`: Indicates whether the email address format is valid. Example: `true`.
        - `valid_spf`: Indicates whether the email domain has a valid SPF (Sender Policy Framework) record. Example: `true`.
        - `valid_dmarc`: Indicates whether the email domain has a valid DMARC (Domain-based Message Authentication, Reporting & Conformance) record. Example: `true`.
        - `valid_mx`: Indicates whether the email domain has valid MX (Mail Exchange) records. Example: `true`.
        - `valid_tld`: If the TLD (Top Level Domain) specified in the email is valid. A TLD is .com, .org, .net, etc
        - `nonsense`: Flags whether the email is nonsensical or randomly generated. Example: `false`.
        - `role`: Indicates whether the email address is associated with a role (e.g., `admin@example.com`). Example: `false`.
        - `free`: Indicates whether the email is from a free email provider (e.g., Gmail, Yahoo). Example: `true`.
        - `disposable`: Indicates whether the email address is from a disposable email service. Example: `false`.
        - `score`: The total score of the email address. The lower the score the more likely the email address is suspicious or not valid. This is is an integer between 0 and 100. An example of a suspicous score would be 35, an example of a non-suspicous score would be 85.
        - `suspicion_rating`: The rating of the email address. Valid value are HIGH, MEDIUM, LOW.
      requestBody:
        description: Request of the email addresses to get info about
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkEmailInfoRequest"
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkEmailInfoResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/400ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/401ErrorResponse"
        "429":
          description: Reached request limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/429ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/500ErrorResponse"
      security:
      - api_key: []
  /emails/csv:
    post:
      tags:
      - email info
      operationId: getEmailCSV
      x-roles:
      - user
      - admin
      summary: Get information and legitimacy score for many email addresses and return
        via CSV
      description: |-
        **The provided file must have one email per line, currently CSV and plain text are the only supported file types**

        Get information about many email address.

        - `email`: The email address being validated. Example: `"user123@example.com"`.
        - `user`: The user portion of the email address, which is everything before the "@" symbol. Example: `"user123"`.
        - `domain`: The domain portion of the email address, which is everything after the "@" symbol. Example: `"example.com"`.
        - `valid_email`: Indicates whether the email address format is valid. Example: `true`.
        - `valid_spf`: Indicates whether the email domain has a valid SPF (Sender Policy Framework) record. Example: `true`.
        - `valid_dmarc`: Indicates whether the email domain has a valid DMARC (Domain-based Message Authentication, Reporting & Conformance) record. Example: `true`.
        - `valid_mx`: Indicates whether the email domain has valid MX (Mail Exchange) records. Example: `true`.
        - `valid_tld`: If the TLD (Top Level Domain) specified in the email is valid. A TLD is .com, .org, .net, etc
        - `nonsense`: Flags whether the email is nonsensical or randomly generated. Example: `false`.
        - `role`: Indicates whether the email address is associated with a role (e.g., `admin@example.com`). Example: `false`.
        - `free`: Indicates whether the email is from a free email provider (e.g., Gmail, Yahoo). Example: `true`.
        - `disposable`: Indicates whether the email address is from a disposable email service. Example: `false`.
        - `score`: The total score of the email address. The lower the score the more likely the email address is suspicious or not valid. This is is an integer between 0 and 100. An example of a suspicous score would be 35, an example of a non-suspicous score would be 85.
        - `suspicion_rating`: The rating of the email address. Valid value are HIGH, MEDIUM, LOW.
      requestBody:
        description: Request of the email addresses to get info about
        content:
          application/octet-stream:
            schema:
              type: string
              format: csv
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            text/csv:
              schema:
                type: string
                format: csv
                example: |-
                  email,user,domain,valid_email,valid_spf,valid_dmarc,valid_mx,valid_tld,nonsense,role,free,disposable,score,suspicion_rating
                  example1@example.com,example1,example.com,true,true,true,true,true,false,false,true,false,95,LOW

        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/400ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/401ErrorResponse"
        "429":
          description: Reached request limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/429ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/500ErrorResponse"
      security:
      - api_key: []
  /emails/draft:
    post:
      tags:
      - email info
      summary: "Generate a drafted email"
      description: "Creates a subject and body based on the provided details."
      operationId: "draftEmail"
      x-roles:
      - user
      - admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailDraftRequest"
      responses:
        "200":
          description: "Successfully generated email draft."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailDraftResponse"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/400ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/401ErrorResponse"
        "429":
          description: Reached request limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/429ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/500ErrorResponse"
      security:
      - api_key: []
components:
  schemas:
    BulkEmailInfoRequest:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: string
      example:
        data:
        - "example1@example.com"
        - "example2@example.com"

    BulkEmailInfoResponse:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/EmailInfoResponse"

    EmailInfoResponse:
      type: object
      required:
      - email
      - user
      - domain
      - first_name
      - last_name
      - did_you_mean
      - valid_spf
      - valid_dmarc
      - valid_email
      - valid_mx
      - valid_tld
      - nonsense
      - role
      - free
      - disposable
      - score
      - suspicion_rating
      properties:
        email:
          type: string
          example: "john.smith@example.cm"
          x-order: 1
        user:
          type: string
          example: "john.smith"
          x-order: 2
        domain:
          type: string
          example: "exmple.cm"
          x-order: 3
        did_you_mean:
          type: string
          example: "john.smith@example.com"
          x-order: 4
        first_name:
          type: string
          example: "John"
          x-order: 5
        last_name:
          type: string
          example: "Smith"
          x-order: 6
        valid_email:
          type: boolean
          example: true
          x-order: 7
        valid_spf:
          type: boolean
          example: true
          x-order: 8
        valid_dmarc:
          type: boolean
          example: true
          x-order: 9
        valid_mx:
          type: boolean
          example: true
          x-order: 10
        valid_tld:
          type: boolean
          example: true
          x-order: 11
        nonsense:
          type: boolean
          example: false
          x-order: 12
        role:
          type: boolean
          example: false
          x-order: 13
        free:
          type: boolean
          example: true
          x-order: 14
        disposable:
          type: boolean
          example: false
          x-order: 15
        score:
          type: integer
          example: 65
          x-order: 16
        suspicion_rating:
          type: string
          example: LOW
          x-order: 17

    EmailDraftRequest:
      type: object
      required:
      - sender
      - recipient
      - reason
      - focus
      properties:
        sender:
          type: string
          format: email
          description: "The email address of the sender."
        recipient:
          type: string
          format: email
          description: "The email address of the recipient."
        reason:
          type: string
          description: "The reason for sending the email."
        focus:
          type: string
          description: "Focus the generated email."

    EmailDraftResponse:
      type: object
      required:
      - subject
      - body
      properties:
        subject:
          type: string
          description: "The generated subject of the email."
          x-order: 1
        body:
          type: string
          description: "The generated body of the email."
          x-order: 2

    400ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: "Invalid field or body"

    401ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: "unauthorized"

    404ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: "Resource cannot be found"

    429ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: "ran out of credits"

    500ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: "Internal server has occured"

  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header