RealMail API (Now Beta!)

RealMail offers a full SOAP/WSDL API for integration with your systems.

If you are a programmer or web developer you can easily integrate RealMail into your applications and start sending letters directly from your software!

You can browse our API at: https://realmail.virtualthinking.net/loadsoap.php?desc

The WSDL is at: https://realmail.virtualthinking.net/loadsoap.php?wsdl

The pages are protected by basic HTTP authentication, and you can access them using:

Username : bulk
Password : 1qaz2wsx3edc4rfv

Description of Remote Methods

  • CreateJob ([string]APIKey, [string]Name, [string]Description)

    This is always the first method you call. It will, upon successful execution return you a JobID that you will need for all other transactions.

    You job will be set to a "DRAFTING" status.

    You can check the status of the transaction by checking the Status property of the returned object.

    This method returns the following:

    JobID     : Unique reference for new job.
    Status    : OK|NOCREATE|NOAUTH
        

  • AddItem ([string]APIKey, [string]JobID, [base64 string]PDFBinaryString, [string]DestinationAddressName, [string]DestinationAddress, [string]DestinationAddressState, [string]DestinationAddressPostcode, [string]DestinationAddressCountry, [string]ReturnAddress)

    This method allows you to add PDF files into your job.

    You can only add files while your job Status is "DRAFTING".

    A successful file transfer does not ensure that the file is acceptable, or "RECEIVED". Please check Status return codes as you proceed.

    You can check the status of the transaction by checking the Status property of the returned object.

    This method returns the following:

    Status    : OK:RECEIVED|OK:PDFERR|NOCREATE|NOCOUNTRY|NOSTATUS|NOAUTH|NOFILE
        

    The following country codes are valid (case sensitive) for DestinationAddressCountry:

    SINGAPORE, MALAYSIA, BRUNEI, AMERICAN SAMOA, BANGLADESH, BHUTAN, CAMBODIA, CHINA, FIJI, FRENCH POLYNESIA, GUAM, HONG KONG, INDIA, INDONESIA, KIRIBATI, SOUTH KOREA, LAO, MACAO, MALDIVES, MARSHALL ISLANDS, MICRONESIA, MONGOLIA, MYANMAR, NAURU, NEPAL, NEW CALEDONIA, NORTHERN MARIANA ISLANDS, PAKISTAN, PALAU, PAPUA NEW GUINEA, PHILIPPINES, PITCAIRN ISLANDS, SAMOA, SOLOMON ISLANDS, SRI LANKA, TAIWAN, THAILAND, TIMOR-LESTE, TONGA, TUVALU, VANUATU, VIET NAM, WALLIS AND FUTUNA, AFGHANISTAN, ALBANIA, ALGERIA, ANDORRA, ANGOLA, ANGUILLA, ANTIGUA AND BARBUDA, ARGENTINA, ARMENIA, ARUBA, AUSTRALIA, AUSTRIA, AZERBAIJAN, BAHAMAS, BAHRAIN, BARBADOS, BELARUS, BELGIUM, BELIZE, BENIN, BERMUDA, BOLIVIA, BOSNIA AND HERZEGOVINA, BOTSWANA, BRAZIL, BRITISH INDIAN OCEAN TERRITORY, BULGARIA, BURKINA FASO, BURUNDI, CAMEROON, CANADA, CAPE VERDE, CAYMAN ISLANDS, CENTRAL AFRICAN REPUBLIC, CHAD, CHILE, COLOMBIA, COMOROS, CONGO, COSTA RICA, COTE D'IVOIRE, CROATIA, CUBA, CYPRUS, CZECH REPUBLIC, DENMARK, DJIBOUTI, DOMINICA, DOMINICAN REPUBLIC, ECUADOR, EGYPT, EL SALVADOR, EQUATORIAL GUINEA, ERITREA, ESTONIA, ETHIOPIA, FALKLAND ISLANDS, MALVINAS, FAROE ISLANDS, FINLAND, FRANCE, FRENCH GUIANA, GABON, GAMBIA, GAZA AND KHAN YUNIS, GEORGIA, GERMANY, GHANA, GIBRALTAR, GREECE, GREENLAND, GRENADA, GUADELOUPE, GUATEMALA, GUERNSEY, GUINEA, GUINEA-BISSAU, GUYANA, HAITI, HOLY SEE, VATICAN, HONDURAS, HUNGARY, ICELAND, IRAN, IRAQ, IRELAND, ISLE OF MAN, ISRAEL, ITALY, JAMAICA, JAPAN, JERSEY, JORDAN, KAZAKHSTAN, KENYA, KUWAIT, KYRGYZSTAN, LATVIA, LEBANON, LESOTHO, LIBERIA, LIBYA, LIECHTENSTEIN, LITHUANIA, LUXEMBOURG, MACEDONIA, MADAGASCAR, MALAWI, MALI, MALTA, MARTINIQUE, MAURITANIA, MAURITIUS, MAYOTTE, MEXICO, MOLDOVA, MONACO, MONTENEGRO, MONTSERRAT, MOROCCO, MOZAMBIQUE, NAMIBIA, NETHERLANDS ANTILLES, NETHERLANDS, NEW ZEALAND, NICARAGUA, NIGER, NIGERIA, NORWAY, OMAN, PANAMA, PARAGUAY, PERU, POLAND, PORTUGAL, PUERTO RICO, QATAR, REUNION, ROMANIA, RUSSIA, RWANDA, SAN MARINO, SAO TOME AND PRINCIPE, SAUDI ARABIA, SENEGAL, SERBIA, SEYCHELLES, SIERRA LEONE, SLOVAKIA, SLOVENIA, SOMALIA, SOUTH AFRICA, SPAIN, ST HELENA, ST KITTS AND NEVIS, ST LUCIA, ST PIERRE AND MIQUELON, ST VINCENT AND THE GRENADINES, SUDAN, SURINAME, SVALBARD AND JAN MAYEN, SWAZILAND, SWEDEN, SWITZERLAND, SYRIA, TAJIKISTAN, TANZANIA, TOGO, TRINIDAD AND TOBAGO, TUNISIA, TURKEY, TURKMENISTAN, TURKS AND CAICOS ISLANDS, UGANDA, UKRAINE, UNITED ARAB EMIRATES, UNITED KINGDOM, UNITED STATES, URUGUAY, UZBEKISTAN, VENEZUELA, VIRGIN ISLANDS, WESTERN SAHARA, YEMEN, ZAMBIA, ZIMBABWE


  • AddItemVerifyAddress ([string]APIKey, [string]JobID, [string]DestinationAddressName, [string]DestinationAddress, [string]DestinationAddressState, [string]DestinationAddressPostcode, [string]DestinationAddressCountry, [string]PushURL, [string]PushID, [string]PushSecret)

    This method allows you to add an address verification letter into your job.

    You can only add files while your job Status is "DRAFTING".

    You can check the status of the transaction by checking the Status property of the returned object.

    This method returns the following:

    Status    : OK:RECEIVED|OK:PDFERR|NOVERIFY|NOCREATE|NOCOUNTRY|NOSTATUS|NOAUTH|NOFILE|NOENDPOINT
        

    The same country codes apply as for the AddItem method.

    Once the verification is complete, our systems will do a POST operation to the URL provided in PushURL and return the appropriate values for VerificationStatus, PushID, and PushSecret. PushID will be the [unique] value you provided when invoking this method (allowing you to identify the originating transaction; and PushSecret is a shared secret that we will provide to verify that we are providing a legitimate request/result.


  • SubmitJob ([string]APIKey, [string]JobID)

    After adding all the PDF items you require, you must execute this transaction successfully to complete your submission. This updates your job into a "PENDING" state that will then be picked up for processing and production.

    Jobs that are not submitted will not be processed any further and will be purged after some time.

    You can check the status of the transaction by checking the Status property of the returned object.

    This method returns the following:

    Status    : OK|NOSUMBIT|NOAUTH
        

  • GetSummary ([string]APIKey, [string]JobID)

    You can get a full summary of your job at any time, during or after creating a job.

    You can check the status of the transaction by checking the Status property of the returned object.

    This method returns the following:

    JobStatus : DRAFTING|PENDING
    Receieved : Integer
    PDFError  : Integer
    Status    : OK|NOAUTH
        

PHP Sample Code to Examine SOAP/WSDL Interface

You can run this from the command line: e.g. php get.soap.php

 //********************************************************************************
 //********************************************************************************
 //Initialize Variables
 $user = "bulk";
 $pass = "1qaz2wsx3edc4rfv";
 $wsdl = "https://realmail.virtualthinking.net/loadsoap.php?wsdl";

 //Create new SOAP Class Worker Instance
 try {
   $client = new SoapClient (
     $wsdl,
     array (
       "login"          => $user,
       "password"       => $pass,
       'authentication' => SOAP_AUTHENTICATION_BASIC,
       "trace"          => true,
       'exceptions'     => true,
       'cache_wsdl'     => WSDL_CACHE_NONE
     )
   );

   fwrite (STDOUT, "\nConnected to Web Service!\n");
   fwrite (STDOUT, "\n");

   //Call remote function
   fwrite (STDOUT, "FUNCTIONS:\n");
   print_r ($client->__getFunctions ());
   fwrite (STDOUT, "\n");

   fwrite (STDOUT, "TYPES:\n");
   print_r ($client->__getTypes ());
   fwrite (STDOUT, "\n");
 } catch (SoapFault $error) {
   fwrite (STDERR, "\nSOAP Error:\n".$error."\n");
 }

 exit (0);
      

PHP Sample Code to Test SOAP/WSDL Interface

You can run this from the command line: e.g. php try.soap.php

 //********************************************************************************
 //********************************************************************************
 //Initialize Variables
 $user   = "bulk";
 $pass   = "1qaz2wsx3edc4rfv";
 $wsdl   = "https://realmail.virtualthinking.net/loadsoap.php?wsdl";
 $apikey = "00000000000000000000000000000000";

 //Create new SOAP Class Worker Instance
 try {
   $client = new SoapClient (
     $wsdl,
     array (
       "login"          => $user,
       "password"       => $pass,
       'authentication' => SOAP_AUTHENTICATION_BASIC,
       "trace"          => true,
       'exceptions'     => true,
       'cache_wsdl'     => WSDL_CACHE_NONE
     )
   );

   fwrite (STDOUT, "\nConnected to Web Service!\n");
   fwrite (STDOUT, "\n");

   //********************************************************************************
   $response = $client->CreateJob ($apikey,
                                   "Test Job",
                                   "This is a test job.");
   $jobid  = $response->JobID;
   print_r ($response);
   fwrite (STDOUT, "\n");
   unset ($response);
   //********************************************************************************

   //********************************************************************************
   $response = $client->AddItem ($apikey,
                                 $jobid,
                                 base64_encode (file_get_contents ("bulk.test.pdf")),
                                 "VirtualThinking",
                                 "P.O. Box 1051,\nNorth Melbourne",
                                 "VIC",
                                 "3051",
                                 "AUSTRALIA",
                                 "VBox 881973,\nSingapore 919191");
   print_r ($response);
   fwrite (STDOUT, "\n");
   unset ($response);
   //********************************************************************************

   //********************************************************************************
   $output = $client->AddItemVerifyAddress ($apikey,
                                            $jobid,
                                            "VirtualThinking",
                                            "P.O. Box 1051,\nNorth Melbourne",
                                            "VIC",
                                            "3051",
                                            "AUSTRALIA",
                                            "https://yourdomain.com/verifiedaddress",
                                            "TransactionID",
                                            "TransactionSecret");

   print_r ($output);
   fwrite (STDOUT, "\n");
   unset ($output);
   //********************************************************************************

   //********************************************************************************
   $response = $client->SubmitJob ($apikey, $jobid);
   print_r ($response);
   fwrite (STDOUT, "\n");
   unset ($response);
   //********************************************************************************

   //********************************************************************************
   $response = $client->GetSummary ($apikey, $jobid);
   print_r ($response);
   fwrite (STDOUT, "\n");
   unset ($response);
   //********************************************************************************
 } catch (SoapFault $error) {
   fwrite (STDERR, "\nSOAP Error:\n".$error."\n");
 }

 exit (0);