Skip to content

Start a history backfill

POST
/v1/grants/{id}/backfill
curl --request POST \
  --url https://api.inboxcnx.com/v1/grants/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/backfill \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "days": 30 }'

Starts a history backfill that delivers a grant’s older mail, for an end user who wants mail from before the connect. At most one history backfill runs per grant. It delivers every mail of the range that matches the grant’s folders and labels (effectiveRoles, subscribedLabels), or the part of them given as roles and labels, as message.received with data.origin: "backfill", and stores only mail within the grant’s retention. Mail the grant already received is not delivered or billed again, so overlapping ranges cost nothing twice. Backfill mail counts against the allowance like live mail, but never against the Profile’s limits, which cap new mail only. The run waits while the grant is paused or blocked, or its mailbox needs a reconnect, and continues on its own. Subscribed endpoints receive grant.backfill_completed when it ends. The range is { "since": "<ISO date>" }, { "days": n } or { "all": true } and ends at the time of the request. roles and labels narrow the run to part of the grant’s filter, e.g. one label just added; giving one of them counts the other as empty. Without them the run follows the grant’s filter as it stands while it runs.

Requires the write:connections scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Request Body

Section titled “Request Body”
Media typeapplication/json
Any of:
object
since
required
string format: date-time
roles
Array<string>
Allowed values: inbox sent archive drafts junk trash
labels
Array<string>
<= 100 items

Example 

{
  "days": 30
}

Responses

Section titled “Responses”

201

Section titled “201”

The run, started

Media typeapplication/json
object
id
required
string format: uuid
grantId
required
string format: uuid
kind
required
string
Allowed values: history catch_up
since
required
string | null
until
required
string | null
roles
required
Array<string> | null
labels
required
Array<string> | null
status
required
string
Allowed values: running done cancelled
waitingReason
required
string | null
listed
required
integer
published
required
integer
estimatedMessages
required
integer | null
createdAt
required
string
finishedAt
required
string | null

Example 

{
  "kind": "history",
  "status": "running"
}

400

Section titled “400”

Invalid range. invalid_subset: roles or labels name something outside the grant’s filter, or nothing

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

The credential lacks the write:connections scope

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

Section titled “404”

No such grant for the caller’s organization and application

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

409

Section titled “409”

backfill_running: a history backfill is already running. grant_not_processed: the grant is revoked, paused or blocked, or its mailbox needs a reconnect

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}