Notices API

View as Markdown Open in Claude

The legally required acknowledgment, trial-ending, renewal, yearly-terms, price-change and cancellation emails, timed from the legal catalog: you send them and Checkbox tracks them (mode merchant, the default), or Checkbox sends them for you (mode checkbox).

Operation	Endpoint
Retrieve notice settings	`GET /v1/sites/{site}/notice_settings`
Update notice settings	`POST /v1/sites/{site}/notice_settings`
List due notices	`GET /v1/notices/due`
List notice email templates	`GET /v1/notices/templates`
Check a notice email template	`POST /v1/notices/templates/check`
Retrieve a due notice	`GET /v1/notices/{notice}`
Mark a due notice as sent	`POST /v1/notices/{notice}/sent`
Record a due notice as missed	`POST /v1/notices/{notice}/missed`

The NoticeSettings object

Checkbox Notices for a site: the legally required emails Checkbox sends on the merchant's behalf.

Field	Type	Description
`id`	string	Unique identifier of the notice settings (ntcs_…).
`object`	enum	String representing the object's type. Always "notice_settings".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`site`	string	The site.
`mode`	enum	merchant ("You send", the default): you send the required emails and Checkbox tells you what and when (listDueNotices, notice.due), checks your templates and confirms each send. checkbox: Checkbox sends them for you (enabled_kinds). One of `merchant`, `checkbox`.
`bcc`	string	The site's inbound address. Copies to it confirm a notice only when your sending domain authenticates them (DKIM/SPF, a trusted sending domain) and they go to the subscriber; to confirm any copy, BCC each due notice's own bcc address instead (listDueNotices / the notice.due webhook).
`enabled_kinds`	array of enum	mode checkbox: the notices Checkbox sends for the merchant.
`brand_name`	string \| null	Brand shown in notices (defaults to the site name).
`product_name`	string \| null	Product name used in notices.
`logo_url`	string \| null	Logo URL (https).
`support_email`	string \| null	Reply-to / support address.
`cancel_url`	string \| null	Where subscribers cancel online (site domain, hosted cancellation page or billing portal).
`brand_color`	string \| null	Hex brand colour.
`from_local_part`	string	Mailbox name of the sender.
`subscribers`	object \| null	Who Checkbox can send notices to (null when unknown).
`subscribers.active`	integer	Active subscriptions Checkbox knows from the billing platform.
`subscribers.with_email`	integer	Of those, how many have a known email address (Checkbox can only send to these).
`policy`	object \| null	Confirmed cancellation policy (required before notices go out).
`policy.cancel_timing`	enum	When a cancellation takes effect. One of `period_end`, `immediately`.
`policy.confirmed`	integer	When the policy was confirmed. Unix timestamp in seconds.
`sender`	object \| null	Sending address, when one is available.
`sender.from`	string	From header.
`sender.own_domain`	boolean	Sent from the merchant's verified domain.
`sending_domain`	object	Custom sending domain status (set it up in the dashboard).
`sending_domain.domain`	string \| null	Custom sending domain.
`sending_domain.status`	string	none, pending, verified or failed.
`delivery_configured`	boolean	This Checkbox deployment can send email.
`kinds`	array of objects	Every notice kind.
`updated`	integer \| null	Last change. Unix timestamp in seconds.
`next_action`	NextAction \| null	What the caller (often an AI agent) should do next.

Retrieve notice settings

GET /v1/sites/{site}/notice_settings

Who sends the site's required emails (mode), the BCC address, which notices Checkbox sends in checkbox mode, and what to do next (next_action).

Scope notices:read · Operation retrieveNoticeSettings

SDK: checkbox.noticeSettings.retrieve() (Node) · checkbox.notice_settings.retrieve() (Python). MCP / agents: operation retrieveNoticeSettings.

Parameters

Parameter	In	Type	Description
`site` required	path	string	Unique identifier of the site (site_…).

Returns

Returns a NoticeSettings object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/notice_settings \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const noticeSetting = await checkbox.noticeSettings.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(noticeSetting);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notice_setting = checkbox.notice_settings.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(notice_setting)

Response

