Mogelmail API

API

Beschreibung

Dies ist die REST API von mogelmail.de. Sie kann verwendet werden, um Informationen über Fake-E-Mails und Fake-SMS-Nummern zu erhalten. Die deutsche Übersetzung der API-Dokumentation ist noch unvollständig. Die englische Version finden Sie hier.

Sie können eine Beispiel-PHP-Klasse und ein Beispiel-PHP-Skript here herunterladen. Es zeigt Ihnen die Verwendung der API.

Authentifizierung

Die Authentifizierung erfolgt über Ihren API-Key. Bitte besuchen Sie diese Seite, wenn Sie noch keinen API-Key besitzen.

Der API-Key wird in die Url jeder Anfrage eingebettet:

/{ihr_api_key}/email/{zu_pruefende_adresse}

Dies gilt für alle Anfragearten (GET und POST).

API Urls

Die Basis-Url für die mogelmail.de-API ist:

Live-System: https://www.mogelmail.de/api/v1

Sie finden die vollständige Url, die Sie für die verschiedenen Anfragen benötigen, unten.

Bitte kontaktieren Sie info@mogelmail.de, wenn Sie weitere Informationen benötigen.

Anfrageformat

Alle Anfrageparameter neben der zu prüfenden Telefonnummer/E-Mail-Adresse werden via JSON übergeben. Welche Parameter verwendet werden können, sehen Sie in den jeweiligen API-Bereichen weiter unten.

Antwortformat

Die API gibt einen HTTP-Status-Code zurück und enthält im Body der Antwort ein JSON-Objekt. Das JSON-Objekt (sofern vorhanden) enthält grundsätzlich das 'error'-Attribut.

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

Das Attribut 'error' ist auf 'true' gesetzt, wenn etwas mit der Anfrage schiefgegangen ist. Bitte beachten Sie, dass die API auch HTTP-Status-Codes verwendet, bei denen normalerweise der Body-Inhalt der Antwort nicht beachtet wird. Stellen Sie also sicher, dass Sie das JSON-Objekt auch bei den HTTP-Codes '400', '403', '404' etc. auswerten.

Wenn das Attribut 'error' auf 'true' gesetzt ist, erhalten Sie zudem eines oder mehrere der folgenden Attribute:

Allgemeine Fehlerzeigen

  • string

    Hier finden Sie die eigentliche Fehlermeldung. Diese kann einen der folgenden Werte enthalten:

  • MISSING_HTTP_METHOD

    Der Server konnte die HTTP-Methode nicht lesen (GET, POST).

  • INVALID_HTTP_METHOD

    Die gesendete HTTP-Methode ist ungültig (GET, POST).

  • UNSUPPORTED_METHOD

    Die gesendete HTTP-Methode wird für die API-Anfrage nicht unterstützt.

  • MISSING_REQUEST_URI

    Die aufgerufene API-Url ist nicht gültig.

  • INVALID_API_VERSION

    Die aufgerufene API-Version ist nicht gültig.

  • MISSING_API_METHOD

    Die aufgerufene API-Url enthält keinen gültigen API-Endpunkt.

  • MISSING_QUERY

    Die API-Url enthielt keine Anfrage für eine E-Mail-Adresse oder Telefonnummer.

  • 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.