Fiddlemail API

API

Description

This is the REST API of fiddlemail.com. It can be used to get information about fake emails and fake sms numbers.

You can get a sample PHP class and a sample PHP script to show basic API usage here.

Authentication

The authentication is done by your secret API key. Please check this page if you don't have an API key, yet.

The API key is embedded in the URI of each API request. I. e.:

/{your_api_key}/email/{address_to_check}

This applies for all request methods (GET and POST).

API endpoints

The base URI for the fiddlemail.com API is:

Live system: https://fiddlemail.com/api/v1

You can see the full URI to use for the different API methods below.

Please contact info@mogelmail.de if you need further information.

Request format

All request parameters besides the number/email address to check are passed via JSON. Which parameters can be used is stated at the corresponding API section below.

Response format

The API returns a HTTP status code and json a object in the response body. The json object (if existent) always contains an 'error' attribute.

{
  "error": true,
  "message": "TYPE_OF_ERROR",
  "information": "...",
  ...
}

The attribute 'error' is set to true if something was wrong with your call. Please be aware that the API also uses HTTP error status codes, so you will have to evaluate the json response on '400', '403' and '404' status codes, too.

If the 'error' attribute is true, you will get one or more further attributes:

General error typesshow

  • string

    Here you get the type of error that occurred. Specific error types for the different API methods are explained below. These are the general error codes:

  • MISSING_HTTP_METHOD

    Our server could not read the HTTP method (GET, POST) that you sent.

  • INVALID_HTTP_METHOD

    You did not send a valid HTTP method (GET, POST).

  • UNSUPPORTED_METHOD

    The HTTP method you used is not supported by this endpoint.

  • MISSING_REQUEST_URI

    The API URI that you called is not valid.

  • INVALID_API_VERSION

    The API version you set is unsupported.

  • MISSING_API_METHOD

    The API URI you called did not contain any valid endpoint.

  • MISSING_QUERY

    The API URI you called did not contain any query for a phone number or email address.

  • UNKNOWN_API_METHOD

    The API URI you called contains an endpoint that is not known to the system.

  • MISSING_API_KEY

    You did not provide your API auth key in the request.

  • INVALID_API_KEY

    You did provide an invalid API auth key in the request.

  • EXPIRED_API_KEY

    You did provide an expired API auth key in the request.

  • IP_RESTRICTED

    This key is not valid for the ip you used.

  • RATE_LIMIT_EXCEEDED

    You have made more requests in a specific amount of time than you are allowed to. Please check the information field for further data.

  • MISSING_JSON_DATA

    The method you called require a JSON object in the request body, but it was missing.

  • INVALID_JSON_DATA

    The JSON data in your request body could not be decoded.

  • INVALID_REQUEST

    The request you sent could not be understand.

  • API_CALL_FAILED

    The API call failed for an unknown reason. If this persists please contact the support.

  • string

    If there are further information regarding the error, these are conained in this attribute. For example this can be the value you submitted causing the error or information about your rate limits.

Fake Emails

Description

This is the emails API endpoint. You can use this to check an email or domain for being fake or not.

Simple query

GET /{your_api_key}/email/{email_address}

Check an email address or domain.

Example URI

GET /api/v1/af59d3....f40/email/srzd1234@sampletrash.com

Valid Parameters

  • string

    The email address or domain name you want to check.

Response on success show

HTTP-Code 200

Headers

Content-Type: application/json

Body

{
  "error": false,
  "suspected": true
}

Extended query

POST /{your_api_key}/email/{email_address}

Get detailed information about a fake email address.

Example URI

POST /api/v1/af59d3....f40/email/srzd1234@sampletrash.com

Excample request body show

{
  "lang": "en",
  "score": true,
  "extended": true
}

Valid JSON Parametersshow

  • string (optional)

    Two letter iso country code for the language you want to get the error messages in. Defaults to 'en'.

  • boolean (optional)

    If set to true and your API key is allowed to use it you will get a score for the probability of fake.

  • boolean (optional)

    If set to true and your API key is allowed to use it you will get detailed information about the score calculation.

Response on successshow

HTTP-Code 200

