Your use of the MailingBird API is subject to the terms & conditions between you and MailingBird. Our API offers in-depth documentation and the integration possibilities are endless. If you have any technical questions regaring an integration, please contact our support.

It's easy to get started with our simple HTTP API to integrate the whole intelligence in your system and build killer mailing lists.

For websiteowners we also provide an easy to use Real-time Email-Form Validation (see also our Live Demos) to keep your lists clean and reliable from the beginning.

Note: To use the MailingBird Advanced API, you need to sign up for an API-Key. As a professional service provider we will NEVER send any emails to one of your addresses!


Receiving additional data on a given address is a simple matter of sending a GET request to the API endpoint located at http://www.mailingbird.com/api/. This is a sample markup for an HTTP GET Request to MailingBird Free API:

    
    http://www.mailingbird.com/api/{FORMAT}/{EMAIL}
 

Parameters:

{FORMAT} Response format: Available formats are "json" or "xml"
{EMAIL} The email-address to work with; This can be any valid email-address like "john.doe@example.com" or any string representing a kind of a valid address like "johndoe(at)example.com" or "john.doe[at]example.com"

The Result

[ResponseCode] Shows general information about your request. Available ResponseCodes are:
  • 200: Your Request was successfull.
  • 400: Bad Request(e.g. due to an non-valid email string).
[ResponseStatus] Shows additional information on the [ResonseCode].
[Result] The result of your request (if successful), otherwise false.

The [Result]

[Address] Contains general inofrmation about your submitted address:
  • [SubmittedSyntax]: This is the exact Syntax of the email address that you submitted to MailingBird.
  • [SanitizedSyntax]: This is representing a sanitized version of the submitted address. It is recommended to use this syntax even for your data.
  • [CorrectedSyntax]: This is representing a suggestion on an autocorrected syntax of the submitted address, otherwise false.
  • [KnownMailer]: Boolean true or false. Flags, if the submitted address is hosted by an common ISP or webmail-service.
[Lookups] Returns additional data for the submitted address:
  • [Trashmail]: If the submitted address is a known trashmail-account. Can be set totrue or false

Example #1: JSON Response for MailingBird Free API

    Request:    
    http://www.mailingbird.com/api/json/john.doe79@example.com

    Response:  
    {
        "ResponseCode": 200,
        "ResponseStatus": "Request ok",
        "Result": {
            "Address": {
                "SubmittedSyntax": "John.Doe79@hozmail.com",
                "SanitizedSyntax": "john.doe79@hozmail.com",
                "CorrectedSyntax": "john.doe79@hotmail.com",
                "KnownMailer": true
            },
            "Lookups": {
                "Trashmail": false
            }
        }
    }
 

The interface is a simple matter of sending a GET request to the API endpoint located at http://www.mailingbird.com/api/. This is a sample markup for an HTTP GET Request to MailingBird:

    
    http://www.mailingbird.com/api/{APIKEY}/{FORMAT}/{EMAIL}
 

Parameters:

{APIKEY} Your personal API-Key
{FORMAT} Response format: Available formats are "json" or "xml"
{EMAIL} The email-address to work with; This can be any valid email-address like "john.doe@example.com" or any string representing a kind of a valid address like "johndoe(at)example.com" or "john.doe[at]example.com"

The Result

[ResponseCode] Shows general information about your request. Available ResponseCodes are:
  • 200: Your Request was successfull.
  • 400: Bad Request(e.g. due to an invalid email string).
  • 401: Unauthorized Request(e.g. invalid API-Key).
[ResponseStatus] Shows additional information on the [ResonseCode].
[Result] The result of your request (if successful), otherwise false.

The [Result]

[Address] Contains general inofrmation about your submitted address:
  • [SubmittedSyntax]: This is the exact Syntax of the email address that you submitted to MailingBird.
  • [SanitizedSyntax]: This is representing a sanitized version of the submitted address. It is recommended to use this syntax even for your data.
  • [CorrectedSyntax]: This is representing a suggestion on an autocorrected syntax of the submitted address, otherwise false.
  • [KnownMailer]: Boolean true or false. Flags, if the submitted address is hosted by an common ISP or webmail-service.
[Lookups] Shows technical information to the submitted [Address]
  • [Mailbox]: Name of users mailbox at [Host]
  • [Host]: The Host of the submitted address with the [SanitizedSyntax]
  • [HostDNS]: Shows if DNS-records are existing: true or false
  • [MXRecords]: This flags, if the submitted address has a valid MX-Record and will be boolean true or false
  • [CatchAll]: true or false, wether [Host] has the catcall-option activated.
  • [MailboxType]: Wether its a "technical", "generic", "business", "student" or "personal" mailbox.
  • [MailboxStatus]: Shows information on the status of the submitted Mailbox:
    • Mailbox ok
    • Mailbox overloaded
    • Mailbox temporary not available
    • Mailbox not available
  • [Trashmail]: If the submitted address is a known trashmail-account. Can be set to true or false
[Information] Returns additional data for the submitted address, if available:
  • [Firstname]: This is the firstname for the owner of the submitted email-address
  • [Lastname]: This is the lastname for the owner of the submitted email-address
  • [Gender]: Can be f (female), m (male) or false.
  • [Age]: This is representing the age-group: Possible values are:
    • false: unknown
    • 14-19
    • 20-29
    • 30-39
    • 40-49
    • 50-59
    • 60+
  • [Language]: Can be false or the two digit countrycode, e.g. "US"
  • [GeoData]: Some additional geo-information
    • [Country] 2-digit country code
    • [State]
    • [Region]
  • [Credibility]: You can use this integer value to see how reliable the available information on the current email-user are . The maximum value of 100 (Percent) represents the fact, that the provided information is very reliable.
