API reference

The dashboard's overview for one newsletter: subscribers each day of the last 30 days, email results of the last 30 days against the 30 before, emails sent per hour today and yesterday, and the plan's usage this month, which the account's newsletters share.

Reports account-owned email performance, audience, campaigns, inbox providers, recorded links and operational inventory. Dates are inclusive UTC calendar days with an equal previous-period comparison. Email outcomes belong to their send cohort, as observed now; audience and inventory are current snapshots. Test emails are excluded by default.

Lists the account's newsletters, 3 at most, first created first, with their settings and active contacts. Actions that take a newsletter use the first one when it's left out.

Gets a newsletter's settings: sender, postal address, welcome and confirmation emails, list cleanup and archive.

Creates a newsletter. An account has up to 3, sharing its plan's emails and subscribers; one more answers conflict. Without a fromEmail it sends from the shared address hello@<slug>.<shared domain>, which XMails sets up in a few minutes. List cleanup is on unless cleanup.enabled is false. Without a postalAddress, its emails print the server's default if it has one: XMails’ address on XMails Cloud.

Changes a newsletter's settings. Send only the fields to change; nested groups (welcome, confirmation, cleanup, author) keep the fields you leave out. An account changes slugs 3 times a day at most: one more answers rate_limited.

Says whether a newsletter can take a slug: available, or taken by another newsletter, reserved by XMails or invalid, with the message saving it would answer. Checking doesn't count toward the 3 slug changes a day.

Sends the saved welcome email to the account owner's address, switched on or not. It counts toward the plan's emails.

Returns an account-owned product or service, including archived items, with its editable catalog details.

Permanently deletes an account-owned product or service. Existing template snapshots, campaign drafts and image library assets are preserved. This cannot be undone.

Lists this account's products and services, newest first. Archived items are hidden unless requested. Pass nextCursor back as cursor for the next page.

Adds a product or service to this account's catalog. Its facts, price, links and pictures can be reused in newsletter templates.

Updates an account-owned catalog item or archives it. Templates keep a snapshot so changing an item never rewrites an existing template or campaign.

Permanently deletes an account-owned template. An active generation worker must finish or its lease expire first. Queued work skips deleted templates. Existing campaigns, guide revisions and image library assets are preserved. This cannot be undone.

Returns this account's current Markdown generation guide and its last ten revisions. Recommendations reflect human feedback, not a measured quality score.

Saves one review of a ready AI template and rebuilds the account's versioned Markdown guide from its latest twenty reviews. Repeat the same review to recover an interrupted guide update. Existing templates stay unchanged; recommendations guide future generations.

Creates a new AI template using the current account guide after reviewing a ready template. Keeps the original, links the new version to its parent, and snapshots the guide for reproducible retries. Uses the original brief and current catalog facts; nothing is sent.

Creates an editable drag-and-drop email design with validated blocks and brand settings. Requires no catalog or AI service. HTML is generated on the server; nothing is sent.

Lists this account's reusable templates and AI generation progress, newest first. A ready template can become a campaign draft using create_campaign.

Returns an account-owned template, its editable email content, catalog snapshot and generation status. Poll this action while AI generation runs.

Queues an AI template using account-owned catalog items and a brief. Gemini writes editable copy; optional Nano Banana artwork is stored in the account's image library. Returns immediately; poll get_template. Nothing is sent.

Retries a failed AI template or a worker whose six-minute lease expired. Reuses completed copy and artwork stages rather than regenerating them. Nothing is sent.

Saves a ready template's name, subject, preview text or content. DIY templates use structured design blocks and server-rendered HTML; other templates use sanitized rich content. Existing campaign drafts are independent.

Lists campaigns, newest activity first: sent issues by send date, scheduled ones by send time, drafts by last edit. Content is left out; get_campaign has it.

Gets a campaign with its content, stats and, for drafts, what would block sending it now.

Delivery, open, click, bounce, complaint and unsubscribe rates of a sent campaign, its list cleanup emails, results by inbox provider, and how many contacts a capped send hasn't reached yet.

Creates a draft. Nothing is sent: review it in the dashboard or with get_campaign, then send_test_email, schedule_campaign or send_campaign.

Changes a draft or scheduled campaign's subject, preview text or content. Send only the fields to change; format goes with content. Sent campaigns can't change.

Deletes a draft, scheduled, paused or sent campaign from lists and the public archive. Pause actively sending campaigns first. Delivery records remain for analytics, billing and suppression; sent emails cannot be recalled.

Copies a campaign's subject, preview text and content into a new draft.

Sends the campaign as saved to the account owner's address, subject prefixed with [Test]. Nobody else gets it. It counts toward the plan's emails.

