E POSTBUSINESS API Mailbox-API Reference. Version 1.3.1

Transcription

1 E POSTBUSINESS API Mailbox-API Reference

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 Mailbox-API Reference

3 Content 1 Introduction 1 2 Basic concepts 3 3 API resources Get Service Document E POST letter Creating an E-POST letter draft with metadata, cover letter and attachments Creating an empty draft only with metadata Reading an E POST letter Modifing an E POST letter metadata Marking an E POST letter as read or unread Deleting an E POST letter Envelope Read list of all envelopes Move envelope to folder Attachment Read attachments of an E POST letter Create attachment Read information about an attachment Delete attachment Read content of an attachment Content Retrieve content of an envelope (with changing the status read ) Retrieve content of an envelope (without changing the status read ) Change cover letter Folder Read status and envelopes from Inbox, Drafts, Sent and Trash Read status and sub-folders of a folder Read status and envelopes of a folder Read status and sub-folders of all folders of a user Create Folder Rename folder Delete Folder User Information Read user information 64 4 Metadata 67 Mailbox-API Reference

4 4.1 E POST letter Metadata Metadata for creating or modifying E POST letter Metadata after creating a E POST letter draft Envelope metadata Folder metadata Metadata of Inbox, Drafts, Sent, and Trash Metadata of a folder with sub-folders Metadata of a folder with E POST letters Metadata of all user folders Error Metadata User information metadata Fax error codes 89 Mailbox-API Reference

