PC2Paper News - Developers

Using Microsoft Power Automate to send letters with PC2Paper

Rob Forber — Wed, 17 Apr 2024 07:30:11 GMT

Microsoft Power Automate is a process automation platform which makes automating repetitive tasks with little or no code..

If you have a Microsoft 365 subscription you probably already have access to Power Automate. Check your subscription or talk to your Microsoft partner for more details.

You may be able to automate processes such as picking up when addresses are added to a an Excel spreadsheet and then sending a PDF letter to that address that sits in SharePoint or in OneDrive.

You can send your letters to PC2Paper using Power Automate and our RESTFul JSON API by following these steps below.

In the example below we’ve setup a new Flow in Power Automate with a Manual Trigger. We are getting a PDF file to use, using the OneDrive for Business Action. You can use any action you’d like to provide a file for upload.

Add the Manual Trigger flow (you can use a different one here depending on the process you are after) and the OneDrive for Business Get File Content Action below it. If there is another Action you’d prefer to use you can use that instead.

Uploading a PDF

We have used the HTTP Action to upload our PDF file add this below the One Drive for Business Get File Content Action. You can search for it as HTTP in the action search box, you will want the plain HTTP adaptor.

Once added you can rename this adaptor to “Upload File”

Enter the following details

For the URI: https://test.pc2paper.co.uk/uploadfileapi.aspx if you are connecting to production enter https://www.pc2paper.co.uk/uploadfileapi.aspx
Method: Set this to POST
Headers: Add the following headers and place your PC2Paper username and password (or API keys) into them

username
password

Queries: Over here you will want to enter “fileName” and in the value field give your file a name. You can enter anything in here and you can populate this from a previous action if you have one.
Body: For the body you will want to enter the following JSON

{
"$content-type": "multipart/form-data",
"$multipart": [
{
"headers": {
"Content-Disposition": "form-data: name=\"file[data]\";filename=\"testfile.pdf\""
},
"body": @{body('Get_file_content')}
}
]
}

Where you see this tag @{body('Get_file_content')} you will want to drag in the content from the OneDrive Action that ran before this action. You select this from the little lightening bolt that appears next to the Body text box when you click in it.

Parse the results from the PDF Upload

After you have completed the previous step you will want to add a “Parse JSON” action. We will use this to parse the JSON returned by the upload file action.

Schema: Enter the following text into the schema box.

{
"type": "object",
"properties": {
"fileGuid": {
"type": "string"
},
"pages": {
"type": "integer"
}
}
}

Content: Select the content box and then select the lightening bolt that appears next to it and select (as per the image above) the Body field from the Upload File step you did previously.

Submit Letter

Now for the final Action

Add another HTTP Action after the “Parse JSON” Action.

Enter the following details

URI: https://test.pc2paper.co.uk/lettercustomerapi.svc/json/SendSubmitLetterForPosting for production you can use https://www.pc2paper.co.uk/lettercustomerapi.svc/json/SendSubmitLetterForPosting
Method: Select POST
Body: This is the same JSON example used in our JSON API example found here. Insert the below JSON into the body text

{
"letterForPosting": {
"SourceClient": "Power Automate",
"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 John, Please find my letter attached",
"IncludeSenderAddressOnEnvelope": true,
"SenderAddress": "22 Acme Acres\n Acme Town",
"YourRef": "MyRef001",
"FileAttachementGUIDs": [
"@{body('Parse_JSON')?['fileGuid']}"
]
},
"username": "username here",
"password": "password here"
}

Important: Ensure you changing the following in the JSON. You can read more about these fields here

username and password: Make sure you update these with your own this can also be your API key and API secret
FileAttachementGUIDs: For this you want to replace @{body('Parse_JSON')?['fileGuid']} with “Body fileGuid” from your Parse JSON action

Note you can find out more about postage options and country codes in the documentation found here. The postage codes can be found using our postal calculator for a quick lookup

Conclusion

That’s it. Please remember to always test your integration signing up for a free test account on https://test.pc2paper.co.uk you can top up your free test account with the following card number 5555558265554449 (this is not a real card number as it is a test environment), use made up details for the rest of the top-up process. You can then see if the letters you send come through to your test account. Remember to change the test endpoints to our live server when you are done by changing https://test to https://www .

PC2Paper JSON Interface v1.0

Rob Forber — Sun, 31 Jul 2016 17:59:08 GMT

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 three ways.

HTTP POST

This is probably one of the easiest ways to upload your file submitting your file over HTTP POST. Simple call https://www.pc2paper.co.uk/uploadfileapi.aspx?fileName=myfileName.pdf

In the headers of your HTTP POST place the following

username - This will be your PC2Paper username or API key
password - This will be your PC2Paper password or API secret

You will recieve a response that contains the GUID for your PDF and how many pages it has.

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"}

Sending a letter via PC2Paper’s SOAP API using PHP

Rob Forber — Wed, 21 Aug 2013 20:02:50 GMT

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: ?>

PC2Paper SOAP Letter API v1.0 beta

Karen Nutton — Mon, 05 Aug 2013 22:01:56 GMT

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.

PHP - http://php.net/manual/en/book.soap.php
Java - http://axis.apache.org/axis/index.html
RUBY - https://github.com/rubiii/savon

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.

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.

PC2Paper API Version 3 update

Lora Tyler — Mon, 04 May 2009 14:27:07 GMT

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

PC2Paper Letter Pricing API released

Rob Forber — Fri, 12 Dec 2008 17:43:41 GMT

PC2Paper have released a new Letter Pricing API.

PC2Paper Developers

Lora Tyler — Sat, 18 Aug 2007 09:24:05 GMT

We have now launched a Developer API section...

PC2Paper API Interfaces

Karen Nutton — Wed, 09 May 2007 15:10:03 GMT

Integrate your business letter sending with PC2Paper