Upload emails and documents

This guide shows how to create documents in Parseur via HTTP. You can either upload files (PDF, DOC, EML, etc.) or post email/text content directly.

Prerequisites

An API key (Account → Overview): https://app.parseur.com/account

Understand how API Authentication works.

The mailbox (parser) ID for uploads — you’ll find it in your mailbox URL.

Choose your method

Upload files (recommended for PDFs, images, EML…): POST /parser/{mailbox_id}/upload

Post email/text content (HTML or plain text): POST /email

The API is asynchronous: a successful response means the document was received, not that the document was successfully processed; downstream processing happens afterward.

Upload binary files

The files are sent through the usual HTTP file upload mechanism using multipart/form-data request described in RFC 1867.

Check out the list of document formats supported by Parseur to learn more about the types of documents you can send.

Using cURL

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

On some macOS setups, adding --http1.1 can help if cURL negotiates HTTP/2 incorrectly.

Response (example)

{
  "message": "OK", 
  "attachments": [
    {
      "name": "file.pdf", 
      "DocumentID": "1e2e34cba5c678a9012f3e456c789a0f"
    }
  ]
}

Save DocumentID if you need to correlate the upload with parsed results later using the DocumentID Metadata field.

Refer to the following page for details on this endpoint: Endpoints → Document → Upload a binary document

Send email/text content

Post an email-like JSON payload to /email. Use body_html for HTML content or body_plain for text (HTML takes precedence if both are present).

{
    "subject": "The title of your document, or email subject",
    "from": "Sender Name <sender.name@example.com>",
    "recipient": "mailbox.name@in.parseur.com",
    "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",
            "<original.sender@corporate.email>"
        ]
    ]
}

Using cURL

Refer to the following page for details on this endpoint: Endpoints → Document → Upload an email/text document

Adding To, CC and BCC fields

You can include to, cc, and bcc fields in the payload.

Important: your mailbox address must appear in at least one of recipient, to, cc, or bcc.

Example:

{
    "subject": "The title of your document, or email subject",
    "from": "Sender Name <sender.name@example.com>",
    "recipient": "mailbox.name@in.parseur.com",
    "to": "to.name@example.com, Another Name <another.name@example.com>",
    "cc": "cc.name@example.com",
    "bcc": "mailbox.name@in.parseur.com",
    [... rest of the request...]
}

Add custom parameters (optional)

Attach custom key/values that will be merged into the parsed result.

As query string (both endpoints)

This will upload file.pdf and once successfully processed, the keys user.name and user.age will get added to the result for this file.

For example, if the initial extracted data looks like this:

{
    "user.account_number": 123456,
    "user.role": "admin"
}

Then the resulting data will be:

{
    "user.account_number": 123456,
    "user.role": "admin",
    "user.name": "John",
    "user.age": "42"
}

Lowercasing: parameter keys are lowercased by HTTP parsing; values keep their case.

As form fields (`/upload` endpoint only)

Send URL-encoded fields in the multipart body; they’ll be merged into the result.

Expand custom parameters

Taking advantage of our mailbox's Expand field names in JSON Result feature, the result will look like this:

{
    "user": {
        "account_number": 123456,
        "role": "admin",
        "name": "John",
        "age": "42"
    }
}

Custom parameters arrays

Repeat the same key multiple times to create arrays (e.g., user.names=John&user.names=Jo).

This will add the following to the document's result:

{
    "user": {
        "names": ["John", "Jo", "Johnny"]
    }
}

Common pitfalls

Missing Authorization header or putting the key in the URL/body.

Forgetting Content-Type: application/json for /email.

Not including your mailbox address in any of recipient, to, cc, bcc.

Assuming upload success means it will always appear in the mailbox (ingestion is async).

Quick reference

Base URL: https://api.parseur.com/

Upload files: POST /parser/{mailbox_id}/upload (multipart with file=@...)

Post email/text: POST /email (JSON payload)

Auth header: Authorization: <YOUR_API_KEY>

Make sure to stay below Rate limits

Prerequisites#

Choose your method#

Upload binary files#

Using cURL#

Response (example)#

Send email/text content#

Using cURL#

Adding To, CC and BCC fields#

Add custom parameters (optional)#

As query string (both endpoints)#

As form fields (/upload endpoint only)#

Expand custom parameters#

Custom parameters arrays#

Common pitfalls#

Quick reference#

Prerequisites

Choose your method

Upload binary files

Using cURL

Response (example)

Send email/text content

Using cURL

Adding To, CC and BCC fields

Add custom parameters (optional)

As query string (both endpoints)

As form fields (`/upload` endpoint only)

Expand custom parameters

Custom parameters arrays

Common pitfalls

Quick reference