Anymail Finder Find Email API

openapi: 3.2.0
info:
  title: Anymail finder Find Email API
  description: ''
  version: '5.1'
  contact: {}
servers:
- url: https://api.anymailfinder.com
tags:
- name: find-email
paths:
  /v5.1/find-email/company:
    post:
      description: Retrieves emails associated with a given domain or company name. At least one parameter among "company_name" or "domain" is required. For better results, we recommend using the company website (domain) instead of the company name.
      operationId: company
      parameters:
      - name: x-webhook-url
        in: header
        description: If provided, the result will be POSTed to this URL instead of waiting for the response.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api51FindEmailCompanyBodyDto'
      responses:
        '200':
          description: Emails found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51FindEmailCompanyResponseSuccessDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '402':
          description: Upgrade needed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
      security:
      - api_key: []
      summary: Search for company emails based on company details
      tags:
      - find-email
  /v5.1/find-email/decision-maker:
    post:
      description: Find the details and emails of a decision maker of a specific category at a company. This search requires either "company_name" or "domain" to identify the company, and the "decision_maker_category".
      operationId: decisionMaker
      parameters:
      - name: x-webhook-url
        in: header
        description: If provided, the result will be POSTed to this URL instead of waiting for the response.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api51FindEmailDecisionMakerBodyDto'
      responses:
        '200':
          description: Email found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51FindEmailDecisionMakerResponseSuccessDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '402':
          description: Upgrade needed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
      security:
      - api_key: []
      summary: Search for a decision maker email based on company and category
      tags:
      - find-email
  /v5.1/find-email/linkedin-url:
    post:
      description: Retrieves a specific person's email within a company by providing a LinkedIn profile URL. This search requires just the "linkedin_url".
      operationId: linkedinUrl
      parameters:
      - name: x-webhook-url
        in: header
        description: If provided, the result will be POSTed to this URL instead of waiting for the response.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api51FindEmailLinkedinUrlBodyDto'
      responses:
        '200':
          description: Email found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51FindEmailLinkedinUrlResponseSuccessDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '402':
          description: Upgrade needed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
      security:
      - api_key: []
      summary: Search for a person's email based on a LinkedIn profile URL
      tags:
      - find-email
  /v5.1/find-email/person:
    post:
      description: Retrieves a specific person's email within a company. This search requires either "company_name" or "domain" to identify the company, and the person's name provided as "full_name" or both "first_name" and "last_name". For better results, we recommend using the company website (domain) instead of the company name. A "linkedin_url" can be sent on its own, in which case company and name are not needed.
      operationId: person
      parameters:
      - name: x-webhook-url
        in: header
        description: If provided, the result will be POSTed to this URL instead of waiting for the response.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api51FindEmailPersonBodyDto'
      responses:
        '200':
          description: Email found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51FindEmailPersonResponseSuccessDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
        '402':
          description: Upgrade needed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api51ErrorResponseDto'
      security:
      - api_key: []
      summary: Search for a person's email based on company and personal details
      tags:
      - find-email
