Skip to main content

Domain health is now refreshed every day, and a flaky lookup can no longer switch a record off

Domain health used to be refreshed only when someone read it, so the first read after a long gap could return a check that was days old.

  • Daily refresh. The daily DNS check that already watches every verified domain now also records the result for domains that pass, so emailAuthCheckedAt and cacheAgeSeconds stay within about a day for them. It never switches a record off, and it can turn DMARC on if the record appeared.
  • No switch-off on a single failed lookup. The refresh that a stale read starts in the background now looks again after a short pause before it marks DKIM, SPF or DMARC as no longer configured. Sending is blocked on those flags, and a DNS lookup can fail once and succeed a moment later. A record that really is gone is still switched off, one check later.
  • Unchanged. refresh=true still runs one live check and reports exactly what it found. A domain that fails both checks still gets the DNS drift email, once per 7 days.

Documentation changed

Domain health says how old it is and what to do when it is stale

Domain health (GET /api/public/v1/domains/{id}/health, GET /api/public/v1/motor-blocks/{id}/domain-health, and the matching MCP tools) is served from the last stored DNS check. For a domain nobody has read for a while that check can be days old. The response now says so:

  • cacheAgeSeconds is the age of the stored check.
  • nextAction appears when a refresh has started: read again in about ten seconds, or pass refresh=true to wait for a live check.
  • dmarc.policy is not reported yet and is always null. Use dmarc.configured to know whether a DMARC record exists.

Documentation changed

Send dry run now shows your remaining allowance and warnings

POST /v1/send with dryRun: true (and motorical_send_email on its default dry run) now returns two extra fields on top of the validated message:

  • data.limits shows the Motor Block's burst, hourly and daily allowance right now: used, limit, remaining and resetInSeconds, plus throttled. It uses the same figures as the rate-limits endpoint.
  • data.warnings is a list of { code, message }. Codes: NO_TEXT_PART (HTML without a plain-text alternative), SUBJECT_LONG, OVER_LIMIT (this many recipients would exceed an allowance), NEAR_LIMIT, THROTTLED. Warnings do not block anything; they say what a real send would run into.

Nothing changes for real sends.

Documentation changed

MCP docs: an error catalogue, smaller tool pages, and when each tool is not listed

  • MCP errors and what to do lists every code a tool call can return, what it means and what an agent should do next. Branch on code, not on the message. Codes assigned by the authentication layer (for example insufficient_scope, authorization_revoked) keep their lowercase spelling in the top-level code as well as in details.
  • The tool reference now comes in slices. The full MCP tool reference is large; there is now one page per area (sending, analytics, domains, sandbox, webhooks, Motor Blocks, Communications), each listed in llms.txt, so an agent can fetch only the part it needs.
  • Every tool entry has a "Not listed" row saying when the tool is absent from a connection's tool list (missing permission, past the sandbox phase, or never over OAuth).

Documentation changed

Motor Block config now shows the limits actually enforced, including the burst limit

  • effectiveLimits on the config response. GET /api/public/v1/motor-blocks/{id}/config (and motorical_get_config) now returns effectiveLimits with dailyVolume, hourlyRate, burstLimit and throttled: the limits that are enforced right now, which is the lower of what you configured and any reputation throttle, with defaults filled in. The existing limits field is unchanged and still shows only what was configured, so it can leave out burstLimit when you never set one. Read effectiveLimits to know what will actually bind.
  • Clearer MCP tool descriptions. motorical_list_motor_blocks now says it lists every block the connection covers (id and name), while motorical_motor_block_list lists manageable production blocks with type, domain and status, so their counts can differ. motorical_send_email says its sandbox advice applies to sandbox accounts only.

Documentation changed

MCP: errors now carry a code and a next step, and delivery rates count only finished messages

  • Errors have a shape you can act on. A failed Motorical tool call now returns code (for example NOT_FOUND, FORBIDDEN, RATE_LIMITED, MOTOR_BLOCK_REQUIRED), a plain error message with no internal route in it, a hint naming the next move, and the existing status and details. When a connection covers several Motor Blocks and none was named, the error lists them as candidates (id and name). Branch on code, not on the message text.
  • One Motor Block granted means no motorBlockId needed. Tools that act on a Motor Block now use the single granted block when you leave the id out. With several granted, the error above lists the choices.
  • Delivery rates use one definition. Overview and provider figures count a message as accepted once the receiving server took it (delivered, processed or complained) and divide by finished messages only (accepted, bounced or failed). Messages still queued or deferred are reported as pending and no longer pull the rate down. The response says which basis it used (rateBasis) and when it was generated (generatedAt).
  • The 200 bucket in error-code breakdowns is now labelled "Accepted (exact SMTP reply not recorded)", because the exact reply text is not stored for those messages.

