openapi: 3.0.3
info:
  title: Check by MailnJoy - API Partenaire - Unitary Validation
  description: Cette page présente la documentation de l'API permettant de valider
    des mails unitairement.
  termsOfService: https://developer.mailnjoy.com/terms/
  contact:
    url: https://developer.mailnjoy.com/faq/
    email: contact-developer@mailnjoy.com
  license:
    name: Consulter la licence
    url: https://mit-license.org
  version: 2.0.0
externalDocs:
  description: Accèder au GitHub de l'API
  url: https://github.com/mailnjoy/check-api
servers:
- url: https://api.mailnjoy.com
security:
- apiId: []
  apiSecret: []
tags:
- name: unitary
  description: La validation d'un seul mail
paths:
  /v2/unitary:
    post:
      tags:
      - unitary
      description: Valide une unique adresse mail. L'appel prend quelques secondes
      operationId: validateOneV2
      parameters:
      - name: type
        in: query
        description: "Le type de validation, simple ou appronfondie. Le type du retour\
          \ dépendra de l'option selectionnée"
        required: true
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/ValidationType'
      requestBody:
        description: Le mail à valider
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/Email'
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponseV2'
              examples:
                simple:
                  summary: a simple validation result example
                  value:
                    id: 564
                    email: foo@bar.com
                    created: 2020-02-29T18:02:42.847+0000
                    validated: 2020-02-29T18:02:46.906+0000
                    validationType: simple
                    userId: 12
                    status: VALID
                    category: SAFE
                    attributs:
                      alias:
                        type: negative
                        value: false
                      free:
                        type: neutral
                        value: false
                      autogenerated:
                        type: negative
                        value: false
                      catchall:
                        type: negative
                        value: true
                      disposable:
                        type: negative
                        value: false
                      protected:
                        type: negative
                        value: false
                      role:
                        type: negative
                        value: false
                      spamtrap:
                        type: negative
                        value: false
                      suspect:
                        type: negative
                        value: false
                deep:
                  summary: a deep validation result example
                  value:
                    id: 56
                    email: foo@bar.com
                    created: 2020-02-29T18:02:48.847+0000
                    validated: 2020-02-29T18:02:57.906+0000
                    validationType: deep
                    userId: 12
                    status: VALID
                    category: VERY_SAFE
                    attributs:
                      alias:
                        type: negative
                        value: false
                      free:
                        type: neutral
                        value: false
                      autogenerated:
                        type: negative
                        value: false
                      catchall:
                        type: negative
                        value: true
                      disposable:
                        type: negative
                        value: false
                      protected:
                        type: negative
                        value: false
                      role:
                        type: negative
                        value: false
                      spamtrap:
                        type: negative
                        value: false
                      suspect:
                        type: negative
                        value: false
                    extras:
                      socialMedia:
                        type: positive
                        value: false
                      marketingPlateform:
                        type: positive
                        value: true
                      breachList:
                        type: negative
                        value: true
                      fraudList:
                        type: negative
                        value: false
                      blacklisted:
                        type: negative
                        value: false
                      young:
                        type: negative
                        value: false
                    score:
                      result: 8.4
                      total: 10.0
        "400":
          description: Le paramétre n'est pas un mail valide ou le type spécifié est
            incorrect
        "401":
          description: Le couple id/secret est absent ou incorrect
        "403":
          description: Pas assez de crédit pour lancer la validation
        "500":
          description: Erreur serveur
        "503":
          description: Indisponibilité temporaire du service
  /v1/unitary:
    post:
      tags:
      - unitary
      description: Valide une unique adresse mail. L'appel prend quelques secondes
      operationId: validateOne
      parameters:
      - name: type
        in: query
        description: "Le type de validation, simple ou appronfondie. Le type du retour\
          \ dépendra de l'option selectionnée"
        required: true
        style: form
        explode: true
        schema:
          $ref: '#/components/schemas/ValidationType'
      requestBody:
        description: Le mail à valider
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/Email'
        required: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponseV1'
              examples:
                simple:
                  summary: a simple validation result example
                  value:
                    id: 564
                    email: foo@bar.com
                    created: 2020-02-29T18:02:42.847+0000
                    validated: 2020-02-29T18:02:46.906+0000
                    validationType: simple
                    userId: 12
                    status: VALID
                    category: SAFE
                    attributs:
                      alias:
                        type: negative
                        value: false
                      free:
                        type: neutral
                        value: false
                      autogenerated:
                        type: negative
                        value: false
                      catchall:
                        type: negative
                        value: true
                      disposable:
                        type: negative
                        value: false
                      role:
                        type: negative
                        value: false
                      spamtrap:
                        type: negative
                        value: false
                deep:
                  summary: a deep validation result example
                  value:
                    id: 56
                    email: foo@bar.com
                    created: 2020-02-29T18:02:48.847+0000
                    validated: 2020-02-29T18:02:57.906+0000
                    validationType: deep
                    userId: 12
                    status: VALID
                    category: VERY_SAFE
                    attributs:
                      alias:
                        type: negative
                        value: false
                      free:
                        type: neutral
                        value: false
                      autogenerated:
                        type: negative
                        value: false
                      catchall:
                        type: negative
                        value: true
                      disposable:
                        type: negative
                        value: false
                      role:
                        type: negative
                        value: false
                      spamtrap:
                        type: negative
                        value: false
                    extras:
                      socialMedia:
                        type: positive
                        value: false
                      marketingPlateform:
                        type: positive
                        value: true
                      breachList:
                        type: negative
                        value: true
                      fraudList:
                        type: negative
                        value: false
                      blacklisted:
                        type: negative
                        value: false
                      young:
                        type: negative
                        value: false
                      suspect:
                        type: negative
                        value: false
                    score:
                      result: 8.4
                      total: 10.0
        "400":
          description: Le paramétre n'est pas un mail valide ou le type spécifié est
            incorrect
        "401":
          description: Le couple id/secret est absent ou incorrect
        "403":
          description: Pas assez de crédit pour lancer la validation
        "500":
          description: Erreur serveur et/ou indisponibilité temporaire du service
  /v1/credit:
    get:
      description: Retourne le solde de crédits du compte
      operationId: getCredits
      responses:
        "200":
          description: Le solde du compte
          content:
            text/plain:
              schema:
                type: string
                example: "217403"
        "500":
          description: Erreur serveur et/ou indisponibilité temporaire du service
