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.
  • Participants — set participants to up to 50 bare emails to import every email exchanged with those contacts: From/To/Cc/Bcc, all folders except spam, trash and drafts, the whole history up to job creation. Cannot be combined with participant, count, window_start or window_end. Emails already imported for the mailer (live inbound or an earlier backfill) and emails this mailbox sent through Edith are skipped and counted; emails it received from other Edith mailers are imported. The mailbox's own address and aliases are ignored; a request naming only those returns 400. Requires an active incoming webhook on the mailer (422 otherwise). Several participants jobs can run in parallel on one mailer; a participants job and a full/single-conversation job refuse each other with 409.

Rules:

  • window_end is optional and defaults to now.
  • Idempotent per mailer for full and single-conversation imports — an active job returns 409 with the existing jobId.
  • Supported for Google (Gmail) and Microsoft (Outlook) OAuth mailboxes, and for basic username/password IMAP mailboxes (connection_type: basic with config_type: imap or smtp_imap).

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.

    participants string[]

    Possible values: <= 50

    Up to 50 bare emails. Imports every email exchanged with these contacts (From/To/Cc/Bcc, all folders except spam/trash/drafts, whole history up to now). Cannot be combined with participant, count, window_start or window_end. The mailbox's own address and aliases are ignored.

    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...