canonical: https://jentic.com/apis/mailcheer.com/mailcheer

# Mailcheer API

The Mailcheer API sends transactional emails from your application and runs your subscriber lists and email campaigns from code. A single send call delivers one message from a verified domain, with fields such as reply_to, tags, attachments, track_opens, and unsubscribe_url, and returns 202 once the message is accepted. Subscribers can be upserted one at a time or up to 500 per batch, tagged, unsubscribed, or erased for GDPR, while campaigns move from draft through an optional dry_run to a real send with full statistics. Suppressions, address verification, a tracking domain, and webhook subscriptions with a replayable delivery log complete the surface, and a test key that starts with mch_test_ simulates sends without delivering anything.

## For AI agents

Send transactional email and run subscriber lists and campaigns with Mailcheer: send from a verified domain, upsert and tag subscribers, draft and send campaigns, manage suppressions, and replay webhook deliveries.

## Scope

Does not send SMS, push notifications, or run a CRM. Use for transactional email, subscriber lists, and email campaigns only.

## Capabilities

- Send a transactional email from a verified domain with reply_to, tags, attachments, and open or click tracking
- Check delivery status of a sent email and verify addresses before writing to them
- Upsert subscribers individually or up to 500 per batch, then add or remove tags
- Draft a campaign, preview its audience, and start the send with an optional dry_run
- Read campaign statistics and per-recipient status after a send
- Suppress addresses, unsubscribe a subscriber, or erase a person for GDPR
- Subscribe a webhook to events, send a test event, and replay a past delivery

## Use cases

### AI agent sending transactional email through Jentic

An app's support agent needs to email a customer a receipt without the developer writing a mail client. Through Jentic it searches for 'send an email', loads the Mailcheer send operation, first reads GET `/api/v1/me` to find a verified domain and sender, then posts from, to, subject, and html. The API key is injected at call time and the 202 response confirms acceptance.

Example prompt: Call GET `/api/v1/me` to read verified domains, then POST `/api/v1/emails` with from 'Billing <billing@yourdomain.com>', to 'customer@example.com', subject 'Your September invoice', and html, then GET `/api/v1/emails/{id}` for status

### Newsletter campaign from draft to send

A small team writes a monthly newsletter and wants it sent to tagged subscribers. Mailcheer creates the campaign as a draft with name, subject, preheader, and content, previews the audience a target would reach without creating a campaign, and starts the send, optionally as a dry_run first. Afterwards the full report and per-recipient status show what happened.

Example prompt: Call POST `/api/v1/campaigns` with name and subject, POST `/api/v1/audience` with the target tag to preview recipients, then POST `/api/v1/campaigns/{id}/send` with dry_run true before the real send

### Subscriber sync from a signup form

New signups land in an app database and need to reach the mailing list. Mailcheer upserts a subscriber by email with firstName, lastName, tags, custom fields, and double_opt_in, or up to 500 subscribers in one batch call. Tags can be added or removed per person or across many subscribers at once.

Example prompt: Call POST `/api/v1/subscribers/batch` with a subscribers array of new signups, then POST `/api/v1/tags/{tag}/subscribers` to tag them as 'trial'

### Compliance and list hygiene

Sending reputation depends on not mailing people who bounced, complained, or opted out. Mailcheer keeps a suppression list that refuses sends to listed addresses, verifies addresses before writing to them, and erases a person on a GDPR request. A bounce or complaint rate that is too high suspends sending, so hygiene matters before a campaign.

Example prompt: Call POST `/api/v1/verify` with an emails array, then POST `/api/v1/suppression` for each invalid address with a reason

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/emails` | Send an email |
| GET | `/api/v1/emails/{id}` | Get the status of an email |
| GET | `/api/v1/me` | Read key permissions, quota, and verified domains |
| POST | `/api/v1/subscribers/batch` | Upsert up to 500 subscribers |
| POST | `/api/v1/campaigns` | Create a campaign draft |
| POST | `/api/v1/campaigns/{id}/send` | Start a campaign send |
| GET | `/api/v1/campaigns/{id}/stats` | Get the full campaign report |
| POST | `/api/v1/suppression` | Suppress an address |

## Key resources

- **Emails** — Transactional messages sent with POST `/api/v1/emails` and tracked by id
- **Subscribers and tags** — List members addressed by email, with tags, custom fields, unsubscribe, and GDPR erase
- **Campaigns** — Drafts, sends with dry_run, statistics, and per-recipient status
- **Suppression list** — Addresses refused for sending, with their reason
- **Webhooks** — Event subscriptions with a delivery log, test events, and replay

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 62 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 48 / 100
  - Developer Experience & Jentic Compatibility: 65 / 100
  - AI-Readiness & Agent Experience: 56 / 100
  - Agent Usability: 94 / 100
  - Security: 55 / 100
  - AI Discoverability: 73 / 100
- **View full report:** https://jentic.com/apis/mailcheer.com/mailcheer/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Mailcheer by hand means choosing between bearer and X-Api-Key auth, reading verified domains before the first send, and honouring Retry-After on 429 and 423 responses. Through Jentic you install once, import Mailcheer from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Mailcheer puts the subscriber email, campaign id, and webhook id in the URL path, such as `/api/v1/campaigns/{id}/send`, so a rule can pin your agent to one campaign or one subscriber and the operations you pick. You choose the operations it may call, so ones like starting a campaign send, erasing a person, or deleting a tag are not included unless you add them.
- **Credential handling:** Your Mailcheer API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a transactional email' or 'add a subscriber', and Jentic returns the matching Mailcheer operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Resend** — Developer transactional email API that Mailcheer's send endpoint is modeled on
- **Mailchimp** — Email marketing platform with audiences and campaigns
- **Brevo** — Email, SMS, and marketing automation platform
- **HubSpot CRM Contacts** — CRM contact records that can feed a mailing list

## FAQ

### What authentication does the Mailcheer API use?

Mailcheer declares a workspace API key sent either as a bearer token in the Authorization header or in the X-Api-Key header, per its OpenAPI spec; the two are equivalent, so send one, not both. Keys start with mch_live_ or mch_test_ and carry scopes such as emails:send. GET `/api/v1`, the API map, needs no key. Through Jentic the key is stored by your own instance and attached at call time.

### What are the rate limits for the Mailcheer API?

The Mailcheer OpenAPI spec states 600 requests per minute per key, with a 429 response beyond that and a Retry-After header in seconds. Monthly plan quota is reported on authenticated responses through the Mailcheer-Quota-Remaining and related headers.

### Is there a Mailcheer MCP server?

Yes. Mailcheer offers an official MCP server that calls this same API. You can also connect Mailcheer directly through Jentic: your agent gets the full 37-endpoint surface without loading another server's tool definitions into its context, your key is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### Can I test Mailcheer sends without emailing anyone?

Yes. A key that starts with mch_test_ checks every send like a live one, including verified from address and suppression list, and returns the same response, but nothing goes out and the quota is not touched. Simulated events still reach your webhooks marked as test.

### How do I send an email through Jentic?

Search Jentic for 'send a transactional email', load the POST `/api/v1/emails` operation, and run it with from, to, subject, and html or text; from must be on a domain verified in the workspace, which GET `/api/v1/me` lists. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Mailcheer API?

Yes. For example, a rule that allows POST `/api/v1/subscribers` and POST `/api/v1/subscribers/{email}/tags` lets the agent add and tag signups while it cannot send a campaign, erase a subscriber, or delete a webhook. Jentic logs each call the agent makes, and Mailcheer key scopes add a second limit.