Electronic Delivery API¶
HTTP Request¶
POST /v1/shipments/{shipmentId}/email?carrier=PBCS
Summary¶
This operation delivers a label or QR code through email. The operation is available for PB Returns shipments, except for shipments created with APAC Services. The API provides fields to customize the email. If you send a QR code, the email will include a list of nearby postal facilities.
Note
Shipments created with APAC Services are not supported for electronic delivery.
Onboard with Electronic Delivery¶
A merchant must enroll with electronic delivery to use this API. To enroll a merchant with electronic delivery:
Onboard the merchant to use PB Delivery. See Onboard with PB Delivery and PB Returns.
Contact either your implementation manager or Pitney Bowes Client Support (GEC-TechSupport@pb.com) and ask that the merchant be enabled to use this API.
Considerations for the Electronic Delivery API¶
Before calling this API, you must create a label or QR code through the Create Returns Label API. The label or QR code must use the following format:
A label must use the PDF format
A QR code must use the GIF format
For content types compatible with the above, see PB Delivery Labels. The content type determines whether the Electronic Delivery API sends a URL or an attachment. If the content type is
URL
, the API sends the URL in the email body. If content type isBASE64
, the application will render it and send it as an attachment.Retrieve the
shipmentId
value from the Create PB Returns Label response. The Electronic Delivery API requires the value in the request.Before going to Production, test the Electronic Delivery API in Sandbox to ensure emails display as expected. When you create emails in Sandbox, the API will insert text in the body to label the email as a test email.
When you use this API to send a label, the email includes default instructions on how to ship the parcel. You can optionally override the default instructions with custom instructions.
When you use this API to send a QR code, the email will include:
Instructions on how to use the QR code to print a label.
A list of postal facilities near to the recipient.
The API uses the email template described below.
You cannot insert HTML markup into the email.
If you choose to write custom content in the email, use HTML codes for the following characters:
Character
HTML Code
Apostrophe (
'
)'
Equal Sign (
=
)=
Plus Sign (
+
)+
The API sends certain URLs by default. To insert additional URLs into the email, you must have additional authorization on top of the enrollment in electronic delivery. For authorization to insert custom URLs into the email, contact Client Support at ClientSupportTechServices@pb.com.
Electronic delivery counts toward any limits on the number of reprints that can be made for a given
shipmentId
.Carrier limits on how long a label is available via URL apply.
Template for Sending Emails¶
When you invoke the Electronic Delivery API, the API sends an email based on the template described here. You have the option of customizing the email through the templateData object in the request. If the email sends a QR code, the QR code appears in the Return Information section of the template. The template includes the following types of content:
Default text
Insertion points for custom text within the default text
Replaceable text. You can replace certain default text with custom text.
The following table describes the sections of the template in sequence. Some sections apply only to shipping labels or only to QR codes. They are marked accordingly.
Template Section |
Description |
The templateData Fields that Affect this Section |
---|---|---|
Salutation |
The value of templateData.salutation followed by the value of templateData.recipientName. |
|
Opening |
Default opening text. If you pass templateData.orderId in the request, the opening text mentions the order ID. You can optionally override the default opening text with custom text. To do so, send the custom text in templateData.openingParagraph. To include the order ID, you must explicitly mention it. |
|
Shipping Instructions
|
Default instructions on how to package the return, print the label, and bring it to a postal center. This applies only if you are sending a label. You can optionally override the default instructions with custom instructions. To do so, send the custom instructions in templateData.shippingInstructions. |
|
QR Code Instructions
|
This section is not editable and is required by USPS if you are sending a QR code. This section applies only if you are sending a QR code. |
NA |
Return Website URL |
A merchant-provided URL for tracking the return, as sent in templateData.returnWebsiteURL. You must be enabled to use this field. |
|
Info |
Any custom text you want to add before the Return Information section, such as additional order information. To include custom text here, use templateData.infoParagraph. |
|
Return Information |
This section includes the following:
|
|
Closing |
Any custom closing information you want to send. To send custom closing information, use templateData.closingParagraph. |
Request URLs¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}/email?carrier=PBCS
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/shipments/{shipmentId}/email?carrier=PBCS
Path Parameter¶
Name |
Description |
---|---|
shipmentId |
Required. The shipment ID that Pitney Bowes issued when shipment label was generated. This is the |
Query Parameter¶
Name |
Description |
---|---|
carrier |
Required. The carrier. Set this to |
Request Headers¶
Name |
Description |
---|---|
Authorization |
Required. OAuth token generated using the Generate an OAuth Token API. |
Content-Type |
Required. The media type of the request entity. Set this to |
Accept-Language |
Language and country code. Default: |
Request Elements¶
Note that only the to
array is required. All other fields are optional.
Name |
Data Type |
Description |
---|---|---|
to |
Array[Object] |
Required. One or two email addresses to which to send the label. Each object in the array is an address. The array requires at least one object and takes a maximum of two. Maximum: 2 objects |
to.address |
String |
The email address. |
to.name |
String |
The name associated with the email address. |
carbonCopy |
Array[Object] |
An additional email address to which to send the label. You can enter one email address. The array takes a maximum of one object. This field is optional. Maximum: 1 object |
carbonCopy.address |
String |
The email address. |
carbonCopy.name |
String |
The name associated with the email address. |
templateData |
Customizes the email. This field is optional. |
Template Data Object (Request Only)¶
This object customizes the email. If you include this object, use HTML code for the characters listed in this table, above. Each field in the object is optional.
Name |
Data Type |
Description |
Affects this Section in the Email |
---|---|---|---|
salutation |
String |
The greeting to precede the recipient’s name, such as “Hi”, “Hello”, or “Dear”. This will not appear unless Maximum: 1024 characters |
|
recipientName |
String |
The customer’s name as it should appear in the email salutation. If you also send the Maximum: 1024 characters |
|
orderId |
String |
The merchant’s identifier for the order. This appears in the Opening, if the default Opening is used. If you leave out this field, the Order ID does not appear in the default Opening. Maximum: 1024 characters |
|
openingParagraph |
String |
Custom text to replace the Opening’s default text. This will completely replace the default text, including the inserted order ID. If you want to include the order ID, you must enter it directly in the custom text. You can enter line breaks in the custom text by using the Maximum: 1024 characters |
|
shippingInstructions |
String |
Custom shipping instructions to replace the default Shipping Instructions. You can enter line breaks in the custom text by using the Maximum: 1024 characters |
|
returnWebsiteURL |
String |
A merchant-provided URL for tracking the return. If provided, the URL appears in the Return Website URL section of the email. You must be enabled to use this field. Maximum: 1024 characters |
|
infoParagraph |
String |
Additional custom text that appears after the shipping and tracking instructions but before the return information. You can enter line breaks in the text by using the If you do not use this field, no custom text appears in this section of the email. Maximum: 1024 characters |
|
rmaNumber |
String |
The RMA number used as a tracking number. This appears as a separate line in the Return Information section. If you leave this field out, the email does not include the RMA number, though you could add it as custom text in the other fields, such as Maximum: 1024 characters |
|
returnDetails |
String |
Additional custom information about the return. This appears in the Return Information section of the email. You can enter line breaks by using the Maximum: 1024 characters |
|
closingParagraph |
String |
Any custom closing information you want to send. This appears after the inline Label or QR Code (if applicable). You can enter line breaks in the text by using the Maximum: 1024 characters |
Response Elements¶
Name |
Data Type |
Description |
---|---|---|
messageId |
String |
The identifier for the email message. Use this identifier if you need to contact Client Support. |
shipmentId |
String |
The identifier that you sent in the request. This identifies the PB Returns label within the Pitney Bowes system. |
Sample Request¶
curl -X POST ".../v1/shipments/{shipmentId}/email?carrier=PBCS" \
-H "Authorization: Bearer <oauth_token>"
-H "Content-Type: application/json" \
-H "Accept-Language: en-US" \
-H "Content-Type: application/json" \
-d '
{
"to" : [ {
"address" : "mary@example.net",
"name" : "Mary"
},{
"address" : "john@example.net",
"name" : "John"
} ],
"carbonCopy" : [ {
"address" : "kathryn@example.net",
"name" : "Kathryn"
} ],
"templateData" : {
"orderId" : "12345678-234568",
"recipientName" : "Mary Jones",
"returnWebsiteURL": "http://widgets.example.com/shop/order/return/12345678-234568",
"rmaNumber": "RMA12345678"
}
}'
Sample Response¶
{
"messageId": "abcdefghijklmnopqrstuv",
"shipmentId": "NGST2200123456784836"
}
Error Codes¶
For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.