components:
  schemas:
    Api51FindEmailCompanyResponseSuccessDto:
      type: object
      properties:
        input:
          type: object
          description: Your request original input.
        credits_charged:
          type: number
          description: Number of credits charged for this request.
        email_status:
          enum:
          - valid
          - not_found
          - blacklisted
          type: string
          description: 'The email status. One of the following: valid, not_found, blacklisted.'
          example: valid
        emails:
          description: An array containing up to 20 email addresses found for the specified company.
          example:
          - joedelia@hundo.io
          - help@hundo.io
          type: array
          items:
            type: string
        mx_domain:
          type:
          - string
          - 'null'
          description: The root domain of the MX hostname, e.g. google.com or outlook.com. null when mx_host is null.
          example: google.com
        mx_host:
          type:
          - string
          - 'null'
          description: The domain's primary MX hostname, or null if no email was found.
          example: aspmx.l.google.com
        valid_emails:
          description: An array containing up to 20 email addresses found for the company, only when email_status is valid. Otherwise, this array is empty.
          example:
          - joedelia@hundo.io
          - help@hundo.io
          type: array
          items:
            type: string
      required:
      - input
      - credits_charged
      - email_status
      - emails
      - mx_domain
      - mx_host
      - valid_emails
    Api51FindEmailLinkedinUrlResponseSuccessDto:
      type: object
      properties:
        input:
          type: object
          description: Your request original input.
        credits_charged:
          type: number
          description: Number of credits charged for this request.
        email:
          type:
          - string
          - 'null'
          description: The email found, or null if not found.
          example: satyan@microsoft.com
        email_status:
          enum:
          - valid
          - not_found
          - blacklisted
          type: string
          description: 'The email status. One of the following: valid, not_found, blacklisted.'
          example: valid
        mx_domain:
          type:
          - string
          - 'null'
          description: The root domain of the MX hostname, e.g. google.com or outlook.com. null when mx_host is null.
          example: google.com
        mx_host:
          type:
          - string
          - 'null'
          description: The domain's primary MX hostname, or null if no email was found.
          example: aspmx.l.google.com
        person_company_name:
          type:
          - string
          - 'null'
          description: The person's company name.
          example: Microsoft
        person_full_name:
          type:
          - string
          - 'null'
          description: The full name of the person.
          example: Satya Nadella
        person_job_title:
          type:
          - string
          - 'null'
          description: The job title of the person.
          example: Chairman and CEO
        valid_email:
          type:
          - string
          - 'null'
          description: The email only when email_status is valid. Otherwise null.
          example: satyan@microsoft.com
      required:
      - input
      - credits_charged
      - email
      - email_status
      - mx_domain
      - mx_host
      - person_company_name
      - person_full_name
      - person_job_title
      - valid_email
    Api51FindEmailCompanyBodyDto:
      type: object
      properties:
        company_name:
          type: string
          description: The company name (providing the domain is recommended for better accuracy).
        domain:
          type: string
          description: The domain of the company to search for emails.
        email_type:
          enum:
          - any
          - generic
          - personal
          type: string
          description: Specifies which type of email addresses to return in the results.
    Api51FindEmailDecisionMakerResponseSuccessDto:
      type: object
      properties:
        input:
          type: object
          description: Your request original input.
        credits_charged:
          type: number
          description: Number of credits charged for this request.
        decision_maker_category:
          type:
          - string
          - 'null'
          description: The decision maker category that matched, or null if not found.
          example: ceo
        email:
          type:
          - string
          - 'null'
          description: The email found, or null if not found.
          example: satyan@microsoft.com
        email_status:
          enum:
          - valid
          - not_found
          - blacklisted
          type: string
          description: 'The email status. One of the following: valid, not_found, blacklisted.'
          example: valid
        mx_domain:
          type:
          - string
          - 'null'
          description: The root domain of the MX hostname, e.g. google.com or outlook.com. null when mx_host is null.
          example: google.com
        mx_host:
          type:
          - string
          - 'null'
          description: The domain's primary MX hostname, or null if no email was found.
          example: aspmx.l.google.com
        person_first_name:
          type:
          - string
          - 'null'
          description: The decision maker's first (given) name. Null when the full name could not be confidently split into first and last name.
          example: Satya
        person_full_name:
          type:
          - string
          - 'null'
          description: The full name of the decision maker.
          example: Satya Nadella
        person_job_title:
          type:
          - string
          - 'null'
          description: The job title of the decision maker.
          example: Chairman and CEO
        person_last_name:
          type:
          - string
          - 'null'
          description: The decision maker's last (family) name. Null when the full name could not be confidently split into first and last name.
          example: Nadella
        person_linkedin_url:
          type:
          - string
          - 'null'
          description: The LinkedIn profile URL of the decision maker, if available.
          example: https://www.linkedin.com/in/satyanadella/
        valid_email:
          type:
          - string
          - 'null'
          description: The email only when email_status is valid. Otherwise null.
          example: satyan@microsoft.com
      required:
      - input
      - credits_charged
      - decision_maker_category
      - email
      - email_status
      - mx_domain
      - mx_host
      - person_first_name
      - person_full_name
      - person_job_title
      - person_last_name
      - person_linkedin_url
      - valid_email
    Api51ErrorResponseDto:
      type: object
      properties:
        error:
          type: string
          description: Error code
          example: no_result
        message:
          type: string
          description: Detailed explanation of the error
          example: We could not find an email for this person. Sorry.
      required:
      - error
      - message
    Api51FindEmailPersonBodyDto:
      type: object
      properties:
        company_name:
          type: string
          description: Used if domain is not provided.
        domain:
          type: string
          description: Preferred. The company domain.
        first_name:
          type: string
          description: First name of the person.
        full_name:
          type: string
          description: Alternative to first+last name.
        last_name:
          type: string
          description: Last name of the person.
        linkedin_url:
          type: string
          description: Optional LinkedIn profile URL. It can be sent on its own, without company and name. When a name and company are also provided, the profile is used to refine the supplied name (e.g. extending 'John D.' to 'John Doe'), and is used as a fallback if the name+company lookup doesn't return a verified email. The result may be at a different company/domain if the person has moved.
          example: https://www.linkedin.com/in/satyanadella/
    Api51FindEmailLinkedinUrlBodyDto:
      type: object
      properties:
        linkedin_url:
          type: string
          description: The LinkedIn profile URL of the person.
          example: https://www.linkedin.com/in/satyanadella/
      required:
      - linkedin_url
    Api51FindEmailPersonResponseSuccessDto:
      type: object
      properties:
        input:
          type: object
          description: Your request original input.
        credits_charged:
          type: number
          description: Number of credits charged for this request.
        email:
          type:
          - string
          - 'null'
          description: The email found, or null if not found.
          example: satyan@microsoft.com
        email_status:
          enum:
          - valid
          - not_found
          - blacklisted
          type: string
          description: 'The email status. One of the following: valid, not_found, blacklisted.'
          example: valid
        mx_domain:
          type:
          - string
          - 'null'
          description: The root domain of the MX hostname, e.g. google.com or outlook.com. null when mx_host is null.
          example: google.com
        mx_host:
          type:
          - string
          - 'null'
          description: The domain's primary MX hostname, or null if no email was found.
          example: aspmx.l.google.com
        person_company_name:
          type:
          - string
          - 'null'
          description: Name of the company at which the returned email lives. Populated when email_status is valid, otherwise null.
          example: Microsoft
        person_full_name:
          type:
          - string
          - 'null'
          description: Full name of the person we found the email for. May reflect a LinkedIn-extended version of the supplied name. Populated when email_status is valid, otherwise null.
          example: Satya Nadella
        person_job_title:
          type:
          - string
          - 'null'
          description: Job title of the person, sourced from LinkedIn. Populated when email_status is valid AND a LinkedIn URL was provided whose profile we successfully fetched. Otherwise null.
          example: Chairman and CEO
        valid_email:
          type:
          - string
          - 'null'
          description: The email only when email_status is valid. Otherwise null.
          example: satyan@microsoft.com
      required:
      - input
      - credits_charged
      - email
      - email_status
      - mx_domain
      - mx_host
      - person_company_name
      - person_full_name
      - person_job_title
      - valid_email
    Api51FindEmailDecisionMakerBodyDto:
      type: object
      properties:
        company_name:
          type: string
          description: Used if domain is not provided.
        decision_maker_category:
          maxItems: 5
          description: 'The category of the decision maker to search for. One or more of the following: "ceo", "engineering", "finance", "hr", "it", "logistics", "marketing", "operations", "buyer", "sales".'
          type: array
          items:
            type: string
        domain:
          type: string
          description: Preferred. The company domain.
      required:
      - decision_maker_category
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: Authorization