Skip to main content

Create a mailbox history backfill

POST 
/v1/imap/:mailerID/history

Creates a one-time mailbox history backfill job for a connected mailbox and enqueues the first slice. Historical emails are imported newest-first and delivered individually to the mailer's configured webhook; the tenant dedupes by Message-Id.

Scope:

  • Full import (default) — omit participant to import the whole mailbox/window. Provide at least one of window_start (RFC3339) or count.
  • Single conversation — set participant to a bare email to import only mail with that address (from:<participant> OR to:<participant>). Defaults to the last 1 year when window_start is omitted.

Rules:

  • window_end is optional and defaults to now.
  • Idempotent per mailer — an active job returns 409 with the existing jobId.
  • Supported ONLY for Google (Gmail) OAuth IMAP mailboxes.

Request​

Path Parameters

    mailerID stringrequired

    Mailer ID

Body

required

History backfill request

    count integer

    Optional cap on emails delivered, newest-first. 0/omitted = uncapped; clamped to the server max (default 1000).

    folders

    object

    inbox boolean
    sent boolean
    spam boolean
    trash boolean
    participant string

    Single bare email. Provide it to import only the conversation with that address (from:/to:); omit for a full mailbox/window import.

    window_end string

    Newest point (RFC3339). Optional; defaults to now.

    window_start string

    Oldest point to walk back to (RFC3339). Required for a full import unless count is given; a participant import defaults to the last 1 year when omitted.

Responses​

History backfill accepted

Schema

    jobId string
    success boolean
Loading...