This article describes how to control your mailboxes via its native REST HTTPS API.
Notes:
To learn how to send your parsed data to your own REST API server, check out our guide on using webhooks.
To learn how to send documents programmatically to Parseur check out our Send documents using Parseur API article.
Parseur API Authentication
Parseur API uses 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-here>"
Manage Mailboxes
List mailboxes
Mailboxes objects are called parsers in the API.
To list all your mailboxes, make a GET
request on /parser
. The response is paginated.
Supported sorting keys (see the section below for more information):
name
document_count
template_count
PARSEDOK_count
(number of documents processed)PARSEDKO_count
(number of documents not processed)QUOTAEXC_count
(number of documents in quota exceeded status)EXPORTKO_count
(number of documents in export failed status)
The search
query parameter will search in the following properties:
mailbox name
mailbox email prefix
Create a mailbox
To create a mailbox, make a POST
request on /parser
passing the following keys:
name
email_prefix
(optional, if not present, will be derived fromname
key)process_attachments
:true
/false
(optional, defaults totrue
)master_parser_slug
: optional, set it if you want your mailbox to use one of our set of ready-made templates. Possible values are:search-alerts
,food-delivery
,real-estate
,job-application
,property-bookings
,job-search
.
Retrieve a mailbox
You can retrieve a mailbox with a GET
request on /parser/:mailbox_id
Update a mailbox
You can update a mailbox with a PUT
or POST
request on /parser/:mailbox_id
Copy a mailbox
You can copy (duplicate) an existing mailbox with a POST
on /parser/:mailbox_id/copy
Delete a mailbox
You can delete a mailbox with a DELETE
request on /parser/:mailbox_id
Get the field structure (schema) of a mailbox
You can get the mailbox schema with a GET
request on /parser/:mailbox_id/schema
Useful if you're planning to create a connector for Parseur.
Manage Documents in a mailbox
Send documents
To send a document via API, check out this article
List documents
You can list your documents in a given mailbox with a GET
request on /parser/:mailbox_id/document_set
. The response is paginated.
Supported sorting keys (see the section below for more information):
name
created
(default - received date)modified
(processed date)status
The search
query parameter will search in the following properties:
document id (exact match)
document name
template name
from to, cc and bcc email addresses
document metadata header
Retrieve a document
You can retrieve a document and parsed results with a GET
request on /document/:document_id
Update a document
You cannot update a document.
Reprocess a document
You can reprocess (parse) a document with a POST
on /document/:document_id/process
Skip a document
You can set the Skipped status on a document with a POST
on /document/:document_id/skip
Copy a document
You can copy a document to another mailbox with a POST
on /document/:document_id/copy/:target_mailbox_id
Retrieve the logs for a document
You can access the activity logs of a document with a GET
on /document/:document_id/log_set
. Logs are paginated.
Delete a document
You can delete a document with a DELETE
request on /document/:document_id
Manage Templates in a mailbox
List templates
You can list your templates in a given mailbox with a GET
request on /parser/:mailbox_id/template_set
. The response is paginated.
Supported sorting keys (see the section below for more information):
name
created
(creation date)modified
(default - last template update time or last time template was used)last_activity
(last time template was used)status
document_count
(number of documents matched by the template)
The search
query parameter will search in the following properties:
template name
Create a template
Retrieve a template
You can retrieve a template with a GET
request on /template/:template_id
Copy a template
You can copy a template with a POST
on /template/:template_id/copy/:target_mailbox_id
Delete a template
You can delete a template with a DELETE
request on /template/:template_id
Manage Webhooks in a mailbox
List webhooks
You can list your webhooks in a given mailbox with a GET
request on /parser/:mailbox_id
Enabled webhooks are under the
webhook_set
keyPaused webhooks are under the
available_webhook_set
key.
Create a webhook
You can create a new webhook with a POST
request on /webhook
passing the following keys:
event
: must be one ofdocument.processed
,document.processed.flattened
,document.template_needed
ortable.processed
(see our webhook reference article for more information)target
: URL to send the data to, e.g.https://api.example.com/parseur
category
: must be set toCUSTOM
parser
: ID of the mailbox you want to add the webhook to, in numerical formatname
: Custom name for the webhook. If omitted, will use the target URL instead. Optionalheaders
: JSON object containing the HTTP headers you want to send along with the result data. Optionalparser_field
: ID of a field or a table field you want the webhook to react to, in the "PF12345" format
Enable a webhook
You can enable an existing webhook for a given mailbox with a POST
request on /parser/:mailbox_id/webhook_set/:webhook_id
Pause a webhook
You can pause an existing webhook for a given mailbox with a DELETE
request on /parser/:mailbox_id/webhook_set/:webhook_id
Manage parsed data
Parseur can send parsed data in real-time to your server via its Webhook feature. Check out the webhook article to learn more.
Optional HTTP Query parameters
The following query parameters can be mixed and matched.
Pagination
All GET
request that return a list of documents, templates and mailboxes that support the pagination by appending a page
option to the URL. The default page size is 25. You can change the page size using the page_size
query parameter.
For example: /parser?page=2&page_size=50
will list the 2nd page of your mailboxes, each page containing 50 records.
Searching
Some endpoints support sorting via the search
query parameter. The search value needs to be URL encoded.
For example /parser?search=test%20mailbox
will search for mailbox names containing "test mailbox"
Unless stated otherwise, search is not case sensitive and will retrieve all entities that partially match the search string. For example, a mailbox search for foo
will return mailboxes named test.foo
and FOO Mailbox 123
.
Sorting
Some endpoints support sorting via the ordering
query parameter.
to sort a list ascending on the
foo
key, use?ordering=foo
to sort a list descending on the
foo
key, use?ordering=-foo
For example /parser?ordering=-document_count
will list your mailboxes starting with the one with the most documents.
Do more with the API
This article just lists the most common use cases of using our API. There is more you can do, feel free to ask us for more details!