Skip to content
Pidgely Docs

API reference · Contact capture

Import the recipients of the last 90 days

POSThttps://api.pidgely.com/contact-capture/backfill
View as Markdown

Starts a background import of the to and cc recipients of the e-mails of the last 90 days, with the same rules as the capture. Safe to run again: existing contacts keep their data. Follow backfill.progress with Retrieve the settings.

Starts a background import of the to and cc recipients of the e-mails of the last 90 days (the same rules as the capture). Idempotent: existing contacts keep their data. 409 backfill_running while one runs. Full access keys.

Authorization: Bearer pdg_…. An API key with full_access. A sending_access key gets 401 restricted_api_key.

Request

This endpoint is not in the SDKs yet; call it over HTTP.

cURL
curl -X POST 'https://api.pidgely.com/contact-capture/backfill' \
  -H "Authorization: Bearer $PIDGELY_API_KEY"

Response

200 OK

JSON
{
  "object": "contact_capture",
  "enabled": true,
  "exclude": [
    "*@fexxo.com.br",
    "noreply@*"
  ],
  "segment_id": "0199d7f5-9a40-7e11-a2b3-8c4d5e6f7a90",
  "backfill": {
    "status": "running",
    "started_at": "2026-10-22T12:00:00Z",
    "finished_at": null,
    "scanned": 18240,
    "added": 3112,
    "progress": 0.42,
    "error": ""
  }
}

Response fields

Name Type Required Description
object string Yes Object type. One of contact_capture.
enabled boolean Yes Save the recipients of your e-mails as contacts (on by default).
exclude string[] Yes —
segment_id string | null Yes The automatic "Sent mail" segment (null until the first contact is saved). UUID.
backfill object Yes —
backfill.status string Yes Current status. One of idle, running, done, failed.
backfill.started_at string | null Yes Format: date-time.
backfill.finished_at string | null Yes Format: date-time.
backfill.scanned integer Yes E-mail recipients read so far.
backfill.added integer Yes Contacts created so far.
backfill.progress number Yes 0 to 1 (by time covered).
backfill.error string Yes —

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status Name When
401 missing_api_key, restricted_api_key No Authorization: Bearer header, or a sending_access key called an endpoint that needs full_access.
403 invalid_api_key, validation_error The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
409 — Conflict (backfill_running)
422 validation_error A field is missing or invalid; message names it.
429 rate_limit_exceeded Too many requests per second. Wait for Retry-After seconds.
409 backfill_running An import is already running.