# Sunday, 31 July 2016

Below is an example of using our JSON API to send a letter.

Our JSON API has exactly the same fields as our SOAP API and uses the same functionality as our SOAP API.

In the example below we are sending a letter to one person with the body included as free text. You may also use HTML to format the body of your letter. The JSON below could quite easily be used straight from JavaScript or from nodejs, but could just as well be used from almost any coding language. The endpoint to post your JSON to is https://www.pc2paper.co.uk/lettercustomerapi.svc/json/SendSubmitLetterForPosting

{
    "letterForPosting":
    {
    "SourceClient" : "My App name 1",
    "Addresses" :[
        {"ReceiverName": "John Smith",
        "ReceiverAddressLine1" : "1 Acme Road",
        "ReceiverAddressLine2" : "My Street",
        "ReceiverAddressTownCityOrLine3" : "Town",
        "ReceiverAddressCountyStateOrLine4" : "County",
        "ReceiverAddressPostCode" : "Postcode"}
        ],
        "ReceiverCountryCode" :1,
        "Postage":31,
        "Paper":1,
        "Envelope":1,
        "Extras":0,
        "LetterBody" : "Dear Peter, 
Please find my letter attached"
,
        "IncludeSenderAddressOnEnvelope" : true,
        "SenderAddress" : "22 Acme Acres\n Acme Town",
        "YourRef" : "MyRef001" 
        
    },
     "username" : "yourusername",
    "password" : "yourpassword"
}

In the above examples you will notice we use a ReceiverCountryCode you can lookup the code to use for the country you are sending to here. In the above example the country code 1 represents the UK.

For the postage options you can lookup the options you would like to use by using our postage calculator. The postage calculator will list the API options at the bottom of the page for you after you make your selection.  In the example above we have chosen Postage 31 (UK Second Class), Paper 1 (Black and White 80 gsm), Envelope 1 (Standard DL). If you would like the ability to lookup your own postage options, you can use our letter pricing API which you can find out more about here

If you'd like to include PDF's as attachment's to your letter, you can upload these and use the unique id's the website gives you to attach them to your letter.

You can upload PDF's one of two ways.

JSON PDF File Upload

https://www.pc2paper.co.uk/lettercustomerapi.svc/json/UploadDocument

With a JSON file upload you will need to convert what ever file you are uploading into an integer array. This can usually be done by converting your file into a byte array and then into an integer array

{
    "filename":"myfile.pdf",
    "username":"yourusername",
    "password":"yourpassword",
    "fileContent":[37,80,68,70,45,49,46,53,13,10,37...]
}

 

After successfully uploading your PDF file you should receive a response similar to the following.

{
  "d": {
    "__type": "UploadedFileResult:#PC2Paper.Entity.Public.Letters",
    "ErrorMessages": null,
    "FileCreatedGUID": "648b6725-a3c6-4396-b28a-33e86589aa4b",
    "Status": "OK"
  }
}

Store the FileCreatedGUID somewhere as you will need this to attach it to your letter. 

SOAP PDF File Upload

If you would prefer to upload your PDF file over SOAP instead of JSON you can use this endpoint.

https://www.pc2paper.co.uk/lettercustomerapi.svc?wsd

You can find a PHP example and C# example of how to use our SOAP API to upload a file.

Using an uploaded PDF file in your letter

After you have uploaded your PDF file using one of the two methods above you will be provided with a FileCreatedGUID for each file you upload. Construct the JSON for your letter as before but include an array of File GUIDs you would like to attach in the FileAttachementGUIDs field.

