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 is BASE64, 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.	salutation 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.	orderId openingParagraph
Shipping Instructions (Shipping Label Only)	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.	shippingInstructions
QR Code Instructions (QR Codes Only)	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.	returnWebsiteURL
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.	infoParagraph
Return Information	This section includes the following: A line with the RMA number. This appears only if you pass the number in templateData.rmaNumber. Any custom return details you want to add. To add custom return details, use templateData.returnDetails. The carrier tracking URL. (Shipping Label Only). This line cannot be edited. The QR Code. (QR Codes Only). This line cannot be edited.	rmaNumber returnDetails
Closing	Any custom closing information you want to send. To send custom closing information, use templateData.closingParagraph.	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 `shipmentId` value from the response of the Create Shipment API call.

Query Parameter¶

Name	Description
carrier	Required. The carrier. Set this to `PBCS`.

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 application/json.

Accept-Language

Language and country code. Default: en-US

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	Template Data Object	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 `recipientName` is also sent in the request. Maximum: 1024 characters	Salutation
recipientName	String	The customer’s name as it should appear in the email salutation. If you also send the `salutation` field in the request, the salutation appears before the recipient name. Otherwise only the name appears. If you do not send this field, the email leaves out the salutation. Maximum: 1024 characters	Salutation
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	Opening
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 `\n` escape character. Maximum: 1024 characters	Opening
shippingInstructions	String	Custom shipping instructions to replace the default Shipping Instructions. You can enter line breaks in the custom text by using the `\n` escape character. Maximum: 1024 characters	Shipping Instructions
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	Return Website URL
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 `\n` escape character. If you do not use this field, no custom text appears in this section of the email. Maximum: 1024 characters	Info
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 `returnDetails`. Maximum: 1024 characters	Return Information
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 `\n` escape character. If you do not use this field, no custom return details appear. Maximum: 1024 characters	Return Information
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 `\n` escape character. If you do not use this field, no custom closing information appears. Maximum: 1024 characters	Closing Section

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.

Character	HTML Code
Apostrophe (`'`)	`'`
Equal Sign (`=`)	`=`
Plus Sign (`+`)	`+`