[Summary]
  • [BounceRisk]An integer value (percentage) representing the chance an email to this address is going to bounce.
  • [SpamAuthority]An Integer value representing the chance for the submitted address to be spam in percent. The maximum value of 100 (Percent) represents the fact that the provided address is spam.

Example #1: JSON Response for MailingBird Advanced API

    Request:    
    http://www.mailingbird.com/api/[YOUR_API_KEY]/json/john.doe79@example.com

    Response:  
    {
        "ResponseCode": 200,
        "ResponseStatus": "Request ok",
        "Result": {
            "Address": {
                "SubmittedSyntax": "John.Doe79@example.com",
                "SyntaxValidation": true,
                "SanitizedSyntax": "john.doe79@example.com",
                "CorrectedSyntax": false
                "KnownMailer": false
            },
            "Lookups": {
                "Mailbox": "john.doe79",
                "Host": "example.com",
                "HostDNS": true,
                "MXRecords": false,
                "MailboxStatus": "Mailbox not available",
                "CatchAll": false,
                "MailboxType": "personal",
                "Trashmail": false
            },
            "Information": {
                "Firstname": "John",
                "Lastname": "Doe",
                "Gender": "m",
                "Age": "30-39",
                "Language": US,
                "GeoData": {
                    "Country": false,
                    "State": false,
                    "Region": false
                },
                "Credibility": 90
            },
            "Summary": {
                "BounceRisk": 100,
                "SpamAuthority": 90
            }
        }
    }
 

Example #2: XML Response

    Request:      
    http://www.mailingbird.com/api/[YOUR_API_KEY]/xml/John.Doe79@example.com
    
Response: coming soon

Use our powerfull API to boost your campaigns now!

Sign up today to tune up your mailinglist and get 100 Mail-checks for free!

Sign up today

  <?php
   
  //Step 1: Request the information on your address
   
  $url = "http://www.mailingbird.com/api/{YOURAPIKEY}/json/{EMAIL}";
    
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HEADER, FALSE);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
  $data = curl_exec($ch);
  curl_close($ch); 
   
  //Step 2: Turn the result into an Object 
  
  $result_obj = json_decode($data);
  
  //Step 3: Use the data e.g. for storing in your database or to print out on screen
  
  if( $result_obj->ResponseCode == 200 ){
    
    echo $result_obj->Address->SanitizedSyntax;
  
  }
  
  ?>


With MailingBird you can also perform a very solid real-time validation using AJAX for checking your email-forms inside your website.

Check out our Live Demos, to see this in action.

Step1: Clientside Javascript Implementation

Example #1: Bind to click() event of the submit button. Using jQuery a simple Email Check-Up could look something like this:

  <form id="myform">
    <input type="email" name="mymail">
    <button type="button">Submit</button>
  </form>
  
  <script>
  
 //To bind the validation to other events than click() on the submit button, see example #2 below
 //Make sure, that the button inside your <form> has type="button", not type="submit".
  
 $('#myform button').click( function() {
    
    var email = $('#myform input[name="mymail"]').val();
   
    $.ajax({
      url: "./yourAjaxScript.php",
      type: "POST",
      data: {mail : email},
      success: function(response) {
       
        var data = jQuery.parseJSON(response);
  
        if( data.ResponseCode == 400 || (data.ResponseCode == 200 && data.Result.Summary.SpamAuthority > 50 ) ){
          //This Email is not valid
          alert("Please use a valid email-address");
        }else{
          //Email is valid. 
          $('#myform').submit(); 
        }
      }
    });    
  });
  
  </script>

Example #2: Bind to submit() event of the whole form. To bind the validation to your form submission, you could use something like below. There is a variable "checkup" to make sure the form is not submitted before your ajax response arrives.

  <form id="myform">
    <input type="email" name="mymail">
    <button type="submit">Submit</button>
  </form>
  
  <script>
  
   //The var checkup is needed to prevent form submission before ajax response arrived
   var checkup = false;
  
   $('#myform').submit(function(){
              
    var email = $('#myform input[name="mymail"]').val();
   
      $.ajax({
        url: "./yourAjaxScript.php",
        type: "POST",
        data: {mail : email},
        success: function(response) {
         
          var data = jQuery.parseJSON(response);
 
          if( data.ResponseCode == 400 || (data.ResponseCode == 200 && data.Result.Summary.SpamAuthority > 50 ) ){
            //This Email is not valid
            alert("Please use a valid email-address");
          }else{
            //Ajax response is ready and email is valid, so switch checkup and submit again.
            checkup = true;
            //Use the sanitized syntax for input value
            $('#myform input[name="mymail"]').val(data.Result.Address.SanitizedSyntax);
            $('#myform').submit();
          }
            
        }
      });
      
      return checkup;
      
   });
  
  </script>

Step2: Serverside Implementation using PHP

To handle the request on your server and drop a successfull API-Request, we suggest to use PHP cURL function. In your yourAjaxScript.php this could look something like this:

  <?php
  
  if( isset($_POST["mail"]) && strlen($_POST["mail"]) ){
  
    $url = "http://www.mailingbird.com/api/{YOURAPIKEY}/json/".urlencode($_POST["mail"]);
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_HEADER, FALSE);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    $data = curl_exec($ch);
    curl_close($ch); 
    echo $data;
    exit; // only print out the json of the response
  }
  
  ?>


Use our powerfull API now to boost your campaigns!

Sign up today to tune up your mailinglist and get 100 Mail-checks for free!

Sign up today

Not convinced, yet? Try out our sandbox!

Use our free Sandbox to see what MailingBird brings to you.

Try out our Sandbox