{
    "letterForPosting":
    {
    "SourceClient" : "My PC2Paper Client",
    "Addresses" :[
        {"ReceiverName": "John Smith",
        "ReceiverAddressLine1" : "1 Acme Road",
        "ReceiverAddressLine2" : "My Street",
        "ReceiverAddressTownCityOrLine3" : "Town",
        "ReceiverAddressCountyStateOrLine4" : "County",
        "ReceiverAddressPostCode" : "Postcode"}
        ],
        "ReceiverCountryCode" :1,
        "Postage":31,
        "Paper":1,
        "Envelope":11,
        "Extras":0,
        "LetterBody" : "Dear Peter, 
Please find my letter attached"
,
        "FileAttachementGUIDs":["648b6725-a3c6-4396-b28a-33e86589aa4b"]
        
    },
     "username" : "your username",
    "password" : "yourpassword"
    
    
}

You should receive the following response after submitting a successful letter.

{
  "d": {
    "__type": "LetterForPostingResult:#PC2Paper.Entity.Public.Letters",
    "CostOfLetter": 2.02,
    "ErrorMessages": null,
    "FundsLeftInYourAccount": 160.54,
    "LetterId": "71566",
    "Status": "OK"
  }
}

Sending a letter to more than one person

If you would like to send the same letter to more than one person. Just add more people to the Addresses array.

 "Addresses" :[
        {"ReceiverName": "John Smith",
        "ReceiverAddressLine1" : "1 Acme Road",
        "ReceiverAddressLine2" : "My Street",
        "ReceiverAddressTownCityOrLine3" : "Town",
        "ReceiverAddressCountyStateOrLine4" : "County",
        "ReceiverAddressPostCode" : "Postcode"},
        
         {"ReceiverName": "Bob Smith",
        "ReceiverAddressLine1" : "The Gables",
        "ReceiverAddressLine2" : "Another Road",
        "ReceiverAddressTownCityOrLine3" : "Town",
        "ReceiverAddressCountyStateOrLine4" : "County",
        "ReceiverAddressPostCode" : "ZZ1 0ZZ"}
        ]
posted on Sunday, 31 July 2016 18:59:08 (GMT Daylight Time, UTC+01:00)  #    Comments [0] Trackback
# Wednesday, 21 August 2013

We've had several requests for an example on using our SOAP API, so decided to throw one together for you to get an idea of how it works.

The example below will send PDF documents as a letter with a cover letter which is written as a formatted HTML string (see the LetterBody attribute below).

To make more use of this example and to adapt it to your needs you may need to look at the Letter Pricing API along with the country code list which can all be found here.