Headers

Content-Type: application/json

Body

{
  "error": false,
  "score": 1.0,
  "details": [
    {
      "reason": "no_vowel",
      "score": 0.1,
      "match": false,
      "description": "There is no vowel in this email address."
    },
    {
      "reason": "many_numbers",
      "score": 0.1,
      "match": "srzd1234",
      "description": "This address contains lots of numbers."
    },
    {
      "reason": "char_sequence",
      "score": 0.3,
      "match": "12345",
      "description": "This address contains multiple subsequent characters that are siblings in the alphabet."
    },
    {
      "reason": "trashmail",
      "score": 1,
      "match": "mytrashmail.com",
      "description": "This address is from a pool of known trash mail providers."
    }
  ],
  "suspected": true
}

Response on errorshow

  • SCORE_NOT_ALLOWED

    Your key does not allow the use of "score": true or "extended": true. Please upgrade to a plan that supports using these information.

Fake Numbers

Description

This is the fake numbers API endpoint. You can use this to check a phone number for being fake or not.

Simple query

GET /{your_api_key}/phone/{phone_number}

Check a phone number.

Example URI

GET /api/v1/af59d3....f40/phone/%2B4917676191594

Valid Parameters

  • string

    The phone number you want to check.

Response on success show

HTTP-Code 200

Headers

Content-Type: application/json

Body

{
  "error": false,
  "invalid": false,
  "suspected": true
}

Extended query

POST /{your_api_key}/phone/{phone_number}

Get detailed information about a phone number.

Example URI

POST /api/v1/af59d3....f40/phone/%2B4917676191594

Excample request body show

{
  "lang": "en",
  "score": true,
  "extended": true,
  "country": "de"
}

Valid JSON Parametersshow

  • string (optional)

    Two letter iso country code for the language you want to get the error messages in. Defaults to 'en'.

  • boolean (optional)

    If set to true and your API key is allowed to use it you will get a score for the probability of fake.

  • boolean (optional)

    If set to true and your API key is allowed to use it you will get detailed information about the score calculation.

  • string (optional)

    Two letter iso country code that should match the phone number. If the number is not valid for the given country it will be returned as invalid: true.

Response on successshow

HTTP-Code 200

Headers

Content-Type: application/json

Body

{
  "error": false,
  "invalid": false,
  "number": "+49 176 76191594",
  "type": "mobile",
  "number_provided": "+4917676191594",
  "country_prefix": "49",
  "prefix": "0176",
  "local_number": "76191594",
  "country": "de",
  "city": "",
  "suspected": true,
  "score": 0.75,
  "details": [
    {
      "reason": "virtual_number",
      "score": 1,
      "match": "receive-sms-online.info",
      "description": "This phone number is used by an online sms service. Registrations using this number are likely to be fake."
    },
    {
      "reason": "virtual_number_inactive",
      "score": -0.25,
      "match": "receive-sms-online.info",
      "description": "This phone number is marked as inactive at the online sms service."
    }
  ]
}

Response on errorshow

  • SCORE_NOT_ALLOWED

    Your key does not allow the use of "score": true or "extended": true. Please upgrade to a plan that supports using these information.

Domain reporting

Description

This is the reporting API endpoint. You can use this to report new fake domains. Please keep in mind that we cannot report back on the results of our checks regarding your reported domains.

Calls to this API endpoint will NOT be counted as requests and such they do NOT affect your query limit.

Report domains

POST /{your_api_key}/report

Report one or multiple fake domains to fiddlemail.com. You can report up to 100 new domains in a single API call.

Example URI

POST /api/v1/af59d3....f40/report

Excample request body show

{
  "domains": [
      "fakedomain.com",
      "anotherdomain.com"
  ]
}

Valid JSON Parametersshow

  • array (strings)

    Array of Domains (without user part) to report.

Response on successshow

HTTP-Code 200

Headers

Content-Type: application/json

Body

{
  "error": false
}

Response on errorshow

  • MISSING_DOMAIN_LIST

    You forgot to add domains to your api call.

  • LONG_DOMAIN_LIST

    You sent more than 100 domains in a single request.