5 1 Introduction 1 Introduction With this Reference guide you will be able to integrate the E POST Mailbox API into your business application, enabling by this way, users of your application to receive and manage E POST letters in their daily working environemnt. Overview Summary Application Process The Mailbox 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 Mailbox API to receive and manage 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 Mailbox 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 Mailbox API are in accordance with the corresponding E POST portal functions. The invoicing of the services being used via the Mailbox 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 Mailbox API partner, the E POST, and the private customer or business customer, is the basis for the cooperation described in this document. The Mailbox API is a REST API you can use to implement different functions in your application (e.g.receiving 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. To use the Mailbox 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 Mailbox API with the received authorization information from the Login API. Mailbox-API Reference 1

6 1 Introduction Objective Audience It is the aim of the E POSTBUSINESS API to enable developers to integrate E POST functionalities in external systems. This API reference is intended for developers who have knowledge in the following subjects: HTTP and HTTPS REST JSON OAuth 2.0 Mailbox-API Reference 2

7 2 Basic concepts 2 Basic concepts This section explores the basic concepts of the Mailbox 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 Mailbox 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 Hypermedia 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 Mailbox 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 Mailbox API: (Production) (Test and integration environment) The API endpoint implements a hypermedia-driven REST service for communication of URIs with clients (HATEOAS: Hypertext as the engine of application state, see The entry point of the API provides references (links) to the available resources. This collection of links is called service document in the context of the E POSTBUSINESS API. By means of these links the URI of a resource can be determined. Resources, for their part, can provide links to related (sub) resources. This creates a navigable API that can be used without knowledge of the specific and current URI paths. This provides an isolation of API and client. The client can determine by checking the existence of links if certain API functions are available. Mailbox-API Reference 3

8 2 Basic concepts Procedure for implementation Pagination By the use of the hypermedia-driven REST services the entry point for clients is the service document (see 3.1 Get Service Document). This provides all the resources provided by the Mailbox API. The names of the resources assigned there are stable, while the names of the URIs may change. Therefore the service document is the entry point for the implementation of your application as the current resource URIs are represented there. After retrieving the URIs set the appropriate calls to the API. When contents of folder resources are returned (see 3.6 Folder), pagination is always used to avoid problems with large amounts of data. Pagination is controlled with the parameters limit and offset when requesting a resource: offset (integer, optional) The parameter specifies, which part of the result list, that is restricted by limit, is returned. If the parameter is not specified, the default value 0 is returned. limit (integer, optional) The number of E-POST letters that are returned in the response to the request. If the parameter is not specified, the default value 500 is returned. limit has a maximum value of 500. HTTP ETag HTTP status codes ETag, short for entity tag, is a header field that indicates changes when calling a resource. Thereby the ETag represents a specific data set. If the ETag value (without Weak-Marker) is transmitted at a re-request, data has not to be re-transferred, if it is unchanged. More information on this subject can be found on 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. 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. Mailbox-API Reference 4

9 2 Basic concepts 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 Mailbox-API Reference 5

10 3 API resources ǀ Get Service Document 3 API resources The Mailbox API uses REST resources to provide various functions to your application. In the following the usable Mailbox API resources are presented. Each answer of the Mailbox API contains the HTTP-header X-CorrelationId, whose value you can communicate in support requests, so that the logs can be allocated easier to the associated request. All the URIs that are shown in the following are examples. The resources distinguish between the user roles private customer and business customer. Various resources are available only for one specific role. When calling the Service Document (3.1 Get Service Document) only the applicable resources for a logged-on user are displayed. However, if a resource is accessed, that is not available for a logged-in user because of his user role, the HTTP Status 403 returned. 3.1 Get Service Document In the Service Document all links are provided that are required to work with the Mailbox API. All links in the Service-Dokument are absolute. Authentication User role Business customer Private customer Level of authentication normal Scope read_letter Structure of the Service Document { "links": { "attachment": { "templated": true, "href": "<URI>" }, "attachments": { "templated": true, "href": "<URI>" }, "attachmentcontent": { "templated": true, "href": "<URI>" }, "foldercontent": { "templated": true, "href": "<URI>" }, "folder": { "templated": true, "href": "<URI>" }, "coverletter": { "templated": true, "href": "<URI>" }, "letter": { "templated": true, "href": "<URI>" }, "letterreadstate": { "templated": true, "href": "<URI>" }, "inbox": { "templated": true, "href": "<URI>" }, "sent": { "templated": true, "href": "<URI>" }, "drafts": { "templated": true, "href": "<URI>" }, "trash": { "templated": true, "href": "<URI>" }, "self": { "href": "<URI>" }, "folders": { "href": "<URI>" }, "letters": { "href": "<URI>" }, "lettercontent": { "href": "<URI>", "templated": true }, "letterfolders": { "href": "<URI>", "templated": true }, "envelopes": { "href": "<URI>" }, "meidentity": { "href": "<URI>" } } } Mailbox-API Reference 6

11 3 API resources ǀ Get Service Document The JSON-objects within links have the following meaning: href URI for the call of the resource templated true specifies that it is a URI template, therefore you cannot call the URI directely. By using the object links the functions of the Mailbox API are referenced: attachment URI template for the resources Read information about an attachment Delete attachment attachmentcontent URI template to read the content of an E POST letter attachment (3.4.5 Read content of an attachment) attachments URI template for the resource coverletter Read attachments of an E POST letter Create attachment URI template for the resource Retrieve content of an envelope (with changing the status read ). drafts URI template to read the Draft folder (3.6.1 Read status and envelopes from Inbox, Drafts, Sent and Trash ) envelopes URI for the resource Read list of all envelopes folder URI template for the resources Read status and sub-folders of a folder Rename folder Delete Folder foldercontent URI template for the resource Read status and envelopes of a folder folders URI template for the resources Read status and sub-folders of all folders of a user Create Folder Mailbox-API Reference 7

12 3 API resources ǀ Get Service Document inbox URI template to read the Inbox folder (3.6.1 Read status and envelopes from Inbox, Drafts, Sent and Trash ) letter URI template for the resources Reading an E POST letter Modifing an E POST letter metadata lettercontent URI template for the resource Retrieve content of an envelope (without changing the status read ). letterfolders URI template for the resource Move envelope to folder letterreadstate URI template for the resource Marking an E POST letter as read or unread letters URI template for the resource Creating an empty draft only with metadata meidentity self sent URI to read the user information (3.7.1 Read user information) URI for this Service-Dokument URI template to read the Sent folder (3.6.1 Read status and envelopes from Inbox, Drafts, Sent and Trash ) trash URI template to read the trash folder (3.6.1 Read status and envelopes from Inbox, Drafts, Sent and Trash ) Request Production GET Test and integration environment GET Example GET / HTTP/ 1.1 Host: mailbox.api.epost.de Mailbox-API Reference 8

13 3 API resources ǀ Get Service Document Response For additional possible status codes see HTTP status codes on page OK HTTP header application/json;charset=utf-8 HTTP body The Service Document is returned as JSON object. Example: Response in the case of success HTTP/ OK X-CorrelationId: WAF_1_VD5j8wrTAAwAACk2juoAAAAC Content- Type: application/json;charset=utf-8 { "links": { "attachment": { "templated": true, "href": " letters/{letterid}/attachments/{attachmentid}" }, "attachments": { "templated": true, "href": " attachments" }, "attachmentcontent": { "templated": true "href": " {attachmentid}/content", }, "foldercontent": { "templated": true, "href": " offset,limit}" }, "folder": { "templated": true, "href": " }, "coverletter": { "templated": true, "href": " coverletter" }, "letter": { "templated": true, "href": " }, "inbox": { "templated": true, "href": " }, "sent": { "templated": true, "href": " }, "drafts": { "templated": true, "href": " }, "trash": { "templated": true, "href": " }, "self": { "href": " }, "folders": { "href": " }, "letters": { "href": " }, "letterreadstate": { "href": " read", "templated": true }, "lettercontent": { "href": " "templated": true }, "letterfolders": { "href": " "templated": true }, "envelopes": { "href": " }, "meidentity": { "href": " } } } Mailbox-API Reference 9

14 3 API resources ǀ E POST letter Authentication E POST letter Creating an E-POST letter draft with metadata, cover letter and attachments 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. User role Business customer Private customer Level of authentication normal Scope create_letter Request Call of the resource First you get the service document (3.1 Get Service Document). The following object provides the URI for the call of the resource: letters The object refers with href to the URI of the resource. You implement an operation that sets a POST request on the content of the href object. 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 Mailbox-API Reference 10

15 3 API resources ǀ E POST letter 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 Metadata for creating or modifying E POST letter). 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, 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> Mailbox-API Reference 11

16 3 API resources ǀ E POST letter 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. 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": { Mailbox-API Reference 12

17 3 API resources ǀ E POST letter "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 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", Mailbox-API Reference 13

18 3 API resources ǀ E POST letter "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-- 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.1.2 Metadata after creating a E POST letter draft). 400 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) The format of the cover letter is invalid (invalid HTML) Mailbox-API Reference 14

19 3 API resources ǀ E POST letter 403 Forbidden 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. 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", Mailbox-API Reference 15

20 3 API resources ǀ E POST letter "value": " 23d2c6f0-05d0-11e4-94a a87" } ] }, "self": { "href": " 23d2c6f0-05d0-11e4-94a a87" }, "attachments": { "href": " 23d2c6f0-05d0-11e4-94a a87/attachments" } } } Example: Response in the event of an error Authentication HTTP/ Forbidden Content-Type: application/json;charset=utf-8 { } "errorcode": "CORE_035", "description": "Engine Failure: Bad Request" Creating an empty draft only with metadata With this resource you create an empty E POST letter draft that contains only metadata. If you use this resource, you have the possibility, to add a cover letter (3.5.3 Change cover letter) as well as to add an attachment (3.4.2 Create attachment). User role Private customer Level of authentication normal Scope read_letter Request Call of the resource First you get the service document (3.1 Get Service Document). The following object provides the URI for the call of the resource: letters The object refers with href to the URI of the resource. You implement an operation that sets a POST request on the content of the href object.setzt. Mailbox-API Reference 16