If you would like us to advise you on what are the best options to use for postage and paper usage please contact us.

   1:  <?php
   2:   
   3:  $client = new SoapClient("https://www.pc2paper.co.uk/lettercustomerapi.svc?wsdl");
   4:   
   5:  // Your PC2Paper Username and Password go below
   6:  $pc2paperUsername = "username";
   7:  $pc2paperPassword = "password";
   8:   
   9:  //First we upload a PDF we wish to attach to our letter
  10:   
  11:  $file = file_get_contents("C:\tempfiles\mytestfile.pdf");
  12:   
  13:  //We give the pdf a friendly name
  14:  $parametersUpload->filename = "mytestFile.pdf";
  15:  $parametersUpload->fileContent = $file;
  16:  $parametersUpload->username=$pc2paperUsername;
  17:  $parametersUpload->password=$pc2paperPassword;
  18:   
  19:  //We submit our PDF to PC2Paper
  20:  $uploadedFileResult = $client->UploadDocument($parametersUpload);
  21:   
  22:  // Not the above return value contains the following
  23:  // $uploadedFileResult->UploadDocumentResult->ErrorMessages  (A a string array of any errors that took place)
  24:  // $uploadedFileResult->UploadDocumentResult->FileCreatedGUID (The created files GUID)0
  25:  // $uploadedFileResult->UploadDocumentResult->Status (OK or ERROR, if error check ErrorMessages array
  26:   
  27:  //After our PDF has been submited we get a GUID which we store in an array to use with our letter below.
  28:  //Note you can attach multiple PDF's to your letter by adding to this array.
  29:  $fileGuidArray =  array($uploadedFileResult->UploadDocumentResult->FileCreatedGUID);
  30:   
  31:   
  32:  // ********** The actual Letter.
  33:  // We put an address together
  34:  $address->ReceiverName = "Tom Smith";
  35:  $address->ReceiverAddressLine1 = "Line 1 ";
  36:  $address->ReceiverAddressLine2 = "Line 2";
  37:  $address->ReceiverAddressTownCityOrLine3 = "My Town";
  38:  $address->ReceiverAddressCountyStateOrLine4 = "County";
  39:  $address->ReceiverAddressPostCode = "ZZ1 2ZZ";
  40:   
  41:  // Add the address to an address array
  42:  $addressArray = array($address);
  43:   
  44:  //Add the address array to our letter
  45:  $letter->Addresses = $addressArray ;
  46:   
  47:  //Setup our postage options (use the LetterPosting API for these values 
  48:  //or ask us and we will be happy to provide the values based on your needs)
  49:   
  50:   
  51:  // 1=UK , 240=US for a list of more please refer to country.csv file from the API section of our website.
  52:  $letter->ReceiverCountryCode = 1; 
  53:   
  54:  $letter->IncludeSenderAddressOnEnvelope = true;
  55:  $letter->Postage = 3; //UK First Class
  56:  $letter->Paper = 1;  // B&W Single Sides print
  57:  $letter->Extras = 0;
  58:  $letter->Envelope = 1; //Simple DL envelope
  59:  $letter->Pages = 2;
  60:  $letter->FileAttachementGUIDs = $fileGuidArray;
  61:   
  62:  $letter->SenderAddress = "Peter Smith\nMy Town";
  63:   
  64:  //This is the cover letter of your letter. Leave this null if you do not want a cover letter
  65:  //You may use formatted HTML in here to format your letter.
  66:  $letter->LetterBody = "<p>Hi Tom,</p> <p>This is a letter sent from PHP!</p>";
  67:   
  68:   
  69:  $parameters->letterForPosting = $letter;
  70:   
  71:  // Your PC2Paper username and password
  72:  $parameters->username = $pc2paperUsername;
  73:  $parameters->password = $pc2paperPassword;
  74:   
  75:  $result = $client->SendSubmitLetterForPosting($parameters);
  76:   
  77:  // The return object will give you the following
  78:  // $result->SendSubmitLetterForPostingResult->CostOfLetter
  79:  // $result->SendSubmitLetterForPostingResult->ErrorMessages  (any errors that took place)
  80:  // $result->SendSubmitLetterForPostingResult->FundsLeftInYourAccount
  81:  // $result->SendSubmitLetterForPostingResult->LetterId
  82:  // $result->SendSubmitLetterForPostingResult->Status (OK if everything went ok or ERROR, if error check the ErrorMessages array)
  83:   
  84:   
  85:  print_r($result);
  86:  ?>
posted on Wednesday, 21 August 2013 21:02:50 (GMT Daylight Time, UTC+01:00)  #    Comments [0] Trackback
# Monday, 05 August 2013

We've just released a beta version of our new SOAP API which harnesses many of the features found in our recently launched Letter 2.0 writing interface.

The API enables you to:

  • Send the same letter to multiple recipient
  • Attach multiple PDF's to a letter
  • Add a cover (written in HTML) with or without PDF's

More documentation will follow soon, but for now here is an example for using the API.

The endpoint for the service can be found here https://www.pc2paper.co.uk/lettercustomerapi.svc
to access the WSDL simply go here https://www.pc2paper.co.uk/lettercustomerapi.svc?wsdl

Please note the service endpoint talks about svcutil.exe, this is only applicable to Microsoft WCF users. Please also note that SOAP is a widely used XML-based protocol, it is assumed at all times that the developer is aware of SOAP or has used it. It is beyond the scope of this article to explain SOAP. If you are using .NET you can take advantage of the features available to you in WCF, if not you can still use the service as a bog standard soap service from any of the popular languages such as PHP, C#, Ruby, Delphi, Java etc. by just using the WSDL (https://www.pc2paper.co.uk/lettercustomerapi.svc?wsdl )

