Developer’s Guide

The PostalMethods Web-to-Postal API allows developers to easily send postal mail online (snail mail) from applications. The service may be accessed from all common development environments through standard SOAP libraries. Native SOAP libraries, as well as third-party libraries, are available for .NET, ASP & PHP.

This developer’s guide will go through through the steps required to send out your first web-to-postal letter. It’s assumed that you are acquainted with a development environment, and have a good grasp of building and testing applications in that environment.

Production and Development Work Modes

PostalMethods offer two optional Work Modes

1. Production Work Mode

Unsurprisingly, this work mode is meant for production use. Letters and postcards are fully processed, i.e. PostalMethods prints the mail item, prepares it to be mailed, delivers it to the postal agency and charges your account.

2. Development Work Mode

This work mode should be use while developing. This mode simulates a letter’s workflow, so you can make sure your application is ready for real life. Your letter is accepted in the same environment as a production letter and goes through the same flow, but doesn’t get physically created or handled. Feedback and errors are handled just as they are handled in Production Work Mode.

Differences between Production and Development Work Modes

1. Mail sent in Development Work Mode goes through the same process as those in Production Work Mode but are not printed and delivered to the postal agency. After being processed, the mail item’s status is set to Successfully Completed Development Work Mode (-1002). Since failures, as of this point, are very rare, you can assume your mail would have been delivered if sent as Production Work Mode. You can assume that if your mail was successfully sent in Development Work Mode, there is a good chance it would be processed successfully in Production Work Mode

2. You are not charged for mail items submitted in Development Work Mode. The system displays a price estimate but this amount is not deducted from the account balance

3. Mail sent in Development Work Mode might not go through all stages of Address Validation, which means the final recipient address may change

Setting Work Mode

Working With Multiple Users

Each account can hold multiple users. There is no additional cost involved in having multiple users. To control the account’s users, click on Account and go to the Users tab.

When in production, we recommend adding an additional user and setting it to Development Work Mode. When you make a change to your documents, application or environment, send a few test letters and postcards using the development user’s credentials and make sure everything is in order.

Identifying User’s Work Mode

Once you are logged-in to the Control Panel, look at the top-right corner of the website, where the user’s work mode setting is displayed.

Resend Mail Items Sent In Development As Production

Send mail in Development Work Mode; login to the PostalMethods Control Panel; view and verify it; and use the [Resend Live] option in the Control Panel Activity section to re-send it as Production Work Mode.

Best Practices In Designing With PostalMethods

Things To Notice When Using The PostalMethods Web Service

1. Updating letter status: You may use the status query methods to check on your letters’ status and you may have PostalMethods contact you whenever a status changes, by using “Push” Feedback. Also read Feedback By “Push” vs. “Pull”. We recommend implementing the push feedback because (a) you are notified of changes as they occur; and (b) less resources are wasted. In addition, we recommend polling for statuses in low frequency, just as a fail-safe mechanism.

2. Status codes may be added: Status codes may be added when new features become available so, in case you add codes and descriptions to your application, make sure it can handle unfamiliar codes.

3. Rendering documents to PDF is a lengthy operation: Documents sent to PostalMethods are rendered to PDF format (even if the document was originally a PDF document). In case you automatically try to GetPDF, note that the rendering process is relatively lengthy and depends on the type of document, its size, remote images to download and current system load.

4. Test using Development Work Mode: When sending mail items in Development Work Mode, they are only simulated and are not sent to the postal agency. This is a great way for testing during the development process. The Work Mode can be set as a user default or for every mail item in the Web Service method.

5. It is not always possible to cancel the delivery of a letter: Cancel Delivery is only possible before the letter was printed. Make sure your application is ready to handle failure codes when trying to cancel a delivery.

6. Sending to international addresses: When sending letters internationally, the last address line must include only the country name. Please check the valid names of countries.

7. More To Come…

8. Writing Your Code

9. Code samples are available for a variety of development environments.

10. See the Code Samples page.

11. The samples are a good starting point for creating custom code adapted to your requirements.