21 3 API resources ǀ E POST letter 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-letter+json The specification of the value indicates that a JSON object with the metadata follows in the body. 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 body In the body you include a JSON object with the E POST letter metadata (4.1.1 Metadata for creating or modifying E POST letter). 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.1.2 Metadata after creating a E POST letter draft) Bad Request Incorrect parameters or values were given. Reading an E POST letter This resource returns the content of an E POST letter. When retrieving a single E POST letter it will be marked as read. Mailbox-API Reference 17

22 3 API resources ǀ E POST letter Only metadata of a standard E POST letter and Einschreiben mit Empfangsbestätigung (registered mail with return receipt) with the status read can be retrieved. By using the resource the status of the envelope is set to the status read (see 4.2 Envelope metadata, parameter read). Authentication User role Private customer Business customer Level of authentication normal Scope read_letter Request Call of the resource First you get the service document (3.1 Get Service Document). The following object provides the URI for the call of the resource: letter The object refers with href to the URI of the resource. You implement an operation that sets a GET request on the content of the href object. This is a URI template, therefore you cannot call the URI directely. So you are addressing the path parameter in curly brackets with the implementation of your application. 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. If-None-Match (optional) Optionally you pass the last ETag value that was delivered from the API (see HTTP ETag on page 4). Example GET /letters/f6b8dbb9-e71c e16-a4473bc6d572 HTTP 1.1 Host: mailbox.api.epost.de x-epost-access-token: <E-POST Access Token> Mailbox-API Reference 18

