Skip to content

Docs / All tools / Loop II: Acquisition

outbound.mail.consent_record

Record the lawful basis for emailing a contact.

0 credits. Free: compliance step.

Example prompt

Send this to your AI app when Heelo is connected:

Record that [email protected] gave express consent through our sign-up form on November 3, 2026.

Input fields

FieldTypeDescription
contact_idRequiredstringThe contact's id, from outbound.mail.contact_add or contact.resolve.
lawful_basisRequired"express" | "implied" | "legitimate_interest"The basis for mailing this person. A CA contact needs express or implied (implied lasts two years from obtained_at); a GB individual needs express.
sourceRequiredstringWhere the consent came from, for example 'signup form on example.com'.
evidence_urlRequiredstringWhere the evidence of the consent is kept: a URL or a reference.
obtained_atRequiredstringWhen the person agreed: ISO-8601 with a timezone, for example 2026-10-14T09:30:00Z. Not in the future.
expires_atstringWhen the consent ends: ISO-8601 with a timezone, after obtained_at. Leave it out for no end.
subscriber_type"individual" | "corporate" | "unknown"Also sets the contact's subscriber type. Leave it out to keep the stored one.

Code

The call with the input fields that the tool needs. Replace each word in capitals, such as CONTACT_ID. Set HEELO_API_KEY to your API key.

import os
import requests

response = requests.post(
    "https://toolsprimitives.uk/v1/tools/outbound.mail.consent_record/invoke",
    headers={"Authorization": f"Bearer {os.environ['HEELO_API_KEY']}"},
    json={"input": {
        "contact_id": "CONTACT_ID",
        "lawful_basis": "express",
        "source": "SOURCE",
        "evidence_url": "https://example.com",
        "obtained_at": "2026-12-01T09:00:00Z",
    }},
    timeout=120,
)
response.raise_for_status()
print(response.json())