“Address Inside” or “Address Outside”?

PostalMethods differentiates between two types of messages:

1. Messages in which the destination address is present in the document (“address inside”).

2. Messages in which the destination address is not present in the document. Instead, the address is provided in the Web Service call that transports the document to PostalMethods (“address outside”).

When sending letters by email, you must use “address inside” Web Service users – when in doubt, use “address outside”

Address Inside

In this mode, the destination address is printed on the first page of the sent document. This mode is normally used when a document is generated from an application in which you cannot cause the Web Service call to include the destination address. It is also used when submitting messages by Email. For example, you may be sending letters from these shrink-wrapped applications.

The SendLetter() method is used for this mode, and the call looks like this (in meta-code):

SendLetter(Username => “myuser”,

Password => “mypass”,

MyDescription => “Sending a letter with Address Inside”,

FileExtension => “DOC”,

FileBinaryData => $base64Letter, /* this letter contains a

destination address on the first page */

WorkMode => “Default”)); /* defines the user’s Work Mode setting */

Limitations: When using “Address Inside”, the document containing the delivery address must be in either MS-Word (doc, docx), textual PDF or HTML formats.

Address Outside

In this mode, the destination address block on the first page of the sent document is left empty, and the destination address is transferred to PostalMethods within the Web Service call. This mode gives better control for performing address verification, and should be your default choice, if possible.

The SendLetterAndAddress() method is used for this mode, and the call looks like this (in meta-code):

SendLetterAndAddress(Username => “myuser”,

Password => “mypass”,

MyDescription => “Sending a letter with Address Inside”,

FileExtension => “DOC”,

FileBinaryData => $base64Letter /* this letter contains an

empty destination block on the first page */

WorkMode => “Default” /* defines the user’s Work Mode setting */

AttentionLine1 => “Andrea Smith

AttentionLine2 => “Accounting Dept.

Company => “ACME Inc.”

Address1 => “100 Flower Street.”

Address2 => “Suite 100”

City => “Los Angeles”

State => “CA”

PostalCode => “90010”

Country => “USA”));

How To Place Content In Letters

When designing your document, make sure you follow these guidelines.

Postal Addresses

Address (Bottom) Window

To make sure the recipient address will fully appear through the bottom window, however the paper may shift inside the envelope (see explanation below), make sure it is placed in a rectangle which top-left corner is placed 0.5” from the left paper margin and 2.042” from the top paper margin. The size of the rectangle must not exceed height 0.875” or width 3.5”.

Return Address (Top) Window

To make sure the return address will fully appear through the top window, however the paper may shift inside the envelope (see explanation below), make sure it is placed in a rectangle which top-left corner is placed 0.5” from the left paper margin and 0.5” from the top paper margin. The size of the rectangle must not exceed height 0.792” or width 3.5”.

The following image shows the measurements of correctly-placed address blocks in a document. These measurements assume the letter is located at the bottom-left part of the envelope. In case the letter shifts upwards or sideways, the postal agency machinery and the postal delivery worker will still be able to read the address.

  1. A. 0.375″
  2. B. 0.167″
  3. C. 0.792″
  4. D. 1.125″
  5. E. 0.625″
  6. F. 0.375″
  7. G. 0.125″
  1. H. 0.125″
  2. I. 0.875″
  3. J. 1.125″
  4. K. 3.667″
  5. L. 3.5″
  6. M. 4.5″
  7. N. 8.5″
Send Letters
Securely + Reliably
Send letters securely and reliably from any business application. Use for invoices, quotes, and other important business communications. Enjoy special web-form to postal features and instant notifications.
Simple Process
Easy as 1-2-3
Experience the ease of our streamlined process - developed for efficiency! You submit your document by email or API. We automatically print, collate, insert, and stamp your letter. Your letter is delivered via standard postal service.
Pay As You Go
No Fuss. No Obligations.
Register for free with no obligations! Evaluate the service as long as you need. Once you are ready, set up our user-friendly pay-as-you option to use our service. No fuss. No on-going commitment. Just plain easy!