Skip to content
Pidgely Docs

API reference · Contact capture

Update the contact capture settings

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

Turns the capture on or off and sets up to 100 excluded addresses or patterns (* matches anything: *@yourcompany.com, noreply@*). Turning it off stops new captures; contacts already saved stay.

Turns the capture on or off and sets the excluded addresses and patterns. Full access keys.

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

Body parameters

JSON object.

Name Type Required Description
enabled boolean No —
exclude string[] No Addresses or patterns with * (*@example.com, noreply@*) that are never saved.

Request

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

cURL
curl -X PATCH 'https://api.pidgely.com/contact-capture' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true,
  "exclude": [
    "*@fexxo.com.br",
    "noreply@*"
  ]
}'

Response

200 OK

JSON
{
  "object": "contact_capture",
  "enabled": true,
  "exclude": [
    "*@fexxo.com.br",
    "noreply@*"
  ],
  "segment_id": "0199d7f5-9a40-7e11-a2b3-8c4d5e6f7a90",
  "backfill": {
    "status": "done",
    "started_at": "2026-10-22T12:00:00Z",
    "finished_at": "2026-10-22T12:04:10Z",
    "scanned": 18240,
    "added": 3112,
    "progress": 1,
    "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).
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.
422 validation_error A pattern is empty, too long or has characters an address cannot have.