Documentation changed

Templates and tests: honest footers, test sends, and deleting

  • Footer. A template made from a starter uses the reason you give, your brand kit footer text, or a neutral "sent by" line. It never says "you subscribed" on its own, and the response warns when it fell back to the neutral line.
  • Test sends. POST /templates/{id}/test-send (and comms_send_template_test) sends one copy to the account owner without a campaign. Test copies of a template or a campaign say that their links are placeholders pointing to motorical.com.
  • Delete. DELETE /templates/{id} supports ?dry_run=true and lists the campaigns that use the template. comms_delete_template and comms_delete_campaign need the manage:comms.audience permission; a deleted campaign goes to the recycle bin.
  • Reports. GET /campaigns/{id}/report includes open_tracking.enabled; the MCP report shows open figures as unmeasured when tracking is off.

Documentation changed

Audience filters: an end date now includes the whole day

  • A bare end date includes the whole day. date_to: "2026-11-04" used to mean 00:00 UTC at the start of 4 Nov, so a one-day range returned nobody. It now runs to 23:59:59 UTC. A full timestamp is still taken exactly.
  • Results explain themselves. comms_search_audience, comms_audience_summary and a filtered comms_derive_list dry run return as_of (when the counts were read) and interpreted (the date range in plain words). The API endpoints POST /recipients/search and /summary return the same.

Documentation changed

Communications MCP: search and summarise the whole audience, and make a list from a filter

  • comms_search_audience searches every contact in the workspace, not one list: by domain, status, engagement, consent, suppression, campaign, import batch, dates, "on no list" or "not on these lists". Each person comes with the lists they are on. Addresses stay masked. API: POST /recipients/search.
  • comms_audience_summary returns counts only (by status, consent, engagement, domain and list, and how many people are on no list). API: POST /recipients/summary.
  • comms_suppression_info says whether one address is on the account-wide suppression list, why and since when. API: GET /suppressions/lookup?email=.
  • comms_derive_list accepts operation: "filter" with the same filter, for example "everyone at example.com who is not on the Newsletter list". It is a snapshot like every derived list, a dry run first, and suppressed people are copied but counted apart as not eligible.
  • comms_find_contact now also returns which lists the person is on.
  • Imports report more: would_change counts only rows that change something, a second row for the same address with a different name is reported as a name conflict (the first name is kept), a value that looks like a spreadsheet formula is dropped with a warning instead of rejecting the contact, and a suppressed row says why.
  • List cards carry each count once through the MCP: the legacy contact_count and suppressed_count are no longer shown next to member_count and suppressed_active_count.
  • API: GET /contacts/{id}/erase-impact shows what erasing one contact would remove before it is confirmed.

Documentation changed

Communications: delete a workspace from the API

DELETE /comm-api/api/workspaces/{id} permanently deletes a workspace together with its people, lists, templates, campaigns and webhooks. Send {"dryRun": true} first to see what would go; the real call must repeat the workspace name as confirmName. The default workspace cannot be deleted, and a workspace with a scheduled or sending campaign is refused until you cancel it. Account-wide suppressions are untouched. This is a person-only action: AI agents connected through MCP cannot delete a workspace.

Documentation changed

Communications: deleting a list can clean up its people; archive, undo an import, and the same in your AI agent

Deleting a list used to leave every person behind in the workspace. DELETE /comm-api/api/lists/{id} now takes contacts=keep (default) or contacts=delete_orphans, plus dry_run=true; people who unsubscribed, bounced, complained or are suppressed are always kept. New: archive and restore a list, list and undo imports (batch_id), clean up people on no list, and a warning (or 409 with strict) when two lists share a name.

In an AI agent connected to Motorical, the same actions are tools. Deleting needs a new, separate permission (manage:comms.audience) that you approve once; every one of these tools shows what it would do before it does it.

Documentation changed