23 3 API resources ǀ E POST letter Response For additional possible status codes see HTTP status codes on page OK The request was successful and the body contains the E POST letter. HTTP header Content-Type: application/vnd.epost-letter+json Declaration that a JSON object with the metadata follows. ETag: <ETag value> The ETag value of the response (see HTTP ETag on page 4). HTTP body The body contains a JSON object with the metadata of the E POST letter information. The structure of the object: envelope (object) The envelope coverletterinfo (object) The cover letter attachments (object) List, that contains information about the attachments Not Modified The content is not returned because it has not changed since the retrieval, in which the ETag has been delivered. Bad Request Incorrect parameters or values were given. Forbidden There is no permission to access the resource. This might be due to the following reasons: Authorization error: The scope is not specified correctly for the resource. The user is not allowed to access the resource. Only metadata of a standard E POST letter and Einschreiben mit Empfangsbestätigung (registered mail with return receipt) with the status read can be retrieved. Mailbox-API Reference 19

24 3 API resources ǀ E POST letter 404 Not Found The E POST letter could not be found, because an invalid folderid was referenced. Example: Response in the case of success (physical E POST letter) HTTP/ OK X-CorrelationId: WAF_1_VD5j8wrTAAwAACk2juoAAAAC ETag: W/" " Content-Type: application/vnd.epost-letter+json { "_links" : { "self" : { "href" : " 3cd12110-b3b9-4c22-ae6f-46192edaaf87" }, "send" : { "headers" : [ { "name" : "Content-Source", "value" : " mailbox.api.epost.de/letters/3cd12110-b3b9-4c22-ae6f-46192edaaf87" } ], "href" : " "method" : "POST" }, "postage-info" : { "headers" : [ { "name" : "Content-Source", "value" : " letters/3cd12110-b3b9-4c22-ae6f-46192edaaf87" } ], "href" : " "method" : "POST" }, "delete" : { "href" : " ae6f-46192edaaf87", "method" : "DELETE" }, }, "envelope": { "sender": { "displayname": "Max Mustermann", "epostaddress": "max.mustermann@epost.de" }, "recipientsprinted": [ { "city": "Berlin", "zipcode": "13409", "postofficebox": "", "company": "Musterfirma GmbH", "salutation": "Frau", "title": "Dr.", "firstname": "Erika", "lastname": "Mustermann", "streetname": "Musterstraße", "housenumber": "12", "addressaddon": "Erdgeschoss" } ], "sentdate": " T15:07:38.848Z", "lettertype": { "sendertype": "private", "messagetype": "EPB" }, "subject": "reminder", "read": false, "hasattachments": true, "encryptedattachment": false, "_links": { "letter": { "href": " ae6f-46192edaaf87" } } }, "coverletterinfo": { "_links" : { "content" : { "href": " a4473bc6d572/coverletter" } } }, "attachments": [ { "_links": { "self": { "href": " ca1be995-30b5-49e1-a457-f0b1ccbf7476/attachments/ca1be995-30b5-49e1-a457- f0b1ccbf7476" }, "content" : { "href": " ca1be995-30b5-49e1-a457-f0b1ccbf7476/attachments/ca1be995-30b5-49e1-a457- f0b1ccbf7476/content" } }, "cid" : "part @epost.de", "filename": "Bewerbung.pdf", "contenttype": "application/pdf", "inline": false, "encrypted": false, "size": 1024 }, { "_links": { "self": { "href": " f0b1ccbf7476/attachments/d8a69d09-ba5d-447f-bce5-092ace8ac606" }, "content": { "href": " f0b1ccbf7476/attachments/d8a69d09-ba5d-447f-bce5-092ace8ac606/ content" } }, "cid" : "part @epost.de", "filename": Mailbox-API Reference 20

25 3 API resources ǀ E POST letter "inlinegrafik.jpg", "contenttype": "image/jpg", "inline": true, "encrypted": false, "size": 512 } ] } Authentication Modifing an E POST letter metadata With the resource you change the metadata of a E POST letter draft. The resource changes the metadata of a E POST letter (letter, without cover letter). If you want to modify the cover letter (coverletter) of a E POST letter, use the resource Change cover letter. User role Private customer Level of authentication normal Scope read_letter Request Call of the resource First you get the service document (3.1 Get Service Document). The following object provides the URI for the call of the resource: letter The object refers with href to the URI of the resource. You implement an operation that sets a PUT request on the content of the href object. This is a URI template, therefore you cannot call the URI directely. So you are addressing the path parameter in curly brackets with the implementation of your application. 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. Content-Type (required) application/vnd.epost-letter+json HTTP body In the body you pass the JSON serialized envelope object of the E POST letter. Only the fields that are included in envelope are replaced. For more Information about the JSONschema, see Metadata for creating or modifying E POST letter. Mailbox-API Reference 21

