Integrations

The Integration hub (Admin → Integrations) connects PeoplePit to other systems over their web APIs — a payment provider, a form service, a national federation — entirely through configuration. Define where to call, what to call, test it interactively, then schedule jobs that pull records in on a cadence.

Connectors

A connector describes one external system. Three types are supported:

• REST API — its base address, how to authenticate, and any default headers. Supported authentication: none, API key, bearer token, username/password, OAuth2 client credentials, and OAuth2 authorization code — a “Connect” button that walks through the provider’s consent screen once and then refreshes access automatically.
• POP3 mailbox — an email inbox as a data source: mail server host, port and TLS (on by default), plus the mailbox username and password. See Reading a mailbox below.
• Gmail mailbox — a Gmail account (including a personal one) as a data source via the Gmail API, covering received and sent mail. See Reading a Gmail mailbox below.

Secrets — API keys, passwords, client secrets — are entered once, stored encrypted, and never shown again (they display as ********). They are also never included when configuration is exported: on the target workspace an administrator re-enters them.

Endpoints

An endpoint is one callable operation on a connector — “list orders”, “get member” — with its method, path, query and body, all supporting {{placeholders}} filled at run time. You also tell it where the records are in the response, and how the API paginates, so a job can walk through all pages automatically.

Reading a mailbox (POP3)

A POP3 mailbox connector turns incoming email into records — support requests into tickets, replies into activity notes, form-to-mail services into structured data. Create a connector of type POP3 mailbox, then add an endpoint with the fetch options:

• Max messages per run — a per-run cap (newest messages first).
• Only messages received since the job’s last run — an incremental cursor, like {{lastRunAt}} on REST endpoints.
• Delete fetched messages from the server — off by default; leave it off and dedupe in the job instead if other systems also read the mailbox. Deletion only happens on job runs — the test console never modifies the mailbox.
• Store attachments as files — uploads each attachment (up to 10 per email, 10 MB each) into the workspace’s file storage, so attachments holds real downloadable file values instead of just names and sizes. Storage is deduplicated by content — polling the same mailbox again reuses the already-stored file instead of uploading a copy, so repeated runs never grow your file storage. Map attachments into a File field to see them as download links on the record, or attachments.0 for just the first one.

Inline images in email bodies (cid: references, which only exist inside the original message) are automatically embedded as self-contained data URLs so they render wherever the HTML is stored — size-capped to keep values within limits.

Each fetched email becomes one record with the fields subject, from, fromName, replyTo (the sender’s Reply-To address if set, otherwise their from — map this as “where our reply should go”), to, cc, date, text (plain body), html, replyText/replyHtml (just the reply’s own content, with the quoted thread stripped — map these when you only want what the sender wrote; for emails sent by PeoplePit with the Send-email step’s Reply input, the boundary is exact — the reply comes back precisely as it was written, no guessing), messageId, inReplyTo, references (threading headers — which message this one replies to, and the full ancestor chain), uid, attachments and size — map them in a job like any API response. To thread replies, store messageId on each record and use inReplyTo to look up the parent (a job field mapping in lookup mode resolves it to a reference). Match on messageId with skip so re-runs never import the same email twice. To keep the email’s formatting, map html into a Rich text field whose HTML content setting is Full HTML (Admin → Field library) — otherwise tables and styles are stripped down to the editor-formatting subset; map text instead if you only need the plain body. Synced bodies stored this way can also be inspected and hand-edited as raw HTML on the record — the field’s editor opens in its </> HTML source mode with a live preview. The test console works too: press Run to see the parsed messages before wiring a job. Two test-console notes: since last run has no effect there (the last-run date belongs to a job), and messages are never deleted by a test run.

Note

POP3 reads the whole inbox as one list — folders/labels and “mark as read” are IMAP concepts and don’t apply. Use the since last run option plus a messageId key field for clean incremental syncs. For a Gmail account, prefer the Gmail mailbox connector below — it reads sent mail and labels too.

Reading a Gmail mailbox

A Gmail mailbox connector reads a Gmail account through the Gmail API — including sent mail, which POP3 can’t see — using your own Google sign-in (“Connect with Google”) instead of a password. It is strictly read-only: PeoplePit never modifies or deletes anything in the mailbox.

One-time Google setup