Schedules a draft to send by itself at a time within a year. It goes out without asking again, unless unschedule_campaign runs first. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. Plan limits and pre-send checks run now and again when it goes out. XMails Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked.

Turns a scheduled campaign back into a draft, so it doesn't go out.

Sends a draft or scheduled campaign now to the newsletter's active contacts, most engaged first. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. A campaign that is already sending or sent answers conflict, so a retry never sends twice. Plan limits, the from address, the postal address and the email size are checked first. XMails Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked.

Sends a sent campaign to contacts who haven't received it yet, the next most engaged first: a send in steps. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. Each call starts a new step, so check get_campaign_report before calling it again; while a step is still sending it answers conflict. XMails Cloud paces a send by the volume its account has proven: its largest campaign of the last 60 days whose bounces and complaints stayed under the pause level, counted a day after it went out. A send, with what the account's other sends still have to send or sent in the last 24 hours, goes at full speed up to 200 emails, or that volume times 2 on the first day of the account's 30-day warm-up, rising to 5 by its last day and after it. A bigger send goes out over 4 hours plus 4 for each time it doubles that, 72 at most (spreadHours, sendingUntil); a resume keeps the pace, each step of send_campaign_to_more gets its own. Contacts never mailed before go in steps: a slice first, the rest 3 hours after it if the slice's bounces and complaints stay under the pause level. Past 2.00% hard bounces (at least 5) or 0.08% complaints (at least 2), the campaign pauses with pauseCode high_rates, or first_send_slice for a slice, and resume_campaign sends the rest. Past 5.00% (at least 10) or 0.30% (at least 3), the account is blocked.

Stops a campaign that is sending. Emails already sent stay sent; the rest wait until resume_campaign.

Sends the rest of a paused campaign. Sending can't be undone: emails can't be recalled once they go out. Ask the user to confirm first. The plan limits and the account's state are checked again first. Resumed after a high_rates or first_send_slice pause, only the block level stops it again.

Changes the path of a campaign's archive page (/p/<slug>), or pins a sent issue to the top of the archive. Works on sent campaigns too.

Counts what the newsletter's list cleanup would do if the campaign went out now: issues sent, last-chance emails instead, contacts still waiting to answer one, and contacts made dormant. Reads the whole list, so it can take a few seconds.

Lists contacts, newest signups first, 50 a page. Filter by newsletter, contact group, status or the start of the email address; pass nextCursor back as cursor for the next page. counts has every status for the same filters.

Gets one contact by ID or email address, with its status, dates and engagement.

Signs someone up, like the archive's form: they get the welcome email, or the confirmation email when the newsletter asks new subscribers to confirm. Signing up again keeps the contact as it is unless resubscribe is true. Works with signups only keys, for website forms. Signups and confirmation emails keep coming in over the plan's limits; welcome emails count toward the month's emails and are skipped once they're used up, never sent later (get_billing's usage.welcomeEmailsPaused). A misspelled domain (gmial.com) answers validation_failed with the address it was likely meant to be; spam trap addresses, domains that can't receive email, and addresses XMails knows can't receive email (they hard bounced or hit a spam trap, from any sender on XMails) answer validation_failed too.

Updates an account-owned contact's name, source and private notes. Email identifies the subscription and remains unchanged, as do consent, engagement, group membership and suppression status. No email is sent.

unsubscribed stops all emails to the contact, for good: only the person signing up again brings them back. active brings back a dormant contact; unsubscribes, bounces and complaints are final.

Deletes a contact from its newsletter, with its dates and engagement. It can't be undone. For a contact who unsubscribed, bounced or complained, XMails keeps a hash of the address so the newsletter never emails it again: import_contacts leaves it out, and add_contact or a signup form adds it back with that status. Any other contact can be added again like a new one.

Adds up to 1000 contacts per call, with the same checks as the dashboard's CSV import: invalid, misspelled (gmial.com…), spam trap, role (info@, support@…), throwaway, duplicate and suppressed addresses, undeliverable ones (XMails knows they can't receive email: they hard bounced or hit a spam trap, from any sender on XMails), and addresses on domains that can't receive email, are left out and counted. consent must be true: "These people agreed to receive my emails". Existing contacts keep their status unless a row gives a stricter one (unsubscribed, bounced, complained), which is final. No welcome emails go out. For more rows, send the next chunk with the importId of the first.

Makes a CSV download link for the contacts matching the filters, valid for an hour, no API key needed to open it. The columns go back in through the import as they are.

Lists this newsletter's groups and counts. Ensures its automatic Everyone group exists; Everyone includes new contacts automatically, regardless of subscription status.

Creates a custom group inside an owned newsletter. Everyone is reserved. Contacts may belong to multiple custom groups; group membership never changes subscription or suppression status.