26 3 API resources ǀ E POST letter It is sufficient to specify only the metadata that changes. Example PUT /letters/f6b8dbb9-e71c e16-a4473bc6d572 HTTP 1.1 Host: mailbox.api.epost.de x-epost-access-token: <E-POST Access Token> { "envelope" : { "recipients": [ { "displayname": "Maxime Musterfrau } ], "subject" : "Ein geänderter E-Postbrief" } } Response For additional possible status codes see HTTP status codes on page No Content The E POST letter was updated successfully. Bad Request Incorrect parameters or values were given. Not Found The E POST letter could not be found, because an invalid folderid was referenced. Marking an E POST letter as read or unread With this resource you set the status of a E POST letter to read or unread. Authentication User role Private customer Business customer Level of authentication normal Scope read_letter Request Call of the resource First you get the service document (3.1 Get Service Document). The following object provides the URI for the call of the resource: letterreadstate The object refers with href to the URI of the resource. You implement an operation that sets a PUT request on the content of the href object. Mailbox-API Reference 22

27 3 API resources ǀ E POST letter This is a URI template, therefore you cannot call the URI directely. So you are addressing the path parameter in curly brackets with the implementation of your application. 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. Content-Type (required) application/json HTTP body In the body you pass an JSON-object that defines the read or unread status of the E POST letter: readstate true The E POST letter has the status read. false The E POST letter has the status unread. Example PUT /letters/3cd12110-b3b9-4c22-ae6f-46192edaaf87/read HTTP 1.1 Host: mailbox.api.epost.de x-epost-access-token: <E-POST Access Token> { "readstate" : true } Response For additional possible status codes see HTTP status codes on page No Content The E POST letter status was set to read or unread. Bad Request Incorrect parameters or values were given. Mailbox-API Reference 23

28 3 API resources ǀ E POST letter Not Found The E POST letter could not be found, because an invalid folderid was referenced. Deleting an E POST letter With DELETE /letters/{letterid} you delete an E POST letter. 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. 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 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 Authentication 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. User role Private customer Business customer Level of authentication normal Scope delete_letter Request First you get the service document (3.1 Get Service Document). The following objects provide the URIs for the call: Mailbox-API Reference 24

29 3 API resources ǀ E POST letter This is a URI template, therefore you cannot call the URI directely. Therefore you are addressing the path parameter in curly brackets with the implementation of your application. 1. Move to trash folder letter The object refers with href to the URI of the resource. You implement an operation that sets a DELETE request on the content of the href object. 2. Delete from trash folder trash The object refers with href to the URI of the resource. You implement an operation that sets a DELETE request on the content of the href object. 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. 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 Mailbox-API Reference 25

30 3 API resources ǀ E POST letter 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. 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) Mailbox-API Reference 26

31 3 API resources ǀ Envelope READ_003 Missing access rights 404 Not Found The E POST letter could not be found, because an invalid folderid was referenced. 3.3 Envelope An envelope is either an E-POST letter (electronic and physical) or a fax. The following resources are applicable for envelopes. In folder resources envelopes are also displayed (see 3.6 Folder) Read list of all envelopes The resource provides a list of all envelopes of a user. The following restrictions apply: The list of messages contains no s. If no messages exist, the reply contains an empty list. If the user has a large number of messages, the resource provides a large amount of data. In the reply there is no pagination. Authentication User role Private customer Level of authentication normal scope read_letter Request First you get the service document (3.1 Get Service Document). The following object provides the URI for the call of the resource: envelopes The object refers with href to the URI of the resource. You implement an operation that sets a GET request on the content of the href object. Mailbox-API Reference 27

32 3 API resources ǀ Envelope Path parameter includestatusmessage (Boolean, optional) When a user has sent a fax, he receives an e mail that notifies him about the successful or failed delivery. You can suppress the display of such e mails when you use this resource. To achieve that you set the parameter includestatusmessage to false. You can always retrieve the status of a fax with the paramter deliverystate in the envelope metadata (see 4.2 Envelope metadata). The default value for includestatusmessage is true. Older fax messages are still visible, even if the parameter is set to false. 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. Example GET /envelopes 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 OK The request was successful and the body contains the list of envelopes. Content-Type: application/json Declaration that a JSON object with the metadata follows. HTTP body The body contains the JSON object envelopes (the list of envelopes) Bad Request Incorrect parameters or values were given. Forbidden There is no permission to access the resource. Mailbox-API Reference 28

33 3 API resources ǀ Envelope Example: Answer in the case of success Authentication HTTP/ OK X-CorrelationId: WAF_1_VD5j8wrTAAwAACk2juoAAAAC Content- Type: application/json { "envelopes": [ { "recipientsprinted": [], "recipientsincopy": [], "recipients": [ { "epostaddress": "unknown@epost.de", "displayname": "\"axel dell" }, { "epostaddress": "noreply@epost-klassisch.de", "displayname": "berlin\"\"" } ], "sender": { "epostaddress": "post.fuchs02@testingepost.de", "displayname": "Post Fuchs02" }, "letterid": "f7c6e280-11a5-11e4-9e2c fef25", "folderid": "c8136cb0-422b-11e3-b2ec d2", "foldername": "Steuer", "subject": "Prüfe postalische Adresse bei gesendeten Portalentwürfen", "read": true, "isdraft": false, "hasattachments": false, "encryptedattachment": false, "sentdate": " T15:42:00+02:00", "letterstate": "sent", "lettertype": { "systemmessagetype": "hybrid", "sendertype": "private", "systemmessage": false, "messagetype": "EPB" } }, { "recipientsprinted": [], "recipientsincopy": [], "recipients": [ { "epostaddress": "post.fuchs02@testingepost.de", "displayname": "Post Fuchs02" } ], "sender": { "epostaddress": "post.fuchs02@testingepost.de" }, "letterid": "a6ef5ea0-0cfa-11e4-bcaf fef25", "folderid": "inbox", "foldername": "Inbox", "subject": "MailboxITConfirmAcceptedMessage", "read": false, "isdraft": false, "hasattachments": false, "encryptedattachment": false, "sentdate": " T17:05:39+02:00", "letterstate": "received", "lettertype": { "systemmessagetype": "normal", "additionalservice": "Einschreiben mit Empfangsbestätigung", "sendertype": "private", "systemmessage": false, "messagetype": "EPB" } } ] } Move envelope to folder The resource moves an envelope to a folder. The following scenarios are supported: Inbox User folder User folder Inbox User folder User folder Inbox Trash Drafts Trash Draft from trash Drafts Received envelope from trash Inbox Received envelope from trash User folder Sent Trash User role Private customer Business customer Level of authentication normal Mailbox-API Reference 29

34 3 API resources ǀ Envelope Scope read_letter Request First you get the service document (3.1 Get Service Document). The following object provides the URI for the call of the resource: letterfolders The object refers with href to the URI of the resource. You implement an operation that sets a PUT request on the content of the href object. This is a URI template, therefore you cannot call the URI directely. So you are addressing the path parameter in curly brackets with the implementation of your application. 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/json HTTP body In the body you pass a JSON serialized list to the destination folder. At the moment only one destination folder is supported, therefore this list may contain only a single object, otherwise an error message is returned. folderids (string, required) The ID of the destination folder Example PUT /letters/f6b8dbb9-e71c e16-a4473bc6d572/folders HTTP 1.1 Host: mailbox.api.epost.de x-epost-access-token: <E-POST Access Token> { "folderids" : [ "inbox" ] } Response No Content The E POST letter has been successfully moved to the destination folder. Bad Request The request is incorrect. This might be due to the following reasons: The transmitted JSON document is invalid The list of destination folders is empty or contains more than one folder. Mailbox-API Reference 30

35 3 API resources ǀ Attachment Forbidden The E POST letter must not be moved. This is due to the following reasons: It is a Einschreiben Einwurf (registered mail delivered to mailbox) Not Found There is no folder with the specified ID Attachment Read attachments of an E POST letter The resource provides a list of all attachments of a E POST letter. If no attachments exist, the reply contains an empty list. With a GET request to the resource a list of all attachments of a E POST letter can be read. Authentication User role Private customer Business customer Level of authentication normal Scope read_letter Request First you call the service document (3.1 Get Service Document). The following object provides the URI for the call of the resource: attachments The object refers with href to the URI of the resource. You implement an operation that sets a GET request on the content of the href object. This is a URI template, therefore you cannot call the URI directely. So you are addressing the path parameter in curly brackets with the implementation of your application. Path parameter letterid (required) Identifier of the E POST letter. Mailbox-API Reference 31