The example in this article uses C#, we will cover using the service from other languages in future, for now here are some links about SOAP in those languages.

The following example illustrates how to upload a PDF attachment and write a cover letter with our new API the sample below is in C# using Visual Studio .NET. More examples in other languages will follow.

Firstly add a new service reference to your project, ensure you use https in the service address as below.

image

The code for the example is below. As with our other interfaces, in order to get the correct envelope, paper, print type and postage type please refer to our Letter Pricing API or contact us with your requirements and we will be more than happy to provide suitable values for you.

   1:  using System;
   2:  using System.IO;
   3:  using System.Text;
   4:  using PC2PaperLetterCustomerAPIExample.PC2PaperAPI;
   5:   
   6:  namespace PC2PaperLetterCustomerAPIExample
   7:  {
   8:      static class Program
   9:      {
  10:        
  11:          static void Main()
  12:          {
  13:              SendLetter();
  14:          }
  15:   
  16:          static void SendLetter()
  17:          {
  18:              //Your PC2Paper username and password go here.
  19:              string username = "yourusername";
  20:              string password = "yourpassword";
  21:   
  22:              var pc2PaperAPI = new PC2PaperAPI.LetterCustomerAPIClient();
  23:   
  24:   
  25:              //1. First we upload the files we want to attach to our letter
  26:              //   If you don't want to attach any files you can leave this step out.
  27:              // NOTE: You can also upload files async if using WCF Async methods are enables so you don't hang a UI thread for example.
  28:   
  29:              // You can add as many PDF's as you want in this way. Just remember to grab the GUID's from each submit to the server.
  30:              // below we are only attaching one.
  31:              var fileContent =
  32:                  LoadBinaryFileAsByteArray(
  33:                      @"c:\temp\testPDF.pdf");
  34:   
  35:   
  36:              string fileName = "testPDF.pdf";
  37:   
  38:              var uploadDocumentResults = pc2PaperAPI.UploadDocument(fileName, fileContent, username, password);
  39:   
  40:   
  41:              if(uploadDocumentResults.Status!="OK")
  42:              {
  43:                  // Oops an error took place.
  44:                  Console.WriteLine(uploadDocumentResults.ErrorMessages.ToString());
  45:                  return;
  46:              }
  47:   
  48:              //2. Create a letter to attach out PDF to.
  49:              var letter = new LetterForPosting();
  50:   
  51:              letter.Addresses = new LetterAddressForPosting[]
  52:                                     {
  53:                                         new LetterAddressForPosting()
  54:                                             {
  55:                                                 ReceiverName = "Tom Smith",
  56:                                                 ReceiverAddressLine1 = "Acme Co",
  57:                                                 ReceiverAddressLine2 = "2 Acme Street",
  58:                                                 ReceiverAddressTownCityOrLine3 = "Acme Town",
  59:                                                 ReceiverAddressCountyStateOrLine4 = "State",
  60:                                                 ReceiverAddressPostCode = "ZN12 9xn"
  61:                                             }
  62:                                     };
  63:   
  64:              letter.ReceiverCountryCode = 1;
  65:   
  66:              letter.Envelope = 1;
  67:              letter.Postage = 3; //UK First Class
  68:              letter.Paper = 1;
  69:              letter.Extras = 0;
  70:              letter.SenderAddress = "Peter Smith\n 72 Some Road \n Some Town \n P23 123";
  71:              letter.Pages = 1;
  72:   
  73:              // We are also putting a cover letter onto our letter. (The cover letter will always be in front)
  74:              // Leave the LetterBody line out if you do not wish to include one.
  75:              var bodyOfLetter = new StringBuilder();
  76:   
  77:              bodyOfLetter.Append("

Dear Tom

"
);
  78:   
  79:              bodyOfLetter.Append("

How are you? I'm sending you a letter via the PC2Paper API

"
);
  80:   
  81:              bodyOfLetter.Append("

Regards,
Peter

"
);
  82:   
  83:              letter.LetterBody = bodyOfLetter.ToString();
  84:   
  85:              // delete this line if you only wish to send a cover letter
  86:              letter.FileAttachementGUIDs = new string[] { uploadDocumentResults.FileCreatedGUID};
  87:   
  88:             var letterSendingResult =  pc2PaperAPI.SendSubmitLetterForPosting(letter, username, password);
  89:   
  90:              Console.WriteLine("Result:" + letterSendingResult.Status + " with letter id:" + letterSendingResult.LetterId);
  91:   
  92:          }
  93:   
  94:          static byte[] LoadBinaryFileAsByteArray(string filename)
  95:          {
  96:              var binReader = new
  97:                  BinaryReader(File.Open(filename, FileMode.Open,
  98:                                         FileAccess.Read));
  99:              binReader.BaseStream.Position = 0;
 100:              byte[] binFile =
 101:                  binReader.ReadBytes(Convert.ToInt32(binReader.BaseStream.Length));
 102:              binReader.Close();
 103:   
 104:              return binFile;
 105:          }
 106:   
 107:      }
 108:  }

 

