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
participantto import the whole mailbox/window. Provide at least one ofwindow_start(RFC3339) orcount. - Single conversation — set
participantto a bare email to import only mail with that address (from:<participant>ORto:<participant>). Defaults to the last 1 year whenwindow_startis omitted. - Participants — set
participantsto 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 withparticipant,count,window_startorwindow_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_endis 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: basicwithconfig_type: imaporsmtp_imap).
Request
Path Parameters
Mailer ID
- application/json
Body
required
History backfill request
Optional cap on emails delivered, newest-first. 0/omitted = uncapped; clamped to the server max (default 1000).
folders
object
Single bare email. Provide it to import only the conversation with that address (from:/to:); omit for a full mailbox/window import.
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.
Newest point (RFC3339). Optional; defaults to now.
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
- 202
- 400
- 404
- 409
- 422
History backfill accepted
- application/json
- Schema
- Example (from schema)
Schema
{
"jobId": "01JC3BBW8S9YGX2VNKG5MD7BTA",
"success": true
}
Bad Request / more than 50 participants / only the mailbox's own addresses
- application/json
- Schema
- Example (from schema)
Schema
{
"error": "string",
"success": false
}
Mailer not found
- application/json
- Schema
- Example (from schema)
Schema
{
"error": "string",
"success": false
}
Active history backfill already exists / mailer inactive
- application/json
- Schema
- Example (from schema)
Schema
{
"error": "string",
"jobId": "01JC3BBW8S9YGX2VNKG5MD7BTA",
"success": false
}
Provider not supported for history fetch / no active incoming webhook
- application/json
- Schema
- Example (from schema)
Schema
{
"error": "string",
"success": false
}