{
  "id": "ntcs_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "notice_settings",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "mode": "merchant",
  "bcc": "k_3f9a1c2e@inbound.checkbox.site",
  "enabled_kinds": [
    "acknowledgment",
    "renewal_reminder"
  ],
  "brand_name": "Acme Coffee Club",
  "product_name": "Coffee subscription",
  "logo_url": null,
  "support_email": "help@acme.example",
  "cancel_url": "https://acme.example/account/cancel",
  "brand_color": "#1f2937",
  "from_local_part": "notices",
  "subscribers": {
    "active": 12,
    "with_email": 12
  },
  "policy": {
    "cancel_timing": "period_end",
    "confirmed": 1793318400
  },
  "sender": {
    "from": "Acme Coffee Club <notices@acme.example>",
    "own_domain": true
  },
  "sending_domain": {
    "domain": "acme.example",
    "status": "verified"
  },
  "delivery_configured": true,
  "kinds": [
    {
      "kind": "renewal_reminder",
      "label": "Renewal reminder",
      "description": "Sent before an annual renewal.",
      "enabled": true,
      "check_ids": [
        "reminder.annual_renewal_notice"
      ]
    }
  ],
  "updated": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

Update notice settings

POST /v1/sites/{site}/notice_settings

Chooses who sends the required emails (mode: merchant = you send them and Checkbox tracks them, the default; checkbox = Checkbox sends them), and sets branding, cancel_url and the confirmed cancellation policy. In checkbox mode, turning a notice on (enabled_kinds) requires cancel_url, a confirmed policy, a connected Stripe or Recharge account and a sending address; otherwise resource_conflict explains what is missing.

Scope notices:write · Idempotent (send Idempotency-Key) · Live mode needs activation · Operation updateNoticeSettings

SDK: checkbox.noticeSettings.update() (Node) · checkbox.notice_settings.update() (Python). MCP / agents: operation updateNoticeSettings.

Parameters

Parameter	In	Type	Description
`site` required	path	string	Unique identifier of the site (site_…).

Body

Field	Type	Description
`mode`	enum	merchant: you send the emails (Checkbox tracks them); checkbox: Checkbox sends them. Turning an enabled_kinds notice on implies checkbox. One of `merchant`, `checkbox`.
`enabled_kinds`	array of enum	Notices to send (turning one on needs cancel_url, a confirmed policy and a connected Stripe/Recharge account). trial_reminder is accepted as an alias of trial_ending.
`brand_name`	string \| null	Brand name.
`product_name`	string \| null	Product name.
`logo_url`	string \| null	Logo URL (https).
`support_email`	string \| null	Support address.
`cancel_url`	string \| null	Online cancellation URL.
`brand_color`	string \| null	Hex colour.
`from_local_part`	string	Sender mailbox name.
`policy`	object \| null	Cancellation policy the notices state.
`policy.cancel_timing` required	enum	When a cancellation takes effect (must match your Terms). One of `period_end`, `immediately`.
`policy.confirm` required	enum	Confirms this matches your Terms and your cancellation flow.

Returns

Returns a NoticeSettings object.

In live mode before activation: 403 account_not_activated with next_action.operation_id: "createDomainVerification".

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/notice_settings \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "brand_name": "Acme Coffee Club"
}'

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const noticeSetting = await checkbox.noticeSettings.update('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', { brand_name: 'Acme Coffee Club' });
console.log(noticeSetting);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notice_setting = checkbox.notice_settings.update("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", brand_name="Acme Coffee Club")
print(notice_setting)

Response

