How reference emails are sent
Creating a reference request never sends anything by itself — a follow-up PATCH (or the candidate’s own reply) does.
A candidate created with documents seeded from their CV also seeds reference_requests rows for their prior employers — the bot asks the CANDIDATE for each referee’s email over WhatsApp as part of the normal conversation, with no API call needed from you.
POST /candidates/{id}/references only CREATES the row — it never sends an email itself. A supplied address is classified immediately: a professional-looking domain becomes pending_send; one of these personal domains becomes flagged instead and is never auto-sent:
gmail.comhotmail.comyahoo.comoutlook.comicloud.comyahoo.co.ukhotmail.co.uk
To have the CANDIDATE supply the email instead of you, create with ask_candidate_fields: ["referee_email"] and no referee_email. Whichever way the address arrives, the first PATCH /references/{id} call that captures it triggers the actual send, unless you pass send: false.
Outstanding referees are chased by email up to reference_attempts_max times (see The candidate object) — set a candidate’s reference_chase_attempts_override to 0 via Update outreach settings to disable chasing for one candidate entirely.
Which template is used#
Every reference email — the initial send and every chase — is rendered from one of three sources, tried in this order: the template_id pinned to that specific request (see Reference templates), else the recruiter’s own default template, else Onboardly’s built-in copy. A resolution failure at any tier — including a template deleted after it was pinned — degrades silently to the next tier rather than failing the send.
Automated chase emails never read a template at all — they always use the built-in chase copy, whatever is pinned on the request or set as the recruiter’s default. Only the initial send (and a manual resend) can use a recruiter-authored template.