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:

Considerations for the Electronic Delivery API

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

  2. Retrieve the shipmentId value from the Create PB Returns Label response. The Electronic Delivery API requires the value in the request.

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

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

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

  6. The API uses the email template described below.

  7. You cannot insert HTML markup into the email.

  8. 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 (+)

    +

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

  10. Electronic delivery counts toward any limits on the number of reprints that can be made for a given shipmentId.

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

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.

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:

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

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