Skip to main content

31 posts tagged with "api"

View All Tags

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

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: lists explain themselves, audience breakdown, exclusion lists, template lint and starters

Everything here is additive: existing requests and responses keep working.

  • Lists explain themselves. A list has a description, a kind, a source_label and a recorded provenance. GET /lists/{id} returns the whole card with counts computed on every read (member_count, eligible_count, unsubscribed_count, bounced_count, suppressed_count), the campaigns that use it and whether it is a one-time snapshot. PATCH /lists/{id} is now a partial update.
  • Know who will get it, and why not the others. compile and schedule return an audience breakdown whose included figure is the recipient count, with the people left out grouped by reason. A campaign with nobody left is refused with EMPTY_AUDIENCE. The report carries sync, so a zero that only means "not delivered to the report yet" is not read as a failure.
  • Add contacts as JSON. POST /lists/{id}/contacts/bulk takes up to 500 contacts, answers for every row, never adds back people who unsubscribed or bounced, and supports dry_run.
  • Build lists from lists. POST /lists/derive (union, intersection, difference) records how a list was made; GET /lists/compare shows the overlap of two lists; GET /lists/{id}/relations and GET /map show how lists, campaigns and templates connect.
  • Exclusion lists. A campaign can take exclude_list_ids: people on those lists are never sent to. A list that a campaign excludes can no longer be deleted (409 LIST_IN_USE, which also now protects lists used by unfinished campaigns).
  • Templates. POST /templates/preview shows what a recipient will see, with and without a name. GET /templates/rules, POST /templates/lint, /fix and /check-links give a rulebook, findings with ready fixes (nothing is saved until you PATCH) and a link check. Templates have a description, a kind and derived_from, and POST /templates/{id}/duplicate makes a copy that remembers its parent. Campaigns have a description.
  • Brand kit and starters. GET/PATCH /settings/brand-kit stores your sender name, postal address, colours and font once. GET /templates/starters lists seven starters, POST /templates/starters/{key}/render shows one without saving, and POST /templates/from-starter saves it as a normal template.
  • Readiness. GET /readiness names the first thing missing before a campaign can be sent.

Documentation changed