If you have any questions, please let us know.

posted on Monday, 05 August 2013 23:01:56 (GMT Daylight Time, UTC+01:00)  #    Comments [0] Trackback
# Monday, 04 May 2009

The PC2Paper API documentation has been updated to version 3. The API now enables you to associate costs from our Letter Pricing API with letters. There is also a .NET C# example of how to use the XML RPC interface for sending PDF documents.

To find out more click here..

posted on Monday, 04 May 2009 15:27:07 (GMT Daylight Time, UTC+01:00)  #    Comments [0] Trackback
# Friday, 12 December 2008

PC2Paper have released a new Letter Pricing API which enables you to do real time price queries on letters before they are sent from your own system. You may find this useful if you are reselling the PC2Paper service and would like to provide your customers with all the pricing options available such as special delivery, different printing options, envelope selections, printing station selection etc. Given all these options the PC2Paper Letter Pricing API will give you a price for your letter which you can then use to bill your user.

For more about Letter Pricing API, please visit the API section of our web site.

posted on Friday, 12 December 2008 17:43:41 (GMT Standard Time, UTC+00:00)  #    Comments [0] Trackback
# Saturday, 18 August 2007

We have now launched a Developer section on www.pc2paper.co.uk to help developers create new applications and integrate their existing back end systems with PC2Paper's API interface, enabling easier sending of real letters from the Internet using our service.

The area consists of a chat section for developers to raise questions with us and other developers and an API documentation section. All these features will also be backed up with updates from our blog site www.pc2paper.org.

There are no sign up fees to use our API interface, it is enabled on all PC2Paper accounts as standard. If you are a business or just a novice programmer who would like to integrate with our service please visit our Developer section.

posted on Saturday, 18 August 2007 10:24:05 (GMT Daylight Time, UTC+01:00)  #    Comments [0] Trackback
# Wednesday, 09 May 2007

I had a chat with one of our technical guys Rob Forber yesterday about PC2Papers API interfaces and how he had just finished helping one our customers with a Delphi interface into PC2Paper. Now I'm not a technical person and all I know is that Delphi is another programming language and that he was excited by the accomplishment.

My interest is that we have helped another of our customers to interface their back office systems with our service.

For those who don't know PC2Paper API or Application Interface enables our customers to integrate their own back office systems (systems they use to run their businesses) and websites so that they can automatically send letters via our service. Over the coming months I will be getting Rob to write a few articles about how you can write your own interfaces into PC2Paper.

If you would like to know before then, please contact us

posted on Wednesday, 09 May 2007 16:10:03 (GMT Daylight Time, UTC+01:00)  #    Comments [0] Trackback