You connect Gmail through your own (free) Google Cloud project, so your mail is only ever authorized to you:

1. At console.cloud.google.com, create a project and enable the Gmail API (APIs & Services → Library).
2. Configure the OAuth consent screen: user type External, add the scope https://www.googleapis.com/auth/gmail.readonly, and set the Publishing status to “In production”. This matters: an app left in Testing status has its authorizations expire after 7 days, and your sync would stop weekly until you reconnect. In production, an unverified app just shows a “Google hasn’t verified this app” warning on the consent screen — for connecting your own account, click Advanced → Continue.
3. Create an OAuth client ID (type Web application) and add the redirect URI shown in the PeoplePit connector editor (one for each environment you use). Copy the client ID and client secret.

Connecting

In Admin → Integrations, create a connector of type Gmail mailbox, paste the client ID and client secret, save, and press Connect — you sign in at Google, approve read-only access, and land back on the connector showing Connected as you@gmail.com. Reconnect repeats the flow (for example after revoking access at myaccount.google.com/permissions); Disconnect forgets the authorization. If a fetch ever fails with “Authorization expired or revoked — press Connect to re-authorize”, that one button is the fix.

Fetch options

Add an endpoint with the Gmail fetch options:

• Search query — any Gmail search (from:…, has:attachment, …), combined with the options below.
• Scope — which mail — check Inbox, Sent, add other labels, or leave everything unchecked for all mail. Checking Inbox and Sent is the common setup: one endpoint returns both directions, and each record’s direction field says received or sent.
• Max messages per run, only since the job’s last run, store attachments as files, and include spam & trash — same behaviour as their POP3 counterparts (attachments are stored deduplicated, inline images are embedded).

The records

Each message becomes one record with the same fields as POP3 (subject, from, fromName, replyTo, to, cc, date, text, html, replyText/replyHtml, messageId, inReplyTo, references, uid, attachments, size) plus direction (sent | received), threadId, labelIds and snippet. Map them in a job exactly like a POP3 endpoint — match on messageId with skip so re-runs never import the same email twice. Because the Send-email step stamps its own messageId on outgoing mail, a Sent sync reconciles emails PeoplePit sent with the records it already created instead of duplicating them.

The test console

The Test console is your in-app scratchpad: pick a connector, define or select an endpoint, fill the parameters, and Run — you see the status, timing, record count and the full pretty-printed response. Iterate here until the endpoint returns exactly the records you expect, before any job depends on it.

Jobs — pulling data in

A job runs an endpoint on a schedule and turns the results into records:

1. Schedule — manual, every N minutes, or daily at a time.
2. Connector + endpoint + parameters — what to call. Jobs can ask only for changes since the last successful run, so recurring syncs stay fast.
3. Mapping — which record type to create, and how each incoming field maps to yours (with simple transforms like trim, upper/lower case, date parsing, and defaults).
4. Key field — the unique identifier (an external ID, an email) so re-runs update or skip existing records instead of duplicating them.

Jobs reuse the same machinery as file imports: validation, record IDs, workflows and notifications all apply to synced records.

Multi-step mappings

One incoming record can produce several of yours, in order: a payment provider’s order first upserts the Person (matched by email), then the Payment (matched by the provider’s ID) with its payer pointing at that person. Steps can also look up existing records by any field to resolve references, and each step can carry an “Only when field has a value” guard — e.g. set it to email on the Person step to skip creating people from rows without an email (guarded rows count as skipped in the run). For transforms the screen can’t express (say, converting cents to euros), a job can switch to an advanced script mode.

Pipelines

Chain jobs with Then run — sync people, then sync their payments. The chain runs in order and stops if a step fails; chained jobs fire only through their parent.

The call log

Every external call — from the test console or a job — is recorded in the Call log: request, response, status, timing, with credentials always redacted. Each job also keeps a run history with created/updated/skipped/failed counts — click a run to see which records were created, updated or skipped, each linked to the record itself (the first 100 per outcome are listed), plus any failed source rows with the reason. When a sync misbehaves, the answer is in the log.

Triggering a job from a workflow

A workflow transition can carry Run integration job — clicking “Send to accounting” on a record fires the transition and the job (with its pipeline). Integration becomes a button your team presses, and automations can run jobs too.