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.

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 MailCheap sets up in a few minutes. List cleanup is on unless cleanup.enabled is false. Add a postal address before sending.

Changes a newsletter's settings. Send only the fields to change; nested groups (welcome, confirmation, cleanup, author) keep the fields you leave out.

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

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 or scheduled campaign: it leaves every list and a scheduled send never goes out. Sent campaigns can't be deleted.

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. On MailCheap Cloud, during an account's first 30 days of sending, campaigns go out over hours, the first over 24 hours, the next two over 16 and 12, then each over 8 (sendingUntil). 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. On MailCheap Cloud, during an account's first 30 days of sending, campaigns go out over hours, the first over 24 hours, the next two over 16 and 12, then each over 8 (sendingUntil). 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.

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, 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 keep coming in over the plan's limits. A misspelled domain (gmial.com) answers validation_failed with the address it was likely meant to be; spam trap addresses and domains that can't receive email answer validation_failed too.

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.

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, 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 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. On PostShiba, a check within a minute of the last one answers what that one found. Once its archive subdomain points at MailCheap, the newsletter sending from the domain moves its archive and links there.

Removes a domain from the email provider and its archive subdomain from MailCheap. 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.

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 MailCheap's 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 MailCheap 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.

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

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 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.