E POSTBUSINESS API Send-API Reference. Version Note: For the latest valid version, refer to V (in German only) Status: 02/2018

Transcription

1 E POSTBUSINESS API Send-API Reference Version : For the latest valid version, refer to V (in German only) Status: 02/2018

2 Imprint Software and documentation are protected by copyright and may not be copied, reproduced, stored, translated, or otherwise reproduced without the written approval of the Deutsche Post AG. This also applies to excerpts All rights reserved. The Deutsche Post AG has the right, without prior notice, to make changes or to further develop the documents/software for the purposes of technical progress. Trade names are used without warranty of free usability All trade names and product names are trademarks or registered trademarks of their respective owner Deutsche Post AG Send-API Reference

3 Content 1 Introduction 1 2 Basic concepts 3 3 API resources Creating an E-POST letter draft with metadata, cover letter and attachments Send draft Deleting an draft Query price of a draft Query price information 25 4 Metadata Metadata for delivery options Metadata for pricing information Metadata for creating a E POST letter draft Metadata after creating a E POST letter draft Metadata for the error output 39 5 Print Production Requirements for E POST letters Delivery with cover page Delivery without cover page Print sizes and materials Requirements for PDF files PDF settings for high print quality 49 Send-API Reference

4 1 Introduction 1 Introduction Attention Outdated Version Version of this documentation is outdated. We have added important information. The interface has not been changed. Nevertheless, the current valid version is the German version V With this Reference guide you will be able to integrate the Send API into your business application, enabling users of your application to send E POST letters directly from within their daily working environemnt. Overview Summary Application The Send API is part of the E POSTBUSINESS API, the REST interface of the E POST system for software suppliers. With the E POSTBUSINESS API you are able to integrate E POST functions such as sending E-POST letters as electronic communication, or physical mail, directly from withinyour software. This documentation describes how to use the Send API to send E POST letters from within your application. Many advantages of the E POST, which until now have only been available through the E POST portal, are now available from within your own application, granting users to fully benefit from the functions of the E POST, and the convenience of your application. The Send API comes as REST programming interface, which allows you to directly address the E POST system. To integrate E POST features in any application, you need to be registered as E POST customer, either as E POST business or private customer. The available functions via the Send API are in accordance with the corresponding E POST portal functions. The invoicing of the services being used via the Send API will be demanded directly from the specific customers according to their signed rate or contract in the E POST portal. For legal reasons, you have to inform your customers about this additional contractual relationship between the E POST of Deutsche Post, and you as business application provider. The trilateral relationship between you as Send API partner, the E POST, and the private customer or business customer, is the basis for the cooperation described in this document. The Send API is a REST API you can use to implement different functions in your application (e.g. sending and managing E-POST letters ). Integrate the E POSTBUSINESS API into your system to easy business communication with your customers. In the first stage, the following functions are available: Writing, deleting or saving drafts of an E POST letter. Sending E POST letters to an electronic E POST address. Sending E POST letters to an postal address within Germany (meaning: printing, cuverting and deliverying). Sending E POST letters abroad, outside Germany, is not yet possible with the E POSTBUSINESS API. Send-API Reference 1

5 1 Introduction Process Audience To use the Send API, you have to consider two essential steps in your implementation: First, you need to call the Login API for authentication of the E POST customer who uses E POST services via your application (see Login-API Reference). In the next step you have to call the the Send API with the received authorization information from the Login API. This API reference is intended for developers who have knowledge in the following subjects: HTTP and HTTPS REST JSON OAuth 2.0 Send-API Reference 2

