This article describe how to send documents to Parseur via its native REST HTTPS API

Parseur API Authentication

Parseur API uses a token-based authentication.

You will find your API Token Key in your Account Overview .

For clients to authenticate, the token key should be included in the Authorization HTTP header. The key should be prefixed by the string literal "Token", with white space separating the two strings. For example:

Authorization: Token 1234d45678c90bcf1234fe123ddae4aabbc6abcd


Unauthenticated responses that are denied permission will result in an  HTTP 403 Unauthorized response with an appropriate WWW-Authenticate header. For example:

WWW-Authenticate: Token

The curl command line tool may be useful for testing token authenticated APIs. For example:

curl -X GET https://api.parseur.com/ -H "Authorization: Token <enter-your-token>"

Picking a way to send documents to Parseur

Parseur API offers 2 endpoints to send new documents:

  • The /parser/ID/upload one, which is used to upload binary files (PDF, DOC, EML, ...) in the application. This endpoint is recommended if you want to send one or many arbitrary file(s) with the help of a programming library or the curl command.

  • The /email one, which is mostly used to receive documents originating from emails (so, it's most often HTML or text documents). This endpoint offers the possibility to send the document's text content directly. It also allows you to specify email-related metadata and headers.

Sending binary documents to Parseur

You can send a document to one of your mailboxes by issuing a POST HTTP request to the URL https://api.parseur.com/parser/ID/upload , replacing the ID with the ID of the mailbox you want to send the document to.

The files are sent through the usual HTTP file upload mechanism described here: https://datatracker.ietf.org/doc/html/rfc1867

In order to upload a file from your disk to your mailbox, you need 2 things:

  • Your API token (found here: https://app.parseur.com/account )

  • The numerical ID of the mailbox you want to upload the file to. You can find this ID in the URL bar of your browser, when browsing your mailbox:

You can then upload a file using the following curl command, on Linux and Mac OS X systems:

curl \
-X POST \
https://api.parseur.com/parser/<Your mailbox ID>/upload \
-H "Authorization: Token <Your API token>" \
-F '[email protected]/path/to/file.pdf' \
--http1.1

Notes:

  • Make sure to replace the <API token> and <Mailbox IS> placeholders with your own values

  • --http1.1 flag is needed for work around Mac OS X's curl incompatibility with Parseur's servers

Here is a list of files types you can send this way: https://help.parseur.com/en/articles/5275611-document-formats-supported-by-parseur

Sending emails and text documents to Parseur

Once authenticated, you can send a new document for Parseur to process by issuing a POST request on https://api.parseur.com/email with the following payload:

{
'subject': 'The title of your document, or email subject',
'sender': '[email protected]',
'recipient': '[email protected]',
'body_html': '<html><body>Document content as HTML. This one has priority over text content if both are present.</body></html>',
'body_plain': 'Document content as text. This one is only used if body_html is empty.',
'message_headers': [
["Standard-SMTP-Header", "Any usual email header goes here"],
["X-Envelope-From", "<[email protected]>"],
]
}


As an example, you can test the following curl command and it should create a new document for your [email protected] mailbox (attachments and message headers removed to keep the example simple but those are optional anyway):

curl \
-X POST \
https://api.parseur.com/email \
-d '{
"subject": "The title of your document, or email subject",
"sender": "[email protected]",
"recipient": "[email protected]",
"body_html": "<html><body>Document content as HTML. This one has priority over text content if both are present.</body></html>",
"body_plain": "Document content as text. This one is only used if body_html is empty.",
"message_headers": []
}' \
-H "Content-Type: application/json" \
-H "Authorization: Token <enter-your-token-here>"

Note: Make sure to replace the recipient email address and the token with your own values

What's next?

Did this answer your question?