This article describes 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/uploadone, 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 thecurlcommand.The
/emailone, 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 ID> placeholders with your own values
--http1.1 flag is needed for work around Mac OS X's
curlincompatibility with Parseur's servers
Check out the list of document formats supported by Parseur to learn more about the types of documents you can send.
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',
'from': 'Sender Name <[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",
"from": "Sender Name <[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