{
  "id": "ntcs_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "notice_settings",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "mode": "merchant",
  "bcc": "k_3f9a1c2e@inbound.checkbox.site",
  "enabled_kinds": [
    "acknowledgment",
    "renewal_reminder"
  ],
  "brand_name": "Acme Coffee Club",
  "product_name": "Coffee subscription",
  "logo_url": null,
  "support_email": "help@acme.example",
  "cancel_url": "https://acme.example/account/cancel",
  "brand_color": "#1f2937",
  "from_local_part": "notices",
  "subscribers": {
    "active": 12,
    "with_email": 12
  },
  "policy": {
    "cancel_timing": "period_end",
    "confirmed": 1793318400
  },
  "sender": {
    "from": "Acme Coffee Club <notices@acme.example>",
    "own_domain": true
  },
  "sending_domain": {
    "domain": "acme.example",
    "status": "verified"
  },
  "delivery_configured": true,
  "kinds": [
    {
      "kind": "renewal_reminder",
      "label": "Renewal reminder",
      "description": "Sent before an annual renewal.",
      "enabled": true,
      "check_ids": [
        "reminder.annual_renewal_notice"
      ]
    }
  ],
  "updated": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

List due notices

GET /v1/notices/due

The legally required emails you owe subscribers (sites in "You send" mode, the default): kind, the subscriber (billing-platform ids), the legal window for the subscriber's state, the recommended send date, the copy-ready email and the BCC address. Default: everything not yet sent (upcoming, due, overdue), soonest first. Live keys list live subscribers' notices, test keys test-mode ones. Send each one on its send_date (inside its window), then call markNoticeSent (or BCC the notice's bcc address). Subscribe to the notice.due webhook to get each one on its send date.

Scope notices:read · Operation listDueNotices

SDK: checkbox.notices.listDue() (Node) · checkbox.notices.list_due() (Python). MCP / agents: operation listDueNotices.

Parameters

Parameter	In	Type	Description
`limit`	query	integer	Number of objects to return, 1-100 (default 10).
`starting_after`	query	string	Cursor: an object id; returns the objects after it (older).
`ending_before`	query	string	Cursor: an object id; returns the objects before it (newer).
`site`	query	string	Only this site (site_…). Default: every site of the account.
`status`	query	string	Comma-separated statuses (upcoming, due, sent, overdue, canceled, missed). Default: upcoming,due,overdue — what still needs sending.
`kind`	query	string	Comma-separated kinds (acknowledgment, trial_ending, renewal_reminder, annual_terms, price_change, cancellation_confirmation).
`subscription`	query	string	Only notices for this billing-platform subscription id.

Returns

Returns a list ({ object: "list", data, has_more, url }) of DueNotice objects.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl -G https://app.checkbox.site/v1/notices/due \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const notices = await checkbox.notices.listDue({ limit: 3 });
console.log(notices.data);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notices = checkbox.notices.list_due(limit=3)
print(notices.data)

Response

{
  "object": "list",
  "data": [
    {
      "id": "ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "due_notice",
      "livemode": false,
      "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "kind": "trial_ending",
      "label": "Trial-ending reminder",
      "required": true,
      "status": "due",
      "subscriber": {
        "platform": "stripe",
        "subscription": "sub_1QabcXYZ",
        "customer": "cus_Qabc123",
        "name": "Alex Rivera",
        "email_masked": "a•••@example.com",
        "region": "US-CA"
      },
      "window_start": 1793318400,
      "window_end": 1793318400,
      "send_at": 1793318400,
      "send_date": "2026-11-12",
      "anchor": 1793318400,
      "jurisdictions": [
        "US-CA"
      ],
      "requirement_ids": [
        "US-CA.17602.a.3"
      ],
      "citations": [
        "Cal. Bus. & Prof. Code § 17602(a)(3)"
      ],
      "email": {
        "template_id": "trial_ending.v1",
        "subject": "Your Acme Coffee free trial ends on November 19, 2026",
        "text": "Hi Alex,\n\nYour free trial ends on November 19, 2026. …",
        "html": "<div …><p …>Hi Alex,</p>…</div>",
        "missing_fields": []
      },
      "bcc": "k_3f9a1c2e+trial_ending.9f8e7d6c5b4a39281706f5e4d3c2b1a0@inbound.checkbox.site",
      "sent": {
        "at": 1793318400,
        "source": "bcc",
        "late": false,
        "provider_message_id": "re_9f8e7d6c",
        "evidence": null
      },
      "missed": {
        "at": 1793318400,
        "reason": "Subscriber already left; not sent."
      },
      "created": 1793318400,
      "updated": 1793318400,
      "next_action": {
        "type": "verify_domain",
        "message": "Verify your site domain to turn on live mode.",
        "operation_id": "createDomainVerification",
        "mcp_tool": "call_api",
        "endpoint": "POST /v1/sites/{site}/domain_verification",
        "url": "https://checkbox.site/docs/concepts/activation#verify"
      }
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}

List notice email templates

GET /v1/notices/templates

Copy-ready HTML + text templates for every required notice (acknowledgment with and without a trial, trial ending, renewal, yearly terms, price change, cancellation confirmation), with {{merge_fields}}. Each passes the preflight email check for its kind when filled. Pass ?site= to get each kind's BCC address too. Adapt one, then call checkNoticeTemplate.

Scope notices:read · Operation listNoticeTemplates

SDK: checkbox.notices.listTemplates() (Node) · checkbox.notices.list_templates() (Python). MCP / agents: operation listNoticeTemplates.

Parameters

Parameter	In	Type	Description
`site`	query	string	Site (site_…) whose BCC addresses to include.

Returns

Returns a list ({ object: "list", data, has_more, url }) of NoticeTemplate objects.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/notices/templates \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const notices = await checkbox.notices.listTemplates();
console.log(notices.data);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notices = checkbox.notices.list_templates()
print(notices["data"])

Response

{
  "object": "list",
  "data": [
    {
      "id": "trial_ending.v1",
      "kind": "trial_ending",
      "variant": "trial_ending",
      "label": "Trial-ending reminder",
      "when": "Before a free trial converts, inside the subscriber's state window.",
      "use_when": "A free trial is about to convert to a paid subscription.",
      "subject": "Your {{brand_name}} free trial ends on {{trial_end_date}}",
      "text": "Hi {{customer_name}},\n\nYour free trial ends on {{trial_end_date}}. …",
      "html": "<div …><p …>Hi {{customer_name}},</p>…</div>",
      "merge_fields": [
        "customer_name"
      ],
      "check_kind": "trial_reminder",
      "bcc": "k_3f9a1c2e+trial_ending@inbound.checkbox.site"
    }
  ],
  "merge_fields": [
    {
      "name": "trial_end_date",
      "description": "When the free trial ends and the first charge happens."
    }
  ],
  "has_more": false,
  "url": "/v1/notices/templates"
}

Check a notice email template

POST /v1/notices/templates/check

Checks your own version of a notice email: Checkbox fills the merge fields with the site's plan, brand and cancel URL (sample dates), then runs the preflight email check for the kind across the site's jurisdictions. Stateless. Fix what fails (or start from listNoticeTemplates) and check again until verdict is pass.

Scope notices:read · Operation checkNoticeTemplate

SDK: checkbox.notices.checkTemplate() (Node) · checkbox.notices.check_template() (Python). MCP / agents: operation checkNoticeTemplate.

Body

Field	Type	Description
`site` required	string	Site whose plan, brand, cancel URL and jurisdictions fill the merge fields and scope the check.
`kind` required	enum	Which notice the template is for. One of `acknowledgment`, `trial_ending`, `renewal_reminder`, `annual_terms`, `price_change`, `cancellation_confirmation`.
`subject` required	string	Your subject (merge fields allowed).
`text`	string	Your plain-text body (merge fields allowed).
`html`	string	Your HTML body (merge fields allowed).

Returns

Returns a NoticeTemplateCheck object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/notices/templates/check \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "kind": "trial_ending",
  "subject": "Your {{brand_name}} free trial ends on {{trial_end_date}}",
  "text": "Hi {{customer_name}}, your free trial ends on {{trial_end_date}}. Unless you cancel before then, you will be charged {{price}} every {{billing_period}} until you cancel. Cancel online anytime at {{cancel_url}}."
}'

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const notice = await checkbox.notices.checkTemplate({
  site: 'site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b',
  kind: 'trial_ending',
  subject: 'Your {{brand_name}} free trial ends on {{trial_end_date}}',
  text: 'Hi {{customer_name}}, your free trial ends on {{trial_end_date}}. Unless you cancel before then, you will be charged {{price}} every {{billing_period}} until you cancel. Cancel online anytime at {{cancel_url}}.',
});
console.log(notice);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notice = checkbox.notices.check_template(
    site="site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    kind="trial_ending",
    subject="Your {{brand_name}} free trial ends on {{trial_end_date}}",
    text="Hi {{customer_name}}, your free trial ends on {{trial_end_date}}. Unless you cancel before then, you will be charged {{price}} every {{billing_period}} until you cancel. Cancel online anytime at {{cancel_url}}.",
)
print(notice)

Response

{
  "object": "notice_template_check",
  "kind": "trial_ending",
  "verdict": "pass",
  "checks": [
    {
      "check_id": "reminder.trial_ending",
      "status": "pass",
      "explanation": "The reminder states the charge, the date and how to cancel."
    }
  ],
  "unknown_fields": [],
  "warnings": [
    {
      "code": "unknown_merge_fields",
      "message": "Unknown merge fields: {{plan}}."
    }
  ],
  "filled": {
    "subject": "Your Acme trial ends November 19, 2026",
    "text": "Hi Alex, …",
    "html": "<p>Hi Alex, …</p>"
  },
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

Retrieve a due notice

GET /v1/notices/{notice}

One notice you owe a subscriber, with its window, recommended send date, copy-ready email, BCC address and send status.

Scope notices:read · Operation retrieveDueNotice

SDK: checkbox.notices.retrieve() (Node) · checkbox.notices.retrieve() (Python). MCP / agents: operation retrieveDueNotice.

Parameters

Parameter	In	Type	Description
`notice` required	path	string	Unique identifier of the due notice (ntd_…).

Returns

Returns a DueNotice object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/notices/ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const notice = await checkbox.notices.retrieve('ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(notice);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notice = checkbox.notices.retrieve("ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(notice)

Response

{
  "id": "ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "due_notice",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "kind": "trial_ending",
  "label": "Trial-ending reminder",
  "required": true,
  "status": "due",
  "subscriber": {
    "platform": "stripe",
    "subscription": "sub_1QabcXYZ",
    "customer": "cus_Qabc123",
    "name": "Alex Rivera",
    "email_masked": "a•••@example.com",
    "region": "US-CA"
  },
  "window_start": 1793318400,
  "window_end": 1793318400,
  "send_at": 1793318400,
  "send_date": "2026-11-12",
  "anchor": 1793318400,
  "jurisdictions": [
    "US-CA",
    "US-FED"
  ],
  "requirement_ids": [
    "US-CA.17602.a.3"
  ],
  "citations": [
    "Cal. Bus. & Prof. Code § 17602(a)(3)"
  ],
  "email": {
    "template_id": "trial_ending.v1",
    "subject": "Your Acme Coffee free trial ends on November 19, 2026",
    "text": "Hi Alex,\n\nYour free trial ends on November 19, 2026. …",
    "html": "<div …><p …>Hi Alex,</p>…</div>",
    "missing_fields": []
  },
  "bcc": "k_3f9a1c2e+trial_ending.9f8e7d6c5b4a39281706f5e4d3c2b1a0@inbound.checkbox.site",
  "sent": {
    "at": 1793318400,
    "source": "bcc",
    "late": false,
    "provider_message_id": "re_9f8e7d6c",
    "evidence": null
  },
  "missed": {
    "at": 1793318400,
    "reason": "Subscriber already left; not sent."
  },
  "created": 1793318400,
  "updated": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

Mark a due notice as sent

POST /v1/notices/{notice}/sent

Records that you sent this notice (optionally with your email provider's message id). Idempotent: a notice already marked sent is returned unchanged. A send before window_start is refused (it does not satisfy the law: send again inside the window). An overdue notice marked sent stops failing its check and is recorded as late; a sent_at earlier than when it became overdue is refused (only the BCC copy can prove an in-window send). Canceled and missed notices cannot be marked. BCC'ing the notice's bcc address does the same with the email itself as evidence.

Scope notices:write · Idempotent (send Idempotency-Key) · Operation markNoticeSent

SDK: checkbox.notices.markSent() (Node) · checkbox.notices.mark_sent() (Python). MCP / agents: operation markNoticeSent.

Parameters

Parameter	In	Type	Description
`notice` required	path	string	Unique identifier of the due notice (ntd_…).

Body

Field	Type	Description
`provider_message_id`	string	Your email provider's message id (Resend / Postmark / SES), stored as proof.
`sent_at`	integer	When it was sent (unix seconds). Default: now. A time after the window closed records the notice as sent late; a time before window_start is refused (too early to count), and so is a time before an overdue notice became overdue.

Returns

Returns a DueNotice object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/notices/ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/sent \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const notice = await checkbox.notices.markSent('ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(notice);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notice = checkbox.notices.mark_sent("ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(notice)

Response

{
  "id": "ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "due_notice",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "kind": "trial_ending",
  "label": "Trial-ending reminder",
  "required": true,
  "status": "due",
  "subscriber": {
    "platform": "stripe",
    "subscription": "sub_1QabcXYZ",
    "customer": "cus_Qabc123",
    "name": "Alex Rivera",
    "email_masked": "a•••@example.com",
    "region": "US-CA"
  },
  "window_start": 1793318400,
  "window_end": 1793318400,
  "send_at": 1793318400,
  "send_date": "2026-11-12",
  "anchor": 1793318400,
  "jurisdictions": [
    "US-CA",
    "US-FED"
  ],
  "requirement_ids": [
    "US-CA.17602.a.3"
  ],
  "citations": [
    "Cal. Bus. & Prof. Code § 17602(a)(3)"
  ],
  "email": {
    "template_id": "trial_ending.v1",
    "subject": "Your Acme Coffee free trial ends on November 19, 2026",
    "text": "Hi Alex,\n\nYour free trial ends on November 19, 2026. …",
    "html": "<div …><p …>Hi Alex,</p>…</div>",
    "missing_fields": []
  },
  "bcc": "k_3f9a1c2e+trial_ending.9f8e7d6c5b4a39281706f5e4d3c2b1a0@inbound.checkbox.site",
  "sent": {
    "at": 1793318400,
    "source": "bcc",
    "late": false,
    "provider_message_id": "re_9f8e7d6c",
    "evidence": null
  },
  "missed": {
    "at": 1793318400,
    "reason": "Subscriber already left; not sent."
  },
  "created": 1793318400,
  "updated": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

Record a due notice as missed

POST /v1/notices/{notice}/missed

Records that an overdue notice was not sent and will not be (for example, the subscriber already left). Nothing is attested as sent: the notice moves to missed and stops failing its compliance check, and the record stays in the history. Only overdue notices can be recorded as missed. Idempotent.

Scope notices:write · Idempotent (send Idempotency-Key) · Operation markNoticeMissed

SDK: checkbox.notices.markMissed() (Node) · checkbox.notices.mark_missed() (Python). MCP / agents: operation markNoticeMissed.

Parameters

Parameter	In	Type	Description
`notice` required	path	string	Unique identifier of the due notice (ntd_…).

Body

Field	Type	Description
`reason`	string	Why it was not sent (kept with the record).

Returns

Returns a DueNotice object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/notices/ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/missed \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const notice = await checkbox.notices.markMissed('ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(notice);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

notice = checkbox.notices.mark_missed("ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(notice)

Response

{
  "id": "ntd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "due_notice",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "kind": "trial_ending",
  "label": "Trial-ending reminder",
  "required": true,
  "status": "due",
  "subscriber": {
    "platform": "stripe",
    "subscription": "sub_1QabcXYZ",
    "customer": "cus_Qabc123",
    "name": "Alex Rivera",
    "email_masked": "a•••@example.com",
    "region": "US-CA"
  },
  "window_start": 1793318400,
  "window_end": 1793318400,
  "send_at": 1793318400,
  "send_date": "2026-11-12",
  "anchor": 1793318400,
  "jurisdictions": [
    "US-CA",
    "US-FED"
  ],
  "requirement_ids": [
    "US-CA.17602.a.3"
  ],
  "citations": [
    "Cal. Bus. & Prof. Code § 17602(a)(3)"
  ],
  "email": {
    "template_id": "trial_ending.v1",
    "subject": "Your Acme Coffee free trial ends on November 19, 2026",
    "text": "Hi Alex,\n\nYour free trial ends on November 19, 2026. …",
    "html": "<div …><p …>Hi Alex,</p>…</div>",
    "missing_fields": []
  },
  "bcc": "k_3f9a1c2e+trial_ending.9f8e7d6c5b4a39281706f5e4d3c2b1a0@inbound.checkbox.site",
  "sent": {
    "at": 1793318400,
    "source": "bcc",
    "late": false,
    "provider_message_id": "re_9f8e7d6c",
    "evidence": null
  },
  "missed": {
    "at": 1793318400,
    "reason": "Subscriber already left; not sent."
  },
  "created": 1793318400,
  "updated": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). You remain solely responsible for your subscription program, and Checkbox takes on no legal liability for it (Terms). Checkbox is a System1 company; Trust center · Status. For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.

Notices API

#The NoticeSettings object

#Retrieve notice settings

#Parameters

#Returns

#Update notice settings

#Parameters

#Body

#Returns

#List due notices

#Parameters

#Returns

#List notice email templates

#Parameters

#Returns

#Check a notice email template

#Body

#Returns

#Retrieve a due notice

#Parameters

#Returns

#Mark a due notice as sent

#Parameters

#Body

#Returns

#Record a due notice as missed

#Parameters

#Body

#Returns

The NoticeSettings object

Retrieve notice settings

Parameters

Returns

Update notice settings

Parameters

Body

Returns

List due notices

Parameters

Returns

List notice email templates

Parameters

Returns

Check a notice email template

Body

Returns

Retrieve a due notice

Parameters

Returns

Mark a due notice as sent

Parameters

Body

Returns

Record a due notice as missed

Parameters

Body

Returns