components:
  schemas:
    Email:
      type: string
      description: Une adresse email classique
      example: john.doe@company.com
    ValidationResponseV1:
      description: Le résultat d'une validation unitaire
      discriminator:
        propertyName: validationType
        mapping:
          SIMPLE: '#/components/schemas/ValidationSimpleV1'
          DEEP: '#/components/schemas/ValidationDeepV1'
      oneOf:
      - $ref: '#/components/schemas/ValidationSimpleV1'
      - $ref: '#/components/schemas/ValidationDeepV1'
    ValidationSimpleV1:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 564
        email:
          type: string
          description: l'email validé
          readOnly: true
          example: foo@bar.com
        created:
          type: string
          description: "Datetime de création de la validation, au format ISO 8601"
          readOnly: true
          example: 2020-02-29T18:02:42.847+0000
        validated:
          type: string
          description: "Datetime de fin de la validation, au format ISO 8601"
          readOnly: true
          example: 2020-02-29T18:02:46.906+0000
        validationType:
          $ref: '#/components/schemas/ValidationType'
        userId:
          type: integer
          description: "L'utilisateur qui a lancé la validation, ici le compte de\
            \ développement"
          readOnly: true
          example: 12
        status:
          $ref: '#/components/schemas/Status'
        category:
          $ref: '#/components/schemas/Category'
        attributs:
          $ref: '#/components/schemas/AttributsV1'
      description: Le résultat d'une validation unitaire simple
    ValidationDeepV1:
      allOf:
      - $ref: '#/components/schemas/ValidationSimpleV1'
      - type: object
        properties:
          extras:
            $ref: '#/components/schemas/ExtrasV1'
          score:
            $ref: '#/components/schemas/Score'
        description: Le résultat d'une validation unitaire approfondie3
    ValidationResponseV2:
      description: Le résultat d'une validation unitaire
      discriminator:
        propertyName: validationType
        mapping:
          SIMPLE: '#/components/schemas/ValidationSimpleV2'
          DEEP: '#/components/schemas/ValidationDeepV2'
      oneOf:
      - $ref: '#/components/schemas/ValidationSimpleV1'
      - $ref: '#/components/schemas/ValidationDeepV2'
    ValidationSimpleV2:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          example: 564
        email:
          type: string
          description: l'email validé
          readOnly: true
          example: foo@bar.com
        created:
          type: string
          description: "Datetime de création de la validation, au format ISO 8601"
          readOnly: true
          example: 2020-02-29T18:02:42.847+0000
        validated:
          type: string
          description: "Datetime de fin de la validation, au format ISO 8601"
          readOnly: true
          example: 2020-02-29T18:02:46.906+0000
        validationType:
          $ref: '#/components/schemas/ValidationType'
        userId:
          type: integer
          description: "L'utilisateur qui a lancé la validation, ici le compte de\
            \ développement"
          readOnly: true
          example: 12
        status:
          $ref: '#/components/schemas/Status'
        category:
          $ref: '#/components/schemas/Category'
        attributs:
          $ref: '#/components/schemas/AttributsV2'
      description: Le résultat d'une validation unitaire simple
    ValidationDeepV2:
      allOf:
      - $ref: '#/components/schemas/ValidationSimpleV2'
      - type: object
        properties:
          extras:
            $ref: '#/components/schemas/ExtrasV2'
          score:
            $ref: '#/components/schemas/Score'
        description: Le résultat d'une validation unitaire approfondie
    ValidationType:
      type: string
      description: Le niveau de détail de la validation. Le coût varie selon le type
        de validation.
      enum:
      - SIMPLE
      - simple
      - DEEP
      - deep
    Status:
      type: string
      description: La classification globale de l'adresse
      enum:
      - VALID
      - INVALID
      - INCORRECT
      - SUSPECT
      - FULL
    Category:
      type: string
      description: Le niveau de confiance attribuable à l'adresse
      enum:
      - VERY_SAFE
      - SAFE
      - RISKY
      - UNSAFE
    AttributsV1:
      type: object
      properties:
        alias:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est un alias
        free:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse provient d'un domaine email gratuit
        autogenerated:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est chaîne générée automatiquement
        catchall:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse provient d'un domaine catchall
        disposable:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est jetable
        role:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: "Est-ce que l'adresse est un rôle (contact, sales, ...)"
        spamtrap:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est un spamtrap
      description: Les caractéristiques technique de l'adresse email validée
    ExtrasV1:
      type: object
      properties:
        socialMedia:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse a une présence sur les media sociaux
        marketingPlateform:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse a une présence sur des plateforme de
              vente en ligne
        breachList:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur une liste ayant fuitée publiquement
        fraudList:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur une liste d\'adresses déclarés
              frauduleuses
        blacklisted:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur un domaine dangeureux
        young:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur un domaine récent
        suspect:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur un domaine suspect
      description: "Les attributs supplémentaires, liés à la validation approfondie"
    AttributsV2:
      type: object
      properties:
        alias:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est un alias
        free:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse provient d'un domaine email gratuit
        autogenerated:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est chaîne générée automatiquement
        catchall:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse provient d\'un domaine catchall
        disposable:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est jetable
        protected:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur un domaine protégé
        role:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: "Est-ce que l'adresse est un rôle (contact, sales, ...)"
        spamtrap:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est un spamtrap
        suspect:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur un domaine suspect
      description: Les caractéristiques technique de l'adresse email validée
    ExtrasV2:
      type: object
      properties:
        socialMedia:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse a une présence sur les media sociaux
        marketingPlateform:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse a une présence sur des plateforme de
              vente en ligne
        breachList:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur une liste ayant fuitée publiquement
        fraudList:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur une liste d\'adresses déclarés
              frauduleuses
        blacklisted:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur un domaine dangeureux
        young:
          allOf:
          - $ref: '#/components/schemas/Attribut'
          - description: Est-ce que l'adresse est sur un domaine récent
      description: "Les attributs supplémentaires, liés à la validation approfondie"
    Score:
      type: object
      properties:
        result:
          type: number
          description: Le score de l'adresse
          format: float
          readOnly: true
          example: 7.8
        total:
          type: number
          description: Le score maximal que peut atteindre l'adresse
          format: float
          readOnly: true
          example: 10.0
      description: La note de confiance attribuée à l'adresse email
      readOnly: true
    Attribut:
      type: object
      properties:
        type:
          type: string
          description: "Indique si l'attribut est une caractéristique recherchée (POSITIVE),\
            \ à éviter (NEGATIVE) ou apportant juste une information (NEUTRAL)"
          readOnly: true
          enum:
          - positive
          - neutral
          - negative
        value:
          type: boolean
          description: Indique sur l'adresse email posséde l'attribut (true) ou non
            (false)
          readOnly: true
      description: Une caratéristique d'un email
  securitySchemes:
    apiId:
      type: apiKey
      name: mailnjoy-id
      in: header
    apiSecret:
      type: apiKey
      name: mailnjoy-secret
      in: header