6 2 Basic concepts 2 Basic concepts This section explores the basic concepts of the Send API. Request and response Request and response invocations have been implemented according to the HTTP standard. In addition, note the following requirements: UTF-8 For the processing of strings UTF-8 encoding is required. Dates and Times All dates and times are in ISO 8601 format (e.g T17:05:39+02:00). HTTPS encryption The Send API only uses HTTPS connections. Therefore the identification data of the participants are protected throughout the whole communication process. Verify the correctness of the certificate on the other side with every call. Authentication with OAuth 2.0 JSON data format REST API endpoint HTTP status codes OAuth 2.0 is an open protocol that permits a standardized way of authorization for third-party desktop, web and mobile applications on resources with limited access (for more information, see The OAuth 2.0 protocol is the basis for authentication and authorization to access the Send API. Any additional information about authentication is described in Login-API Reference. For the exchange of data between your application and the E POST system the JSON data format is used. The following REST endpoint is used by the Send API: (Production) (Test and integration environment) Responses are returned in HTTP status code syntax. Each additional information is returned in the body of the response and formatted as JSON document. In addition to the resource specific response codes the following general response codes are returned 401 Unauthorized There was no correct authorization information submitted. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Send-API Reference 3

7 2 Basic concepts Possible values for errorcode: invalid_token The access token is missing, has expired or is invalid. 405 Method Not Allowed The HTTP method is not supported. 415 Unsupported Media Type The submitted Content-Type does not correspond to the expected value. 500 Internal Server Error Internal processing error 503 Service Unavailable Internal processing error Send-API Reference 4

8 3 API resources ǀ Creating an E-POST letter draft with metadata, cover letter and attachments 3 API resources The Send API uses REST resources to provide various delivery and sub-processes to your application. The delivery process requires two types of resources: Letters A letter is a E POST letter, that is to be delivered. You can create a letter with the POST method. A newly created letter will be saved to the Drafts folder. Once a letter has been sent, you cannot change it anymore, apart from a few exceptions such as the label. Deliveries Deliveries are the actual transmission operations. A POST on the deliveries ressource ensures that a new delivery is carried out. In doing so you reference an existing letter, which is still in the draft status. The delivery ensures that each recipient receives an own version of the letter and that the letter is moved from the Drafts folder to the Sent folder. Parallel delivery You can parallelize the API communication to optimize the performance of your application. It is possible to use up to three parallel threads for the delivery. Usable Resources 3.1 Creating an E-POST letter draft with metadata, cover letter and attachments: POST / letters 3.2 Send draft: POST /deliveries 3.3 Deleting an draft: DELETE /letters/{letterid 3.4 Query price of a draft: POST /postage-info 3.5 Query price information: POST /postage-info 3.1 Creating an E-POST letter draft with metadata, cover letter and attachments With POST /letters you create an E POST letter draft including metadata, cover letter and attachments. A draft is composed of the following parts: Metadata, in the form of a JSON object, an optional cover letter, at least one attachment in PDF format. The draft will be stored in the Drafts folder after you created it. Scope For the use of the resource you need the scope create_letter. Send-API Reference 5

9 3 API resources ǀ Creating an E-POST letter draft with metadata, cover letter and attachments When you create a draft you access a resource of Mailbox API, which is why the URLstructure is different: mailbox.api.epost.de Request URL structure Production POST Test and integration environment POST Structure of the message HTTP header for the entire message The multipart/mixed message contains the metadata as JSON as the first part. It is followed by the optional cover letter and at least one attachment. x-epost-access-token (required) This header passes the token that authorizes your application with the permission of the owner of the specified E POST user account. Content-Type (required) multipart/mixed; boundary Setting this value indicates that the message consists of several parts (see HTTP header for the metadata Content-Type (required) application/vnd.epost-letter+json The metadata of the E POST letter in JSON-format. Depending on whether you use the Scope send_letter or send_hybrid the metadata differs (see 4.3 Metadata for creating a E POST letter draft). When a draft is created there is always a envelope JSON object created. It is optional for you, whether you create the envelope object with your application. If the object is not supplied, an envelope object is created with empty fields. In addition, in case of a missing lettertype object, it is filled with default values. HTTP header for the optional cover letter Content-Type (required) Optionally, you can transmit a cover letter text. the following requirements The cover letter must be set in second place. The cover letter must be transmitted in the following format: text/html The cover letter is in HTML-format. The following HTML tags are allowed: b, big, blockquote, body, br, center, cite, code, col, colgroup, dd, div, dl, dt, em, fieldset, font, h1, h2, h3, h4, h5, h6, hr, i, img, label, legend, li, map, noscript, ol, p, Send-API Reference 6

10 3 API resources ǀ Creating an E-POST letter draft with metadata, cover letter and attachments pre, samp, small, span, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, u, ul. It is possible to use individual HTML elements without enclosing them into a complete HTML document with the elements <html>, <head> or <body>. Example: Cover letter in HTML format <html> <head> <meta http-equiv="content-type" content="text/ html;charset=iso " /> </head> <body> <br/> <br/> text <br/> <br/> </body> </html> HTTP header for an attachment or multiple attachments Content-Type (required) application/pdf The parameter specifies the E POST letter attachment in PDF format. There has to be at least one attachment. Multiple attachments can be divided in different documents of the type application/pdf. Restrictions: A maximum of 99 PDF files is allowed. The sum of the file sizes of the PDF documents must not exceed 20 MB per E POST letter. Test procedure for file sizes: The size of the individual attachments will be checked when creating the draft. The sum of all attachments is checked only when sending the created draft. Content-Disposition (required) form-data; filename="<filename of attachment>.pdf"; name="file" The parameter has to be of the type multipart/form-data, the attribute filename specifies the file name of the attachment, the attribute name="file" has to be set. Send-API Reference 7

11 3 API resources ǀ Creating an E-POST letter draft with metadata, cover letter and attachments By using the header Content-Disposition a name for the PDF files can be proposed. For this purpose the attribute filename is used. The value of this attribute must end in the.pdf extension in order to correctly show the E POST letter in the Portal. Should this not be the case, the proposed name is changed, e.g. from unknown to unknown.pdf or from unknown.jpg to unknown.pdf. If there is no name for one or several PDF file(s) provided, the name attachement_x.pdf is used, where x stands for an automatically assigned number by the system. Content-Transfer-Encoding (optional) base64 With this parameter you specify that you transmit a base64 encoded attachment. For more information, refer to Encoding.html. If you do not specify the header, the default binary will be used (i.e. the raw data of the PDF file will be transferred in binary format). Example (physical E POST letter) POST HTTP/1.1 X-CorrelationId: WAF_1_VD5j8wrTAAwAACk2juoAAAAC x-epost-access-token: <E-POST Access Token> Content-Type: multipart/mixed; boundary="boundary_8d16804cd7f91e6" Host: mailbox.api.epost.de --Boundary_8d16804cd7f91e6 Content-Type: application/vnd.epost-letter+json { "envelope": { "lettertype": { "systemmessagetype": "hybrid", "recipientsprinted": [ { "addressaddon": "3rd floor", "city": "", "company": "Deutsche Post AG", "firstname": "Max", "housenumber": "14", "lastname": "Mustermann", "postofficebox": "", "salutation": "Mr", "streetname": "Musterstr. 3", "title": "Dr.", "zipcode": "53115" ], "sender": { "displayname": "Max Mustermann", "epostaddress": "max.mustermann@musterfirma.epost.de", "subject": "Test successful" --Boundary_8d16804cd7f91e6 Send-API Reference 8

12 3 API resources ǀ Creating an E-POST letter draft with metadata, cover letter and attachments Content-Type: text/html Dear Sir or Madam,<br/><br/>We are glad to inform you that the test was successful.<br/><br/>your E-POST Team --Boundary_8d16804cd7f91e6 Content-Type: application/pdf Content-Disposition: form-data; filename="test.pdf"; name="file" <test.pdf in binary format> --Boundary_8d16804cd7f91e6-- Example (electronic E POST letter) POST HTTP/1.1 X-CorrelationId: WAF_1_VD5j8wrTAAwAACk2juoAAAAC x-epost-access-token: <E-POST Access Token> Content-Type: multipart/mixed; boundary="boundary_8d c21df6" Host: mailbox.api.epost.de --Boundary_8d c21df6 Content-Type: application/vnd.epost-letter+json { "envelope": { "lettertype": { "systemmessagetype": "normal", "recipients": [ { "displayname": "Max Mustermann", "epostaddress": "max.mustermann@musterfirma.epost.de" ], "sender": { "displayname": "Miriam Musterfrau", "epostaddress": "miriam.musterfrau@musterfirma.epost.de", "subject": "Test erfolgreich" --Boundary_8d c21df6 Content-Type: text/html Dear Sir or Madam,<br/><br/>We are glad to inform you that the test was successful.<br/><br/>your E-POST Team --Boundary_8d c21df6 Content-Type: application/pdf Content-Disposition: form-data; filename="test.pdf"; name="file" <test.pdf in binary format> --Boundary_8d c21df6-- Send-API Reference 9

13 3 API resources ǀ Creating an E-POST letter draft with metadata, cover letter and attachments Response For additional possible status codes see HTTP status codes on page Created The content was saved successfully. HTTP header HTTP body Content-Type: application/json Location: <URI to the created E POST letter> The body contains a JSON object with the E POST letter metadata (4.4 Metadata after creating a E POST letter draft) Bad Request The request is incorrect. This might be due to the following reasons: No multipart/mixed; boundary request Missing or invalid metadata No file body part A part of the request has an invalid Content-Type Too many attachments (>99) Forbidden The format of the cover letter is invalid (invalid HTML) There is no permission to access the resource. The error message can occur for the following reasons: 1. The attachment has been rejected. In errorcode you find the exact cause. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for errorcode: CORE_035: The total size of the attachments is exceeded. CORE_038: The total number of attachments is exceeded READ_001: Malware has been found. 2. The scope is not correct. Send-API Reference 10

14 3 API resources ǀ Creating an E-POST letter draft with metadata, cover letter and attachments 413 Example: Response in the case of success Request Entity Too Large The HTTP request is larger than 25 MB, or the letter, generated from different parts, is greater than 20 MB. In the case of success the answer is for both scopes send_hybrid and send_letter built the same way: HTTP/ Created Location: 23d2c6f0-05d0-11e4-94a a87 Content-Type: application/json { "id": "23d2c6f0-05d0-11e4-94a a87", "_links": { "coverletter": { "href": " 23d2c6f0-05d0-11e4-94a a87/coverletter", "send": { "href": " "method": "POST", "headers": [ { "name": "Content-Source", "value": " 23d2c6f0-05d0-11e4-94a a87" ], "postage-info": { "href": " "method": "POST", "headers": [ { "name": "Content-Source", "value": " 23d2c6f0-05d0-11e4-94a a87" ], "self": { "href": " 23d2c6f0-05d0-11e4-94a a87", "attachments": { "href": " 23d2c6f0-05d0-11e4-94a a87/attachments" Send-API Reference 11

15 3 API resources ǀ Send draft Example: Response in the event of an error HTTP/ Forbidden Content-Type: application/json;charset=utf-8 { "errorcode": "CORE_035", "description": "Engine Failure: Bad Request" 3.2 Send draft POST /deliveries sends a E POST letter draft. Scope Depending on the type of the E POST letter you set the scope to send_hybrid (physical delivery) or send_letter (electronic delivery). In addition you set the scope create_letter to create the draft. It is possible to specify several scopes simultaneously (see Login-API Reference Request login page). identity level Private customers need for the delivery of an electronic E POST letter the identity level Premium or Premium+ (parameter id_level see Login-API Reference: Request access token). Request Production POST Test and integration environment POST HTTP header x-epost-access-token (required) This header passes the token that authorizes your application with the permission of the owner of the specified E POST user account. Content-Source (required) Contains the URI that refers to the draft to be sent (available via the object _links.self, see 4.4 Metadata after creating a E POST letter draft). Content-Type (optional) application/vnd.epost-dispatch-options+json The header specifies that delivery options are defined. Depending on the defined scope there is a different effect: Physical E POST letter Header present: the delivery options must be specified with a JSON object. Header not present: the default delivery options are used. Send-API Reference 12

16 3 API resources ǀ Send draft Electronic E POST letter The header Content-Type: application/vnd.epost-dispatch-options+json has no effect. Recommendation: Do not specify the parameter. Otherwise an error message is displayed and the processing stops. Background: Electronic E POST letters have no delivery options. HTTP body Optional: In the HTTP body you specify delivery options (see 4.1 Metadata for delivery options). Delivery options are only considered when sending physical E POST letters (scope send_hybrid). Please note that you do not specify the header Content-Type: application/ vnd.epost-dispatch-options+json when sending without delivery options. Example without delivery options x-epost-access-token: <E-POST Access Token> POST /deliveries HTTP/1.1 Host: send.api.epost.de Content-Source: a Example with delivery options x-epost-access-token: <E-POST Access Token> POST /deliveries HTTP/1.1 Host: send.api.epost.de Content-Source: a Response For additional possible status codes see HTTP status codes on page Continue The status message indicates that the initial part of the request was received from the server and is not yet been rejected. In this case, you must wait until a final success or error message is returned by the server. No Content In the case of success the answer has the status 204 and an empty HTTP body. The draft has been sent successfully. The sent E POST letter is saved in the Draft folder. Send-API Reference 13

17 3 API resources ǀ Send draft 403 Forbidden There is no permission to access the resource. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: not_billable The process may not be charged, because the respective customer account is either locked or has not enough credits. insufficient_scope The access token does not have the needed privileges. malware_detected The letter contains malware. insufficient_id_level The user, represented by the access token, does not have the needed identity level to send E POST letters. The call of the function requires a higher identity level. For more information, see the Login-API Reference Identity Levels and E POST Functions. 404 Not Found At the specified URI in the Content-Source header no resource could be found. 406 Not Acceptable An Accept header is missing or has been specified and has a value other than application/json. 409 Conflict The request was made under wrong assumptions. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: invalid_letter The referenced letter can not be processed. Possible causes include: invalid address too many pages invalid cover letter (unsupported HTML tags) cover letter not printable (formatting or conversion error) Send-API Reference 14

18 3 API resources ǀ Send draft invalid attachment attachment not printable (formatting or conversion error) violated blocked areas on the edge of the page or in the address field See 5.5 PDF settings for high print quality for detailed information about possible errors in the delivery of PDF files. For this error there is a description in the form of a JSON object (see 4.5 Metadata for the error output ): error (string) invalid_letter error_description (string) Invalid letter content. error_details (list) The following values specify the error: invalid_type Attachment is not a valid file. : Bad file too_many_pages Letter has too many pages. : The E POST letter contains too many pages. incorrect_format Attachment has an incorrect format. : The attachment is in a incorrect format restriction_mark_violated Content violates restriction mark areas in attachment. : Blocked areas are violated, see 5. Print Production Requirements for E POST letters. max_pages (number) Number of allowed pages num_pages (number) Number of actual pages description (string) not_draft Error description The referenced E POST letter is not a draft. invalid_recipient The recipient specified in the referenced letter is not correct or unknown. too_many_attachments The number of attachments included in the referenced letter is greater than 99. invalid_media_type The referenced letter contains an attachment with an unsupported type. Supported is only application/pdf. Send-API Reference 15

19 3 API resources ǀ Deleting an draft invalid_meta_data The metadata of the letter is invalid. Possible causes: An recipient must contain either a street name or a mailbox An recipient must not simultaneously contain street name and mailbox The subject is invalid (e.g. it is too long: for UTF-8 encoding a maximum of 1000 characters is allowed) letter_size_limit_exceeded The referenced letter (including attachment) is larger than 20 MB insufficient_recipient_id_level The recipient of an electronic E POST letter does not have the required identity level (see Login-API Reference: Identity Levels and E POST Functions). Example: Response in the event of an error HTTP/ Conflict Content-Type: application/json;charset=utf-8 { "error": "invalid_letter", "error_description": "Invalid letter content.", "error_details": [ { "description": "PDF has too many pages.", { "description": "Attachment has an incorrect format.", { "description": "Attachment is not a valid file." ] The SEND API responses contain the HTTP-Header X-CorrelationId. Save the X- CorrelationId to invoke the API call to a later point in time. 3.3 Deleting an draft DELETE /letters/{letterid deletes an E POST letter draft. To delete an E POST letter or an E POST letter draft, you have two possibilities: to move the E POST letter into the trash folder, or to irreversibly delete the E POST letter from the trash folder. Send-API Reference 16

20 3 API resources ǀ Deleting an draft When deleting an E POST letter draft, you access a resource of the Mailbox API, which is why the URL-structure is different: mailbox.api.epost.de. Moving the E POST letter into the trash folder Deleting an E POST letter occurs in a two step procedure: moving the E POST letter into the trash folder, and deleting it from there afterwards. The applying URL structure varies depending on which step you execute the delete event, that is moving it, or irrevocably deleting it. 1. Use the ressource DELETE /letters/{letterid, to move the E POST letter into the folder trash. The E POST letter can stil be reopen by using the ressource GET / letters/{letterid. In this case, an other DELETE Link will be provided, for more information, see 4.4 Metadata after creating a E POST letter draft. 2. To conclude the deletion procedure, you have to irrevocably remove the E POST letter from the trash folder. Use therefore the ressource letterid of the E POST letter to be deleted, and use, like in the first step, the following DELETE link: DELETE /trash/{letterid. Deleting E POST letters directly Scope You can irrevocably delete an E POST letter from any folder in a single step. Use therefore the ressource DELETE /letters/{letterid and the HTTP-Header x-skip-trash to irrevocably delete an E POST letter. To use the resource you need the scope delete_letter. Request Produktionsumgebung DELETE mailbox.api.epost.de/letters/{letterid Test- und Integrationsumgebung DELETE mailbox.api.epost-gka.de/letters/{letterid URL-Struktur (deleting from the trash folder) Production environment DELETE mailbox.api.epost.de/trash/{letterid Test and integration environment DELETE mailbox.api.epost-gka.de/trash/{letterid Path parameter letterid (required) Identifier of the E POST letter. Send-API Reference 17

21 3 API resources ǀ Deleting an draft HTTP-Header x-epost-access-token (required) This header passes the token that authorizes your application with the permission of the owner of the specified E POST user account. x-skip-trash (optional) With the header x-skip-trash you control if you move the E POST letter to the trash folder or irrevocably delete it. Select the value true in the x-skip-trash header to irrevocably delete the E POST letter. Select the value false in the x-skip-trash header to move the E POST letter into the trash folder. If you select an other value than true, false, the server answers with HTTP status code 400 Bad Request. Sample: Moving into the trash folder DELETE /letters/f6b8dbb9-e71c e16-a4473bc6d572 HTTP 1.1 Host: mailbox.api.epost.de x-epost-access-token: <E-POST Access Token> Sample: irrevocably deleting by avoiding the trash folder DELETE /letters/f6b8dbb9-e71c e16-a4473bc6d572 HTTP 1.1 Host: mailbox.api.epost.de x-epost-access-token: <E-POST Access Token> x-skip-trash: true When directly deleting the E POST letters without moving them beforehand to the trash folder, the letters will be deleted and cannot be invoked any longer. The deleted E POST letters cannot be opened from the E-POST Portal. URL structure (move to trash folder) Production DELETE mailbox.api.epost.de/letters/{letterid Test and integration environment DELETE mailbox.api.epost-gka.de/letters/{letterid URL structure (delete from trash folder) Production DELETE mailbox.api.epost.de/trash/{letterid Test and integration environment DELETE mailbox.api.epost-gka.de/trash/{letterid Send-API Reference 18

22 3 API resources ǀ Deleting an draft Path parameter HTTP header letterid (required) Identifier of the E POST letter. x-epost-access-token (required) This header passes the token that authorizes your application with the permission of the owner of the specified E POST user account. Example DELETE /letters/f6b8dbb9-e71c e16-a4473bc6d572 HTTP 1.1 Host: mailbox.api.epost.de x-epost-access-token: <E-POST Access Token> Response For additional possible status codes see HTTP status codes on page No Content This status code appears at both stages of the delete process: 1. Use of DELETE /letters/{letterid: The E POST letter has been moved to the trash folder. The status code will also be returned if the E POST letter has already been moved by a previous call (idempotent); in this case, no further version of the E POST letter is going to be created in the trash folder. 2. Use of DELETE /trash/{letterid: The E POST letter has been successfully deleted from the trash folder. This answer guarantees that the E POST letter does no longer exist in the trash folder. If the E POST letter was not located in the trash folder, the status code is also returned even though the deletion has been ineffective (idempotent). Forbidden The E POST letter could not be deleted. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for errorcode: READ_002 The E POST letter is an unread receipt of a registered letter (it can principally not be deleted) READ_003 Missing access rights Send-API Reference 19

23 3 API resources ǀ Query price of a draft 404 Not Found The E POST letter could not be found, because an invalid folderid was referenced. 3.4 Query price of a draft POST /postage-info returns the price of a saved E POST letter draft. Scope You need the following scope(s) for the price query: send_letter: Query the price for an E POST letter that is to be sent electronically. send_hybrid: Query the price for an E POST letter that is to be sent physically. Request URL structure Production POST Test and integration environment POST HTTP header x-epost-access-token (required) This header passes the token that authorizes your application with the permission of the owner of the specified E POST user account. Content-Source (required) Contains the URI that refers to the draft to be sent (available via the object _links.self, see 4.4 Metadata after creating a E POST letter draft). Content-Type (optional) application/vnd.epost-dispatch-options+json The header specifies that delivery options are defined. Depending on the defined scope there is a different effect: Physical E POST letter Header present: the delivery options must be specified with a JSON object. Header not present: the default delivery options are used. Electronic E POST letter The header Content-Type: application/vnd.epost-dispatch-options+json has no effect. Recommendation: Do not specify the parameter. Otherwise an error message is displayed and the processing stops. Background: Electronic E POST letters have no delivery options. Send-API Reference 20

24 3 API resources ǀ Query price of a draft HTTP body Optional: In the HTTP body you specify delivery options (see 4.1 Metadata for delivery options). Delivery options are only considered when sending physical E POST letters (scope send_hybrid). Please note that you do not specify the header Content-Type: application/ vnd.epost-dispatch-options+json when sending without delivery options. Example with delivery options POST HTTP/1.1 x-epost-access-token: <E-POST Access Token> Content-Type: application/vnd.epost-postage-info+json Host: send.api.epost.de { "letter": { "type": "hybrid", "messagetype": "hybrid", "size": 1, "options": { "color": "colored", "coverletter": "included", "registered": "addresseeonlywithreturnreceipt" Example without delivery options POST HTTP/1.1 x-epost-access-token: <E-POST Access Token> Content-Source: daf4be10-05cb-11e4-94a a87 Host: send.api.epost.de Response 200 OK The price query of the specified draft was successful. HTTP-Header Content-Type: application/json;charset=utf-8 HTTP-Body The body contains a JSON object with the price information. product (object) The object contains the price of the base product. product.currency (string) The currency of the price. Send-API Reference 21

25 3 API resources ǀ Query price of a draft product.product (string) The type of letter. Possible values: E-POSTBRIEF electronic E POST letter HYBRIDBRIEF physical E POST letter product.gross-amount (number) The gross-amount of the base product. options (object) Information about delivery options. options.currency (string) The currency of the price of a delivery option. options.product (string) The single costs of a chosen delivery option (see 4.1 Metadata for delivery options). If the parameter addresseeonlywithreturnreceipt is set, the costs of EINS- CHREIBEN_EIGENHAENDIG (personal registered mail) and EINSCHREI- BEN_RUECKSCHEIN (registered mail with return receipt) are added. EINSCHREIBEN Registered mail without options: Not only the recipient personally, but also an authorized recipient, e.g. a spousemust, is allowed to acknowledge receipt. EINSCHREIBEN_EIGENHAENDIG Personal registered mail: Only the recipient is allowed to acknowledge receipt. EINSCHREIBEN_RUECKSCHEIN Registered mail with return receipt: The sender gets sent the handwritten conformation of an authorized recipient about the delivery as original. EINSCHREIBEN_MIT_EINWURF Registered mail delivered to mailbox: The deliverer of the Deutsche Post AG drops the letter into a mailbox of the receiver and the deliverer confirms this with his signature. FARBDRUCK Color printing: The value depends on the number of printed pages. Send-API Reference 22

26 3 API resources ǀ Query price of a draft options.gross-amount (number) The gross-amount of a single delivery option. total-price (object) The object contains the total delivery price of the letter. Beside the costs for the base product this includes also the costs for the delivery options. total-price.currency (string) The currency of the total price. total-price.gross-amount (number) The gross-amount of the total price. 400 Bad Request The header Content-Source is missing. 403 Forbidden There is no permission to access the resource. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: insufficient_scope The access token does not have the needed privileges. 404 Not Found At the specified URI in the Content-Source header no resource could be found. 406 Not Acceptable An Accept header is missing or has been specified and has a value other than application/json. 409 Conflict The request was made under wrong assumptions. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: invalid_letter The referenced letter can not be processed. Possible causes include: Send-API Reference 23

27 3 API resources ǀ Query price of a draft invalid address too many pages invalid cover letter (unsupported HTML tags) cover letter not printable (formatting or conversion error) invalid attachment attachment not printable (formatting or conversion error) violated blocked areas on the edge of the page or in the address field See 5.5 PDF settings for high print quality for detailed information about possible errors in the delivery of PDF files. For this error there is a description in the form of a JSON object (see 4.5 Metadata for the error output ): error (string) invalid_letter error_description (string) Invalid letter content. error_details (list) The following values specify the error: invalid_type Attachment is not a valid file. : Bad file too_many_pages Letter has too many pages. : The E POST letter contains too many pages. incorrect_format Attachment has an incorrect format. : The attachment is in a incorrect format restriction_mark_violated Content violates restriction mark areas in attachment. : Blocked areas are violated, see 5. Print Production Requirements for E POST letters. max_pages (number) Number of allowed pages num_pages (number) Number of actual pages description (string) not_draft Error description The referenced E POST letter is not a draft. Send-API Reference 24

28 3 API resources ǀ Query price information Example: Response in the case of success Example: Response in the event of an error HTTP/ OK Content-Type: application/json;charset=utf-8 { "totalprice": { "gross-amount":0.6, "currency" : "EUR" HTTP/ Conflict Content-Type: application/json;charset=utf-8 { "error": "invalid_letter", "error_description": "Invalid letter content.", "error_details": [ { "description": "PDF has too many pages.", { "description": "Attachment has an incorrect format.", { "description": "Attachment is not a valid file." ] 3.5 Query price information You can view the postage for an E POST letter without having a draft to be created. With POST /postage-info you submit the appropriate metadata (e.g. color printing) and you receive the corresponding price information. Scope You need the following scope(s) for the price query: send_letter: Query the price for an E POST letter that is to be sent electronically. send_hybrid: Query the price for an E POST letter that is to be sent physically. that depending on the nature of the E POST letter at least the number of pages to be sent (send_hybrid)) or the size of your document in MB (send_letter) must be specified. Request URL structure Production POST Test and integration environment POST HTTP header x-epost-access-token (required) This header passes the token that authorizes your application with the permission of the owner of the specified E POST user account. Content-Type (required) application/vnd.epost-postage-info+json HTTP body In the HTTP body you enter the desired information, such as method of delivery, scope and delivery options (see 4.2 Metadata for pricing information). Send-API Reference 25

29 3 API resources ǀ Query price information Delivery options are only considered when sending physical E POST letters (scope send_hybrid). Example POST HTTP/1.1 x-epost-access-token: <E-POST Access Token> Content-Type: application/vnd.epost-postage-info +json Host: send.api.epost.de { "letter": { "type": "hybrid", "messagetype": "hybrid", "size": 1, "options": { "color": "colored", "coverletter": "included", "registered": "addresseeonlywithreturnreceipt" Response 200 OK The price query of the specified draft was successful. HTTP-Header Content-Type: application/json;charset=utf-8 HTTP-Body The body contains a JSON object with the price information. product (object) The object contains the price of the base product. product.currency (string) The currency of the price. product.product (string) The type of letter. Possible values: E-POSTBRIEF electronic E POST letter HYBRIDBRIEF physical E POST letter product.gross-amount (number) The gross-amount of the base product. options (object) Information about delivery options. options.currency (string) The currency of the price of a delivery option. options.product (string) The single costs of a chosen delivery option (see 4.1 Metadata for delivery options). Send-API Reference 26

30 3 API resources ǀ Query price information If the parameter addresseeonlywithreturnreceipt is set, the costs of EINS- CHREIBEN_EIGENHAENDIG (personal registered mail) and EINSCHREI- BEN_RUECKSCHEIN (registered mail with return receipt) are added. EINSCHREIBEN Registered mail without options: Not only the recipient personally, but also an authorized recipient, e.g. a spousemust, is allowed to acknowledge receipt. EINSCHREIBEN_EIGENHAENDIG Personal registered mail: Only the recipient is allowed to acknowledge receipt. EINSCHREIBEN_RUECKSCHEIN Registered mail with return receipt: The sender gets sent the handwritten conformation of an authorized recipient about the delivery as original. EINSCHREIBEN_MIT_EINWURF Registered mail delivered to mailbox: The deliverer of the Deutsche Post AG drops the letter into a mailbox of the receiver and the deliverer confirms this with his signature. FARBDRUCK Color printing: The value depends on the number of printed pages. options.gross-amount (number) The gross-amount of a single delivery option. total-price (object) The object contains the total delivery price of the letter. Beside the costs for the base product this includes also the costs for the delivery options. total-price.currency (string) The currency of the total price. total-price.gross-amount (number) The gross-amount of the total price. 400 Bad Request For the following reasons the sent data can be incorrect: invalid JSON Page count or type of message is missing Invalid value Send-API Reference 27

31 3 API resources ǀ Query price information 403 Forbidden There is no permission to access the resource. HTTP header Content-Type: application/json;charset=utf-8 HTTP body The body contains a JSON object with the error information. Possible values for error: insufficient_scope The access token does not have the needed privileges. 406 Not Acceptable An Accept header is missing or has been specified and has a value other than application/json. Example: Response in the case of success (addresseeonlywithreturnreceipt) HTTP/ OK Content-Type: application/json;charset=utf-8 { "total-price": { "gross-amount":0.6, "currency" : "EUR" Example: Response in the event of an error HTTP/ Conflict Content-Type: application/json;charset=utf-8 { "error": "invalid_letter", "error_description": "Invalid letter content.", "error_details": [ { "description": "PDF has too many pages.", { "description": "Attachment has an incorrect format.", { "description": "Attachment is not a valid file." ] Send-API Reference 28

32 4 Metadata ǀ Metadata for delivery options 4 Metadata 4.1 Metadata for delivery options The following metadata is specified by your application when sending an E POST letter draft. MIME type application/vnd.epost-dispatch-options+json JSON schema { "options": { "color": "<color selection>", "coverletter": "<option for the first page>" "registered": "<option for the type of registered mail>" "tryelectronic": "<option for address updating and enhancement>" Schema parameter options (object, required) Indication that delivery options are passed. options.color (string, optional) The option specifies whether a color or black-and-white printing is carried out. The option can be any of the following values: grayscale (black and white) colored (color) If the parameter is not specified, the default value grayscale is used. options.coverletter (string, optional) The option specifies whether a cover letter is generated for delivery or if it is included in the PDF attachment. The option can be any of the following values: included (the first page of the submitted PDF will be used as the cover letter) generate (the cover letter is automatically generated) If the parameter is not specified, the default value generate is used. options.duplex (Boolean, optional) The option specifies whether a double-sided duplex printing is to be used. When duplex printing is used, all attached documents, including the generated cover page, are printed on both sides of a sheet. Send-API Reference 29

33 4 Metadata ǀ Metadata for delivery options The printing of each attached document including the generated cover page starts on a new sheet. This way the pages from two different documents are never printed on the same single sheet. The option can be any of the following values: true All sheets of the letter are printed on both sides (duplex printing) false Only the front side of each sheet is printed (simplex printing) the following restrictions: The option is only available for the scope send_hybrid (physical delivery). The option is currently only available for registered users with the user role business customer. When using options.duplex the option options.registered cannot be activated. This means duplex printing is only available for the printing of standard letters (black-and-white or color). options.registered (string, optional) The option specifies if the E POST letter is sent as a Einschreiben (registered letter), and, if so, which registered letter type is to be selected. The option can be any of the following values: standard Einschreiben ohne Optionen (registered mail without options) Not only the recipient personally, but also an authorized recipient, e.g. a spousemust, is allowed to acknowledge receipt. submissiononly Einschreiben Einwurf (registered mail delivered to mailbox) The deliverer of the Deutsche Post AG drops the letter into a mailbox of the receiver and the deliverer confirms this with his signature. addresseeonly Einschreiben nur mit Option Eigenhändig (personal registered mail) Only the recipient is allowed to acknowledge receipt. withreturnreceipt Einschreiben nur mit Option Rückschein (registered mail with return receipt) The sender gets sent the handwritten conformation of an authorized recipient about the delivery as original. Send-API Reference 30

34 4 Metadata ǀ Metadata for delivery options addresseeonlywithreturnreceipt no Einschreiben mit Option Eigenhändig und Rückschein (personal registered mail with return receipt) The sender gets sent the handwritten conformation of the recipient personally about the delivery as original. Standardbrief (standard letter) If the parameter is not specified, the default value no is used. options.tryelectronic (boolean, optional) The option specifies whether an Adressanreicherung (address updating and enhancement) is to be carried out. Possible values are true or false. Functionality The function checks if the recipient, who is addressed by mail, has an E POST letter address. This is done through the transfer of the postal recipient metadata. The function enhances only addresses from private customers in the E POST letter Adressverzeichnis (public address directory). Advantage The users of your application can benefit from the advantages of electronic E POST letters, without knowing the corresponding E POST letter address of the recipient. The Deutsche Post AG looks up the address. Procedure You submit the metadata of a E POST letter that is to be sent physically. If the value of the option is set to true, the Adressanreicherung (address updating and enhancement) is to be carried out. If an recipient's E POST letter address should be found, the letter is sent by electronic means to this address. Application of the option that this option can only be used, if no Briefzusatzleistung (additional service) is selected ("registered": "no" or no specification of this metadata). Background: The Adressanreicherung (address updating and enhancement) is intended to ensure that an E POST letter is sent electronically. A Briefzusatzleistung (additional service) requires a physical delivery. Required level of authentication For the option a high level of authentication is necessary (scope send_letter). If the Adressanreicherung (address updating and enhancement) is carried out with the scope send_hybrid and is successful, an error message appears. If you do not request the high level of authentication in advance, follow these steps: 1. Make sure that your application catches the error. 2. Implement the possibility for a user to log in with the high level of authentication (see: Login-API Reference Increase the level of authentication) and repeat the request. Send-API Reference 31

35 4 Metadata ǀ Metadata for pricing information 4.2 Metadata for pricing information Your application specifies the following metadata optionally, in order to give information about the postage of an E POST letter. You can use it to query the postage, without uploading the draft. MIME type application/vnd.epost-postage-info+json JSON schema { "letter": { "type": "<way of delivery>", "size": <extent of the E POST letter>, "options": { "color": "<color selection>, "coverletter": "<option for the first page>", "duplex": "<option for the double-sided duplex printing>", "registered": "<option for the type of registered mail>" Schema parameter letter (object, required) Indication that metadata of the letter is handed over. letter.type (string, required) This option specifies the way of delivery of the E POST letter. The option can be one of the following values: hybrid: the E POST letter can be sent physically normal: the E POST letter can be sent electronically letter.size (Number, required) Specifies the extent of the E POST letter. The unit depends on the type of E POST letter: Type hybrid: Number of pages Type normal: rounded integer size of the document in MB options (object, optional) Indication if delivery options are transmitted. options.color (string, optional) The option specifies whether a color or black-and-white printing is carried out. The option can be any of the following values: grayscale (black and white) colored (color) Send-API Reference 32

36 4 Metadata ǀ Metadata for pricing information If the parameter is not specified, the default value grayscale is used. options.coverletter (string, optional) The option specifies whether a cover letter is generated for delivery or if it is included in the PDF attachment. The option can be any of the following values: included (the first page of the submitted PDF will be used as the cover letter) generate (the cover letter is automatically generated) If the parameter is not specified, the default value generate is used. options.registered (string, optional) The option specifies if the E POST letter is sent as a Einschreiben (registered letter), and, if so, which registered letter type is to be selected. The option can be any of the following values: standard Einschreiben ohne Optionen (registered mail without options) Not only the recipient personally, but also an authorized recipient, e.g. a spousemust, is allowed to acknowledge receipt. submissiononly Einschreiben Einwurf (registered mail delivered to mailbox) The deliverer of the Deutsche Post AG drops the letter into a mailbox of the receiver and the deliverer confirms this with his signature. addresseeonly Einschreiben nur mit Option Eigenhändig (personal registered mail) Only the recipient is allowed to acknowledge receipt. withreturnreceipt Einschreiben nur mit Option Rückschein (registered mail with return receipt) The sender gets sent the handwritten conformation of an authorized recipient about the delivery as original. addresseeonlywithreturnreceipt no Einschreiben mit Option Eigenhändig und Rückschein (personal registered mail with return receipt) The sender gets sent the handwritten conformation of the recipient personally about the delivery as original. Standardbrief (standard letter) Send-API Reference 33

37 4 Metadata ǀ Metadata for creating a E POST letter draft If the parameter is not specified, the default value no is used. options.duplex (Boolean, optional) The option specifies whether a double-sided duplex printing is to be used. When duplex printing is used, all attached documents, including the generated cover page, are printed on both sides of a sheet. The printing of each attached document including the generated cover page starts on a new sheet. This way the pages from two different documents are never printed on the same single sheet. The option can be any of the following values: true All sheets of the letter are printed on both sides (duplex printing) false Only the front side of each sheet is printed (simplex printing) the following restrictions: The option is only available for the scope send_hybrid (physical delivery). The option is currently only available for registered users with the user role business customer. When using options.duplex the option options.registered cannot be activated. This means duplex printing is only available for the printing of standard letters (black-and-white or color). 4.3 Metadata for creating a E POST letter draft Your application includes the following metadata set when creating an E POST letter or an E POST letter draft with the following procedures: 3.1 Creating an E-POST letter draft with metadata, cover letter and attachments or Creating an empty draft only with metadata. that specifing dummy data in the metadate area, may cause propagation delay in the data processing. MIME type application/vnd.epost-letter+json JSON schema: electronic delivery (scope send_letter) { "envelope": { "lettertype": { "systemmessagetype": "<Typ des E POSTBRIEFS>", "recipientsprinted": [ { "salutation": "<Anrede>", Send-API Reference 34

38 4 Metadata ǀ Metadata for creating a E POST letter draft "title": "<Titel der Person>", "firstname": "<Vorname>", "lastname": "<Nachname>", "company": "<Firmenname>", "streetname": "<Straßenname>", "housenumber": "<Hausnummer>", "addressaddon": "<Zusatzinformation zur Adresse, z. B. Erdgeschoss>", "city": "<Stadt>", "zipcode": "<Postleitzahl>" ], "subject": "<Betreff>" JSON schema: physical delivery (scope send_hybrid) { "envelope": { "lettertype": { "systemmessagetype": "<type of E POST letter>", "recipientsprinted": [ { "salutation": "<salutation>", "title": "<title of the person>", "firstname": "<first name>", "lastname": "<last name>", "company": "<company name>", "streetname": "<street nname>", "housenumber": "<house number>", "addressaddon": "<additional information to the address, e.g. ground floor>", "city": "<city>", "zipcode": "<zip code>" ], "subject": "<subject>" Schema parameter envelope (object, required) Object to create the draft information envelope.lettertype (object, optional) Object that specifies what kind of E-POST letter it is. envelope.lettertype.systemmessagetype (string, optional) The type of E-POST letter. Possible values: Send-API Reference 35

39 4 Metadata ǀ Metadata for creating a E POST letter draft normal Electronic E POST letter hybrid Physical E POST letter If the object is not specified, normal is set as default. envelope.recipients (list, required for electronic delivery) Recipient Information The content of the object differs depending on type of E-POST letter: Electronic E-POST letter: envelope.recipients.displayname and envelope.recipients.epostaddress Physical E-POST letter envelope.recipientsprinted envelope.recipients.displayname (string, optional) The recipient's first and last name envelope.recipients.epostaddress (string, required) E POST letter Address of the recipient envelope.recipientsincopy (list, optional for electronic dispatch) A copy of the E-POST letter recipient information E POST letter envelope.recipientsincopy.displayname (string, optional) First and last name of the recipient of a copy of a E-POST letter. envelope.recipientsincopy.epostaddress (string, optional) E POST letter Address of the recipient of a copy of a E-POST letter. envelope.recipientsprinted (list, required for physical dispatch) List with the recipient data. Only one recipient is currently supported, therefore the list must contain exactly one element. The following values are possible: Name Type Maximum character length company String 80 salutation String 10 title String 30 firstname String 30 lastname String 30 streetname String 50 Send-API Reference 36

40 4 Metadata ǀ Metadata after creating a E POST letter draft Name Type Maximum character length housenumber String 10 addressaddon String 40 postofficebox String 10 zipcode Number 5 city String 80 The following values are mandatory: streetname and zipcode or postofficebox and zipcode envelope.subject (string, erforderlich) Subject of the E POST letter that setting the value streetname excludes the value postofficebox (and vice versa). The simultaneous setting of both values leads to stopping the process. Sending E POST letters to postal addresses is only possible within Germany. The E POSTBUSINESS API does not support yet sending E POST letters abroad. envelope.subject (string, erforderlich) Subject of the E POST letter 4.4 Metadata after creating a E POST letter draft Your application accesses the following metadata, if it references via 3.1 Creating an E- POST letter draft with metadata, cover letter and attachments to a an E-POST letter draft. that specifing dummy data in the metadate area, may cause propagation delay in the data processing. MIME type application/json; charset=utf-8 JSON schema { "envelope": { "lettertype": { "systemmessagetype": "<Typ des E POSTBRIEFS>", "recipients": [ { "displayname": "<Vor- und Nachname 1>", Send-API Reference 37

41 4 Metadata ǀ Metadata after creating a E POST letter draft "epostaddress": "<E POSTBRIEF Adresse 1>" { "displayname": "<Vor- und Nachname 2>", "epostaddress": "<E POSTBRIEF Adresse 2>" ], "recipientsincopy": [ { "displayname": "<Vor- und Nachname 1>", "epostaddress": "<E-POSTBRIEF Adresse 1>", { "displayname": "<Vor- und Nachname 2>", "epostaddress": "<E-POSTBRIEF Adresse 2>" ], "subject": "<Betreff>" Schema parameter id (string) The identifier of the created E POST letter _links (object) Object to display the links of the E-POST letter draft. _links.attachments (string) URI, that points to the corresponding attachments _links.self (string) URI to the created E POST letter _links.coverletter (string) URI of the content E POST letter _links.send (object) The REST URI for the E POST letter delivery in the form of the domain application protocol. The link will only be returned if you specify in addition to the scope create_letter the scope send_letter or send_hybrid. _links.postage-info (object) The REST URI for the calculation of the price and the delivery in the form of the domain application protocol. The link will only be returned if you specify in addition to the scope create_letter the scope send_letter or send_hybrid. _links.delete (object) The REST URI to delete the E-POST letter in the form of the domain application protocol. The link will only be returned if you specify in addition to the scope create_letter the scope delete_letter. Send-API Reference 38

42 4 Metadata ǀ Metadata for the error output 4.5 Metadata for the error output Error messages are used for a more accurate specification of individual errors in a query and are returned as JSON object. The JSON schema differs depending on the resource. The schemas are shown below. JSON schema 1 { "error": "<error identifier>", "error_description": "<error description>", "error_details": [ <distinction oferror reasons> ] MIME typeschema 1 Parameter schema 1 application/json; charset=utf-8 error (string) A reliable identifier for the error type. error_description (string) Human readable text with additional information to support the developer to understand the error that occurred. error_details (list) Optional: A list of detailed error descriptions. It is used to differentiate error reasons, optionally with limits. JSON schema 2 { "errorcode": "<error code>", "errordescription": "<error description>", "description": "<error description>" MIME typeschema 2 Parameter schema 2 application/json; charset=utf-8 errorcode (string) Unique error code description (string) Optional: Description in plain text errordescription (string) Duplicate of description for backward compatibility included in all error responses. Send-API Reference 39

43 5 Print Production Requirements for E POST letters ǀ Delivery with cover page 5 Print Production Requirements for E POST letters If no electronic delivery of E POST letters occur, the mailings will be centrally processed and printed on behalf of the Deutsche Post AG. During the print production of the physical E POST letters, standardized production processes will be applied, unless other ones are specified. E POST letters that are delivered via the Send API are folded and enveloped using the standard formats C6 or C5. In cases where the mailings exceed 10 pages and more, envelopes in the format C4 will be used. The production commitment from Deutsche Post AG also apply for mail production via the E POSTBUSINESS API. If your mailings need to be delivered on the next business day, they have to be consigned via the Send API until 2 pm. A print production at the weekend (including Saturday) does not take place. E POST letters are subject to physical delivery restrictions in relation to size, type and other properties. These differentiations depend on whether a delivery is made with or without a cover page. The print service of the E POSTBUSINESS API also checks the delivered PDF documents and makes adjustments if necessary. PDF quality Blocked areas The print service automatically performs a quality check for the delivered PDF files and adjusts the quality if necessary. Only in cases where the PDF quality of a document is absolutely insufficient, the document will be rejected. By this way, the quality of your physical letters is granted. For more information, see section 5.5 PDF settings for high print quality and 5.4 Requirements for PDF files for the quality of PDF files. In addition, page margins will be superimposed with a white area, should they have been printed on, so that these PDFs are no longer rejected by the E POSTBUSINESS API. Make sure to not print or superimpose the area reserved for IT franking, as an address could be positioned here, thus making the entire address field unreadable. Letters that do not keep clear the area for IT franking are rejected by the E POSTBUSINESS API. For more information to the topic IT franking, see 5.2 Delivery without cover page. 5.1 Delivery with cover page Each time a E POST letter is printed via the Send API, a full addressed cover page will be added by default. This cover page contains the destination address provided in the field delivery, which will be automatically positioned in the right field when printed and enveloped in the data center of the Deutsche Post AG. This ensures that a letter can be sent even if the cover letter does not comply to the applying layout requirements. For price calculation purposes, the delivery of the page will be included. It is possible to replace the standard cover page with your own one, for more information, see 5.2 Delivery without cover page ). Send-API Reference 40

44 5 Print Production Requirements for E POST letters ǀ Delivery with cover page There is a space limit for the recipient's address field, when sending with a cover page. This is a technical limitation because the visibility of the address in the viewing window of the envelope must be ensured when the letter is printed by the Deutsche Post AG. The printable area of the address field is limited to the following dimensions: Maximum width of the sender line: 66mm Maximum width of the first line of the address block: 50mm Maximum width of the continuation line of the address block: 65mm Since the address field is generated automatically from the meta data of the E POST letter, the restriction results from the number of characters used. Send-API Reference 41

45 5 Print Production Requirements for E POST letters ǀ Delivery with cover page As for printing, a variable font is used. The maximum usable number of characters differs from case to case. For example, in printed form, the word Mississippi is shorter than Wiener-Wald, despite the identical number of characters. Example Figure Example: Automatically generated cover page by the E POST system Send-API Reference 42

46 5 Print Production Requirements for E POST letters ǀ Delivery without cover page When the cover page is automatically created, the subject and, if any, the text of the optional cover letter appears in addition to the address information. (see 3.1 Creating an E- POST letter draft with metadata, cover letter and attachments). 5.2 Delivery without cover page For deliveries without a cover page, the first page of the submitted PDF document is used as the first page of the unchanged E POST letters. Thus, it must be set up, ensuring that the page address is still recognizable through the viewing window of the envelope in the print production. To define the production and delivery without cover page, the information needs to be specified in the meta data (see 4.1 Metadata for delivery options). For this reason, it is essential to ensure that neither text, graphics or other objects are located on certain blocked areas. Blocked areas are reserved for processing information that facilitate automated printing and enveloping. Blocked margins are defined by the standard DIN If you do not implement a control mechanism for physically sent E POST letters it can result in the following problems: The characteristics of the E POST letter without cover page makes it impossible to be printed, therefore it will not be sent. The E POST letter without a cover page has characteristics that can be corrected beforehand, so that a deviated printing can be performed. Page layout and blocked areas An E POST letter without a cover page that is to be send physically consists of a first page (e.g. a cover letter) and, if necessary, further pages in PDF format (DIN A4). Ensure the following: For all pages: The dimensions of the margins, as well as the blocked area on the left side of the page match the specifications defined in Figure on page 44. For the first page of a letter: The dimensions of the blocked areas in the address field must comply with the following specifications: E POST letters without additional service (Briefzusatzleistung) Figure on page 45 E POST letters with additional service (Briefzusatzleistung) Figure on page 46 Send-API Reference 43

47 5 Print Production Requirements for E POST letters ǀ Delivery without cover page Druckfreier Rand 2 mm Druckfreier Rand 2 mm 90 mm 12 mm Freifläche Rand Druckfreier Rand 2 mm Druckfreier Rand 2 mm Figure Blocked areas on the side margins Send-API Reference 44

48 5 Print Production Requirements for E POST letters ǀ Delivery without cover page 54 mm Druckfreier Rand 2 mm 45 mm Druckfreier Rand 2 mm 90 mm 6 mm 20 mm 53 mm 53 mm 13 mm 13 mm 12 mm 45 mm 85 mm Druckfreier Rand 2 mm 12 mm Freifläche Rand Druckfreier Rand 2 mm Figure Dimensions for blocked areas and address position without additional service (Briefzusatzleistung) Send-API Reference 45

49 5 Print Production Requirements for E POST letters ǀ Delivery without cover page 54 mm Druckfreier Rand 2 mm 45 mm Druckfreier Rand 2 mm 90 mm 85 mm 20 mm 17 mm 45 mm 85 mm Druckfreier Rand 2 mm 12 mm Freifläche Rand Druckfreier Rand 2 mm Figure Dimensions for blocked areas and address position with additional service (Briefzusatzleistung) Send-API Reference 46