Communications: your own text version is kept, link rules, and clearer template deletes

  • Your text version is sent as you wrote it. Until now the plain-text part was always regenerated from the HTML when a campaign was compiled, replacing the one in the template. A template's own body_text is now kept exactly; only a template with none gets a generated one. The generated text is also much better: paragraphs and list items stay separate and every web link keeps its address (See the sale (https://shop.eu/sale)).
  • Only web links are click-tracked. sms:, whatsapp: and similar links are left exactly as written (they used to be wrapped in a web redirect that broke them), and validate reports them as non_web_link_scheme.
  • A merge variable inside a link address is refused. It could never be filled there. validate reports merge_variable_in_url (it blocks scheduling) and scheduling answers 400 MERGE_VARIABLE_IN_URL listing each link. Put the variable in the visible text instead.
  • Clear template deletes. 409 TEMPLATE_IN_USE now names the campaigns in the way (used_by, used_by_count), including finished campaigns and campaigns in the recycle bin. GET /templates and GET /templates/{id} show how many campaigns use a template. Bulk delete takes at most 100 ids and reports every id on its own (INVALID_ID, NOT_FOUND, TEMPLATE_IN_USE); a template that does not exist is no longer reported as deleted.
  • Examples fixed. The template examples now use {{name|there}} and no longer use {{identity_name}} (the contact's organisation, rarely filled) as if it were your brand.

Documentation changed

Communications: campaign forecast, sending limits and pacing

  • Forecast. POST /campaigns/{id}/compile and /schedule return forecast (estimated_completion_at, limiting_cap, the caps used, enforced) and warnings (will_take_hours, will_span_multiple_days). Call compile first to see the audience size and the time before you schedule.
  • Pacing. The campaign list, detail and report carry pacing: not_started, running, waiting_for_cap (with the reason, burst, hourly, daily, acct_hourly or acct_daily, and resumes_at), done or stopped. A campaign waiting for a limit is not stuck: it continues by itself when the hour or day rolls over. The report adds sent and remaining.
  • A campaign that can never be sent is refused. 400 CAMPAIGN_CANNOT_COMPLETE (reason: too_long or cap_zero) when, at your limits, it would take longer than the maximum (7 days). Only when limits are enforced for campaigns; until then forecast.enforced is false and nothing changes.

Documentation changed

Communications: campaigns now obey your sending limits

  • Campaigns are held to your limits. Until now a campaign was handed to delivery as fast as its chunk settings allowed and did not count against the Motor Block's hourly and daily limits or your plan's account ceiling. From 26 October 2026 it does. When a limit is reached the campaign pauses and continues by itself when the hour or day rolls over; nobody is skipped and nobody gets a message twice.
  • What you see. forecast on compile and schedule now has enforced: true, with warnings when a campaign needs hours or days, and pacing on the campaign shows waiting_for_cap with the reason and resumes_at while it waits. See Sending limits and pacing.
  • Room for transactional mail. Campaigns use at most 80 percent of the account-wide ceiling, so your transactional mail is not starved by a large send.
  • A campaign that could never be sent is refused at scheduling with 400 CAMPAIGN_CANNOT_COMPLETE, as described in the entry from earlier today.

Documentation changed

Communications: merge variables with fallbacks, test send, reply-to, and stricter templates

  • Merge variables are a closed set, with fallbacks. {{name}}, {{first_name}}, {{email}} and {{identity_name}}, plus the links {{unsubscribe_url}} and {{consent_url}}. Write {{name|there}} to use a fallback when a contact has no name. Any other tag is refused when you schedule (400 UNKNOWN_MERGE_VARIABLE, with the tags in variables) instead of being sent as literal braces. POST /templates/validate reports it earlier, as a warning with blocksScheduling: true, and its preview now uses the same renderer as the sender.
  • Test send. POST /campaigns/{id}/test-send sends the campaign to the account owner's verified address only, marked [TEST], with no tracking and no effect on statistics or webhooks. Limited per campaign and per account (429 TEST_SEND_LIMIT).
  • Reply-To, and a better From name. Campaigns take an optional reply_to. When from_name is empty, recipients now see the workspace name instead of the internal campaign name.
  • Templates are validated on save. PATCH /templates/{id} checks the merged result (422 TEMPLATE_INVALID), and a template's type cannot change (400 TYPE_IMMUTABLE). Template responses include updated_at. Prose that merely mentions onclick or javascript: no longer raises a false warning.
  • Also documented: POST /recipients/bulk-permanent-delete.

Documentation changed

Communications: webhooks, your own unsubscribe landing page, and a required unsubscribe link

  • Workspace webhooks. POST /workspaces/{id}/webhooks registers an https URL for campaign.completed, message.delivered, message.bounced, message.complained, contact.unsubscribed and contact.consent_given. Each delivery is signed (X-Motorical-Signature, HMAC-SHA256 of the raw body), retried when it fails, and the webhook is switched off after repeated failures. The signing secret is shown once, when you create the webhook. Opens and clicks are not events. Payloads carry the recipient's email address in plain text.
  • Your own page after unsubscribing. PATCH /settings/unsubscribe sets an optional landing page. Recipients who confirm an unsubscribe are sent there instead of seeing the Motorical page. The URL must be https and on a domain you have verified (LANDING_URL_INVALID, LANDING_DOMAIN_NOT_VERIFIED). One-click unsubscribes from a mail client are unaffected, and the List-Unsubscribe header still points at Motorical.
  • Scheduling needs an unsubscribe link. POST /campaigns/{id}/schedule now answers 400 UNSUBSCRIBE_LINK_MISSING when neither the HTML nor the text of the template contains {{unsubscribe_url}}. Campaigns already scheduled are not affected.
  • Removed: the old inbound POST /api/webhooks/motorical route, which never accepted a request.

Documentation changed

Communications API: campaign rules, duplicate, safer unsubscribe

  • Duplicate a campaign. POST /campaigns/{id}/duplicate copies a campaign of any status into a new draft with the same template, lists, Motor Block, From address and pacing. Completed and cancelled campaigns are final, so this is how you send one again.
  • Status machine. draft, scheduled, sending, completed, cancelled. Completed and cancelled cannot be edited, rescheduled or restarted (409 INVALID_STATE). What a draft, scheduled or sending campaign may still change is listed per status. There is no paused state.
  • Scheduling checks everything, and compiles. POST /campaigns/{id}/schedule re-checks the Motor Block, template, lists and From address, sanitises and compiles the HTML, freezes the audience, and refuses an empty audience (EMPTY_AUDIENCE) or a past time (SCHEDULED_AT_IN_PAST). A separate compile call is optional now.
  • The From address must be on the Motor Block's own domain (FROM_DOMAIN_MISMATCH), when you create the campaign, when you schedule it, and again when it is sent.
  • Templates, lists and Motor Blocks must belong to your workspace; another workspace's id is a 404. Malformed ids are 400 INVALID_ID.
  • Retry-safe creates. POST /campaigns, /schedule and /duplicate accept an Idempotency-Key; a retry replays the first answer instead of creating a second campaign.
  • One report. /campaigns/{id}/report is new, and /stats, /analytics and the overview read the same per-recipient numbers, so they agree. /stats now returns unsubscribed. /events accepts redact=true.
  • Unsubscribe links are safe to scan and no longer expire. Opening the link shows a confirmation page; only the button (or the mail client's one-click) unsubscribes, so link scanners cannot unsubscribe people. Every path records the same data, with a source of one_click, link, manual or api. The List-Unsubscribe header offers the https link only.
  • Removing a spam-complaint suppression needs acknowledge_complaint=true (409 COMPLAINT_ACKNOWLEDGEMENT_REQUIRED without it). Suppressions are account-wide.
  • GDPR export is POST /gdpr/export. It emails the export, so GET is deprecated.
  • Corrections to these pages: the paused state and the "Smart Scheduling" features never existed and are removed; suppressions are shared across the account, not isolated per workspace; and the request examples now include the Authorization header they always needed.

Documentation changed

Reputation scores count the bounces your sending can influence (rolling out)

  • Every bounce still shows as bounced. Logs, totals and message outcomes are unchanged. What changes is the counted figure that feeds a score.
  • Counted: an address or domain that does not exist, policy blocks (reputation, content, authentication) and anything that cannot be classified. Not counted: a full recipient mailbox, a network failure, and blocks on Motorical's own sending network.
  • New response fields on GET /motor-blocks/{id}/reputation (and the overview's reputation): totals.bouncedCounted, totals.bouncedExcluded, and lowVolume with a note. They appear where the rule is active for your account; nothing is removed or renamed.
  • Small Motor Blocks. With fewer than 50 sends in the window, bounces are not scored yet (lowVolume: true); complaints and failures still are.
  • Dashboard. The Health chip keeps the raw bounce rate; its tooltip gains a line saying how many bounces counted and why.
  • Rolling out. Active per account as the rollout reaches it. See which bounces count.

Documentation changed

MCP: onboarding state needs read:domains

  • Fixed. motorical_get_onboarding_state was listed on the analytics server under read:analytics, but the API route behind it needs a different scope (config.read) that read:analytics does not carry. A connection holding only read:analytics saw the tool and got 403 missing_scope.
  • Now. The tool needs read:domains (which carries config.read) and is listed on the domains server and main. A connection without a domains read no longer sees it, instead of seeing it and being refused. Nothing that worked before is lost: the tool never worked for the connections affected.
  • Why not every connection. Unlike motorical_whoami, it reports domain verification, DNS readiness and Motor Block state, which an agent that only sends or only reads analytics has no reason to enumerate.
  • A check keeps scopes honest. The documentation build now compares every MCP tool's scope with the scope its API route requires; these two tools were the only mismatches.
  • Packages. @motorical/mcp 1.22.0 and @motorical/scope-catalog 0.7.0 are on npm; the hosted servers already run the change.

Documentation changed