Renames an owned custom group. Everyone cannot be renamed.

Deletes a custom group and its memberships. Contacts and their subscription/suppression states are kept. Everyone cannot be deleted.

Adds or removes up to 200 contact IDs in an owned custom group. Every contact must belong to its newsletter and account. Everyone is automatic; membership never resubscribes anyone.

Lists the account's own sending domains with their DNS records and status as last checked, and each newsletter's shared address (hello@<slug>.<shared domain>), which works with no setup.

Adds a domain to send from, in the account's own tenant at the email provider: emails are signed with DKIM and bounces return to a subdomain of it (rp.<domain> on PostShiba, bounce.<domain> on Amazon SES). The answer lists the DNS records to add; check_domain reads them once they're in. Newsletters can send from it once it's verified.

Asks the email provider and DNS again whether the domain's records are in, and looks up its DMARC record or its parent domain's. On PostShiba, a check within a minute of the last one answers what that one found. When its setup lists an archive step, the newsletter sending from the domain moves its archive and links to that subdomain once it points at XMails.

Removes a domain from the email provider, and its archive subdomain from XMails when its setup lists one. Newsletters on it can't send until they move to another address. Refused while a campaign from it is sending, paused or scheduled. Adding it again needs new DNS records.

Starts Cloudflare sign-in for an account-owned sending domain, with PKCE and a ten-minute single-use state. The browser connect endpoint sets the matching secure cookie. Authorizing grants setup permission to add only missing email-provider DNS records after provisioning SES.

Completes Cloudflare authorization using its code and the browser's matching state cookie. Discovers the authorized zone, encrypts access and refresh tokens per account and domain, provisions missing email-provider setup, adds nonconflicting DNS records, and checks verification. Never returns credentials. A connected domain may still need DNS conflict resolution or administrator attention.

Returns the account-owned domain's Cloudflare connection status. API tokens and encrypted credentials are never returned.

Connects an owned sending domain to an active Cloudflare zone using a zone-scoped token with Zone Read and DNS Edit. Validates zone ownership and read access, encrypts the token per account and domain, and makes no DNS changes. Never returns the token.

Reads Cloudflare DNS and previews missing SES or PostShiba authentication and optional archive records. Preserves valid existing or inherited DMARC policies, reports conflicts, and makes no DNS changes.

Rechecks and adds only missing provider-generated DNS records to the connected zone, with CNAME proxying disabled. Refuses conflicting plans, never updates or deletes existing records, serializes simultaneous applies, and checks provider verification afterward. Retry safely after partial failure; DNS propagation may take time.

Removes the saved encrypted Cloudflare token for this account-owned domain. Existing DNS records are left in place and the token can be revoked in Cloudflare. Wait for active DNS setup to finish first.

Lists the images uploaded to the account, newest first, 50 a page, so a campaign can use one again without uploading it twice. Pass nextCursor back as cursor for the next page.

Stores a PNG, JPEG, GIF or WebP image under 4 MB on XMails’ CDN and returns its URL for campaign content. Send the file as base64 (under about 3 MB, since requests stop at 4.5 MB) or an https:// link XMails downloads. The URL never changes: sent emails keep pointing at it. list_images finds images uploaded before.

Lists the account's API keys, revoked ones included, with their level and when they were last used. Keys themselves are never shown again.

Creates an API key and returns it once; only its hash is stored. full can do everything a full key can, including creating more keys; signups can only add contacts, for keys that end up in website code. An account has up to 20 active keys: one more answers conflict until one is revoked.

Revokes an API key for good: requests with it answer unauthorized from now on. A key can revoke itself.

Returns this account's Gemini models and reference-image settings, plus the shared server connection status. The server API key is never returned.

Saves account-scoped model and visual preferences. All generation uses the shared server Gemini key; customers cannot supply keys. Changes apply to new templates; queued templates retain their models and visual brief. No provider request is made.

Lists the apps connected to the account with OAuth, such as ChatGPT, Claude and Grok Bot, with when they were connected and last used. Each one has full access, like a full access API key.

Disconnects an app connected with OAuth: its tokens stop working at once, and it has to ask for access again to come back. An app can disconnect itself.

The account's plan, subscription status and this month's usage against the plan's limits, with every plan on sale for comparison. Works without an active plan. A self-hosted server has no billing and answers billing_off.

Returns a Stripe page where the account owner picks up the change: Checkout without a paid plan (on a free plan too: the paid plan takes over), the Customer Portal's confirmation page with one. Nothing changes until they confirm there. Give the URL to the user. A self-hosted server has no billing and answers billing_off.

Returns a Stripe Customer Portal link for the account owner: payment method, invoices, plan changes and cancellation. A self-hosted server has no billing and answers billing_off.