Emails

Send an email

Permission required: emails:send.

Answers 202: Amazon has accepted the message, it is not delivered yet. Delivery is confirmed a few seconds later with GET /api/v1/emails/{id}.

Use the Idempotency-Key header: replaying a successful call returns the same response without a second send, for 24 hours. A refusal is not kept: once its cause is lifted, the same call with the same key goes out.

An address that unsubscribed from the workspace receives an individual email; with unsubscribe_url, the send is a newsletter or prospecting and is refused to it (422 suppressed_recipient). A bounce, a complaint or a manual suppression refuses both.

With a test key (mch_test_…), the same checks and the same response — but nothing goes out and the quota is not touched; events are simulated. See Test mode.

post/api/v1/emails

Request

  • Base URL: https://mailcheer.com
  • URL: https://mailcheer.com/api/v1/emails
  • Auth: one of:
    • HTTP bearer
    • API key in header X-Api-Key

Headers

Idempotency-Keystring

A unique value per send. Replaying a successful call (2xx) returns the same response, without a second send, for 24 hours after the first call. A refusal (402, 422, 423, 429…) is not kept: once its cause is lifted, send the same call with the same key and it goes out. The same key with a different body returns 409 idempotency_key_reused; an identical call still in progress, 409 idempotency_key_in_use with Retry-After.

Request body

fromstring required

Required. An address on a domain verified in the workspace — otherwise 422 unverified_from_domain, which hands you the list of domains you can use. GET /api/v1/me gives it too, before you try. Both forms are accepted: the bare address, or “Name address@domain.com” so the name shows in the inbox.

tostring required

Required. One recipient, or an array of 1 to 50 recipients. At most 50 addresses in all, to, cc and bcc together — our sending provider's limit per message; beyond, 422 validation_error. Beyond 50, split into several calls — or go through a campaign. Each entry accepts the form “Name address@domain.com” as well as the bare address, and is 3 to 320 characters long.

⚠️ Recipients see one another: they go out in the same message, not as blind copies. For each to receive their own, make one call per person.

subjectstring required

Required. The message's subject. The 998-character ceiling is the email standard's; in practice an inbox shows 40 to 60.

htmlstring

The body in HTML. html or text: at least one of the two, both if you can — a message with no text version is marked down by filters.

textstring

The body in plain text, for clients that do not display HTML.

ccstring

Visible copy. One address or an array of 1 to 50. Recipients in copy see and are seen. They count against the quota and go through the same checks as to — suppression list included.

bccstring

Blind copy. One address or an array of 1 to 50. It appears in no header of the received message, including when the send carries attachments — it stays in the envelope. Same quota and same checks as to.

replyTostring

The address recipients will reply to, when it differs from from. One, or an array of 1 to 10. Same form as to: the bare address or “Name <address>”.

reply_tostring

Alias of replyTo, for clients coming from Resend. The address recipients will reply to, when it differs from from. One, or an array of 1 to 10. Same form as to: the bare address or “Name <address>”.

Fill in only one of the two.

headersobject

Free-form headers, as name → value pairs. The ones that carry the message's identity (From, To, Reply-To, List-Unsubscribe…) are ignored: they are ours to answer for.

tagsobject

Free-form tags for your own tracking; they come back in delivery notifications and on GET /api/v1/emails/{id}. Two ways to write them: an object of key → value, or an array of {name, value} as with Resend (10 entries at most in that second form).

Names and values are rewritten, not refused: any character outside A-Z a-z 0-9 _ - becomes _, and beyond 256 characters the value is cut. An accent or a space therefore passes without error, but not unchanged.

unsubscribe_urlstring uri

The one-click unsubscribe address. Mailcheer then sets List-Unsubscribe AND List-Unsubscribe-Post — the two always go together, and without the second Gmail shows no button. Gmail and Yahoo have expected this header since February 2024 on any send to people who did not write to you first; without it, the only way out you offer is the Spam button, and it is your sending domain's reputation that pays. Must be https. The header itself is still rejected inside headers: Mailcheer writes it, you only provide the target. It also says what kind of send this is: with it, a newsletter or prospecting, refused to an address that unsubscribed; without it, an individual email, which an unsubscribe does not stop.

track_opensboolean

Insert an open-tracking pixel (HTML body only). Omitted, your workspace's “Track opens” setting decides (the Workspace screen of the app); sent, it overrides that setting for this email. In France, the CNIL's recommendation of 14 April 2026 makes measuring opens with a pixel, to track campaign performance, subject to the recipient's prior consent.

track_clicksboolean

Track clicks: the http(s) links of the <a> tags of the HTML go through your tracking domain. Left untouched: mailto:, tel:, anchors, unsubscribe_url and links carrying data-no-track. Without this field, the workspace's “Track clicks” setting decides — on by default, for every email, individual ones included. false leaves a message untouched. Login, verification and reset links (recognized by their address or a token) always stay untouched.

verifyboolean

Verify recipients before sending (same checks as POST /api/v1/verify). An invalid recipient refuses the entire call with 422 undeliverable_recipient; risky and unknown addresses go out. Default false.

Example request

{
  "from": "Your brand <hello@yourdomain.com>",
  "to": "customer@example.com",
  "subject": "Your September invoice",
  "html": "<p>Here it is, attached to this message.</p>",
  "text": "Here it is, attached to this message.",
  "cc": "accounting@example.com",
  "bcc": "archive@example.com",
  "replyTo": "support@yourdomain.com",
  "reply_to": "support@yourdomain.com",
  "headers": {
    "X-Entity-Ref-ID": "order-4192"
  },
  "tags": {
    "type": "order"
  },
  "unsubscribe_url": "https://yourdomain.com/unsubscribe/abc123",
  "attachments": [
    {
      "filename": "quote-2026-09.pdf",
      "content": "JVBERi0xLjQKJcfsj6IK…",
      "content_type": "application/pdf"
    }
  ]
}

Response

Accepted by our sending provider.

idstring

The identifier to pass back to GET /api/v1/emails/{id} to learn about delivery.

object'email'
fromstring
tostring[]

Always an array in the response, even if you passed a single address.

subjectstring
created_atstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.