MCP: motorical_whoami now answers billing questions

  • New. account.billing in motorical_whoami (and GET /api/public/v1/account/whoami): the plan price (amount in minor units, currency, interval), trial end, current period end and next renewal date, whether the plan cancels at period end and when it ends, this month's sends against the plan cap, and whether the payment method is ok or failing.
  • Who sees it. Every connection that can call whoami, with no extra scope. The same connection already reads the account's plan and owner email.
  • Never included. Invoices, receipts, invoice links, card details and tax ids.
  • Honest gaps. A value that cannot be resolved is null with its reason under billing.unavailable; nothing is guessed.

Documentation changed

Communications MCP: clearer rules for the assistant

  • Twelve rules, in one place. Look before acting, numbers only from the system, a preflight before every send, one confirmation for the exact action, anything irreversible is yours to decide, waiting is not failing, no invented codes, addresses always masked, honest errors.
  • Workspaces. If you only use your default workspace, the assistant never talks about workspaces. If you have several, it explains once, asks once, names the workspace it is working in, and confirms before acting in another brand's workspace.
  • What it cannot do, said plainly. It cannot delete your data, resubscribe or export anyone, send immediately, change your default workspace, create a webhook or see its secret, or see a real recipient address.
  • Nothing duplicated. Each tool's own steps stay in that tool's description; the numbers they quote (the scheduling window, the daily limit) are checked against the platform's settings by a test, so they cannot drift.

Documentation changed

Communications MCP: manage workspaces and webhooks

  • 9 new tools on the communications server. Two are read-only (comms_get_workspace_settings, comms_list_webhooks). Four need the new permission manage:comms.workspace (create a workspace, rename it, change its settings, add a sending identity) and three need manage:comms.webhooks (change, test, delete a webhook). Both are asked once, the first time they are needed, each on its own line; your first approval is unchanged.
  • Every change is a dry run first. The assistant shows you the before and after and needs your clear yes. Changing click consent comes with a plain explanation of what it does.
  • What an assistant cannot do. It cannot make a workspace the default, delete a workspace, replace or remove sending identities, create a webhook (its signing secret is shown once, to a person) or ever see a secret.
  • Webhook addresses are protected. Campaign events carry recipient email addresses, so an address change needs a confirmed preview, emails you first, and is refused if the email cannot be sent. Addresses are shown to the assistant as the host only.
  • API: POST /comm-api/api/workspaces/{id}/motor-blocks/add adds a verified domain's sending identity to a workspace without replacing anything. For assistants only: a new workspace email, no duplicate workspace names, a limit on webhook test events, and creating a webhook is refused. Nothing changes for the dashboard or other integrations.

Documentation changed

Communications MCP: new workspaces and sending identities are covered automatically

  • Default connections cover what you own now. If you approved a Communications connection without choosing specific workspaces, a workspace or marketing Motor Block you add later is covered at once. The approval screen says so in one line.
  • Always your own, always active. Only your own active workspaces and active marketing Motor Blocks are covered; one you deactivate or delete stops being covered immediately.
  • A chosen subset stays exactly that. If a connection was approved for specific workspaces, a later one is refused, and the refusal now says to reconnect and include it.
  • API: motorical_whoami reports coverage: "all" for such a connection, with the Motor Blocks it covers now. Nothing changes for other connections.

Documentation changed

Communications MCP: how a campaign did

  • 5 new read-only tools on the communications server: comms_get_campaign_report, comms_get_campaign_links, comms_get_campaign_timeline, comms_list_campaign_events and comms_get_analytics_overview. They use the permission you already approved (read:comms), so there is nothing new to approve.
  • Honest numbers. Every rate comes with its denominator ("118 of 120 handed off were delivered"), the time the numbers are from, and a note that open counts are estimates. A campaign that has not sent says there is no data yet.
  • Private by design. Recipient addresses are masked, IP addresses and user agents are never returned, and the query string of each clicked link is hidden.
  • API: events requested by a connected assistant are always redacted (GET /campaigns/{id}/events). Nothing changes for the dashboard or other integrations.

Documentation changed

Communications MCP: scheduling and cancelling, with its own permission

  • 2 new tools on the communications server: comms_schedule_campaign and comms_cancel_campaign. They need a new permission, send:comms.campaign, which is not part of your first approval: it is asked once, the first time a send tool is used, and shown on its own line ("Send campaigns to your contacts (this is what actually emails people)"). Connections you already have keep exactly what they had.
  • Scheduling is a preview first. The agent must show you the campaign, the subject, the sender, exactly how many people, the time with its weekday in your timezone, and every warning. It can only go ahead on your clear yes, with a token tied to that exact preview; if the numbers, the time or the template change, the token is refused and it must preview again.
  • The preflight must still be true. Scheduling compares what would be sent now with the preflight you were shown (the email, the lists, the exclusions and the number of people) and refuses with a list of what changed. A preflight older than 30 minutes is refused.
  • An assistant cannot send immediately. The send time must be 15 minutes to 90 days ahead, with an explicit timezone; a time that does not exist or happens twice because of daylight saving is refused. A connection can schedule at most 3 campaigns a day.
  • You are told. Every schedule and every cancel by an assistant sends you an email. Cancelling is final.
  • API: POST /campaigns/{id}/schedule accepts dry_run, scheduled_at, timezone and expected_preflight_version. Without them nothing changes for existing integrations or for the dashboard.

Documentation changed

Communications MCP: campaign drafts, preflight and a test email to you

  • 5 new tools on the communications server: comms_create_campaign, comms_update_campaign, comms_duplicate_campaign, comms_preflight_campaign and comms_send_test. They use the permission a connection already has (write:comms.content), so there is no new consent.
  • Drafts only. An agent can create and edit a draft and copy any campaign into a new draft. It cannot schedule, cancel or delete a campaign, or set a send time, a timezone or pacing. Every write is a dry run first.
  • An honest preflight. It shows who would receive the campaign and who would not and why, the forecast (an estimate) and every warning, and says plainly when no one would receive it. It sends nothing; it stores a compiled snapshot, and any later change makes it stale.
  • A test email goes to you only. The test send has no recipient field: it always goes to the account owner's own verified address, shown masked, and is rate limited.
  • API: dry_run on POST /campaigns and PATCH /campaigns/{id}/settings, and editing a draft's template_id, list_ids and exclude_list_ids through the settings call. Without them nothing changes for existing integrations.

Documentation changed

Communications MCP: contacts, with addresses always masked

  • 7 new tools on the communications server: comms_list_list_contacts, comms_find_contact, comms_import_contacts, comms_remove_from_list, comms_derive_list, comms_unsubscribe_contact and comms_add_suppression. They use the permissions a connection already has (read:comms and write:comms.audience), so there is no new consent.
  • Addresses are always masked. An agent sees ids, counts and addresses like j***@example.com, names as initials, and never a phone number. For real addresses you open the dashboard.
  • Consent is asked, not assumed. A real import needs the answer to "do these people know they will get your marketing email?", given as true or false. Every write is a dry run first. People who unsubscribed, bounced or are suppressed are never added back.
  • What an agent cannot do: delete or erase a contact, resubscribe anyone, export contact data, remove everything matching a search from a list, or send. Suppressions apply to the whole account.
  • API: POST /lists/derive accepts an Idempotency-Key, like the other creates, so a retried call returns the first list instead of making a second one.

Documentation changed

Communications MCP: templates, the brand kit and list cards can be written

  • 8 new write tools on the communications server: comms_create_template, comms_create_template_from_starter, comms_update_template, comms_apply_template_fixes, comms_duplicate_template, comms_set_brand_kit, comms_create_list and comms_update_list. They need write:comms.content (templates and the brand kit) or write:comms.audience (the list card).
  • Safe by construction. Every write is a dry run unless the agent passes dryRun: false. Creates carry an idempotency key, so a retry never makes a second copy. Updates return the previous values so they can be undone. Nothing deletes, imports contacts, schedules or sends.
  • One consent line. Reading and the two edit scopes now show as a single line on the consent screen: "View and edit your lists, contacts, templates and campaign drafts, and send test emails to you. This never emails your contacts." Sending keeps its own, separate line. A connection approved earlier keeps working read-only and is asked once for the missing permission when a write tool is first used.
  • API: expected_updated_at on PATCH /templates/{id}. Edit only the version you read; a template that changed since is not overwritten (409 STALE_TEMPLATE).
  • API: strict and dry_run on POST /lists and PATCH /lists/{id}. strict refuses a weak list card (422 LIST_CARD_INVALID); dry_run checks without writing. Without them nothing changes for existing integrations.

Documentation changed