Mailcheer

Sends a single (transactional) email to one or more addresses. The sender must belong to a verified domain of the workspace — call get_account to see which ones. A suppressed address fails the entire call, with its reason. The email is sent immediately: this action cannot be undone.

{
  "type": "object",
  "properties": {
    "from": {
      "type": "string",
      "description": "Sending address on a verified domain. \"Name <[email protected]>\" format accepted."
    },
    "to": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "maxItems": 50
        }
      ],
      "description": "Recipient, or list of recipients."
    },
    "subject": {
      "type": "string",
      "description": "Message subject."
    },
    "html": {
      "type": "string",
      "description": "HTML body."
    },
    "text": {
      "type": "string",
      "description": "Plain-text body. At least one of html or text is required."
    },
    "replyTo": {
      "type": "string",
      "description": "Reply-to address."
    }
  },
  "required": [
    "from",
    "to",
    "subject"
  ]
}

Returns the workspace this key grants access to, its scopes, plan, remaining emails this month, sending domains (verified or not) and registered senders. Call this FIRST: it tells you which address to send from before attempting anything.

{
  "type": "object",
  "properties": {}
}

Lists the workspace's subscribers, page by page. Use `cursor` with the `next_cursor` value from the response to get the next page. `status` filters on subscribed, pending, unsubscribed, bounced, or complained.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "1 to 100, 50 by default."
    },
    "cursor": {
      "type": "string",
      "description": "Next-page cursor."
    },
    "status": {
      "type": "string"
    },
    "q": {
      "type": "string",
      "description": "Search by address or name."
    }
  }
}

Adds or updates a subscriber. By default the person enters as PENDING and receives a confirmation email: that is double opt-in, and it protects the workspace's sending reputation. `double_opt_in: false` subscribes directly and must only be used when consent was already collected elsewhere — never on your own initiative. A suppressed or unsubscribed address is refused.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "double_opt_in": {
      "type": "boolean",
      "description": "false = direct subscription without confirmation. Only request this on explicit instruction from the person."
    }
  },
  "required": [
    "email"
  ]
}

Unsubscribes an address and adds it to the workspace's suppression list. The record is not deleted — that is what prevents the address from coming back on the next file import. This action cannot be reversed via the API: only the person can re-subscribe.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    }
  },
  "required": [
    "email"
  ]
}

Addresses that will receive nothing more: unsubscribed, bounced, or complained. The `scope` field tells whether the address is suppressed for this workspace only or for the entire platform. No tool removes an address from this list: that action is done manually in the Mailcheer workspace, because it is the one that can suspend a sending capability.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    },
    "cursor": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "description": "Look up a specific address."
    }
  }
}

Adds an address to the workspace's suppression list: it will receive nothing further, neither campaigns nor transactional emails. Use when someone requests no further contact outside the unsubscribe link.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string"
    },
    "reason": {
      "type": "string",
      "enum": [
        "unsubscribe",
        "bounce",
        "complaint",
        "manual"
      ]
    }
  },
  "required": [
    "email"
  ]
}

The workspace's campaigns, from newest to oldest, with their status: draft, scheduled, sending, or sent.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number"
    },
    "cursor": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  }
}

Creates a DRAFT. Nothing is sent: you then need to call send_campaign, or send it from the Mailcheer workspace. Content is written in plain text in `text` — a blank line separates paragraphs, "#" at the start of a line makes a heading. Always have the draft reviewed before sending.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Internal name, visible only in the workspace."
    },
    "subject": {
      "type": "string",
      "description": "Subject line seen by recipients."
    },
    "text": {
      "type": "string",
      "description": "Plain-text content."
    },
    "preheader": {
      "type": "string",
      "description": "Preview text shown after the subject in the inbox."
    },
    "from": {
      "type": "string",
      "description": "Address of an already-registered sender. Defaults to the workspace sender."
    },
    "kind": {
      "type": "string",
      "description": "newsletter, offer, announcement… newsletter by default."
    }
  },
  "required": [
    "name"
  ]
}

Read-only: nothing is sent. Returns exactly what send_campaign would do right now — would it go out (and if not, why), and how many people would receive it. With `to`, reports address by address who is kept and who is excluded, with the reason (unsubscribed, bounced, complained, not in the list…). Call it BEFORE send_campaign, and give that number to the person when you ask them to confirm.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Campaign identifier."
    },
    "to": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional. The addresses to restrict the send to. Omitted = the campaign's whole audience."
    }
  },
  "required": [
    "id"
  ]
}

⚠️ IRREVERSIBLE. Locks the recipient list and triggers sending to ALL active subscribers in the workspace — or, with `to`, only to the requested addresses that are active subscribers (never an unsubscribed or suppressed address). A sent email cannot be recalled. First call preview_campaign_send with the same parameters, then ask the person for explicit confirmation, telling them how many people will receive the message. Messages go out progressively; get_campaign_stats tracks progress.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Campaign identifier."
    },
    "to": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional. Restricts the send to these addresses. An empty list sends to nobody (refused); for the whole list, omit the field."
    }
  },
  "required": [
    "id"
  ]
}

Status and figures for a campaign: recipients, sent, delivered, opened, clicked, bounced, complained. Rates are calculated on delivered messages, not on recipients. Every rate comes twice: open_rate and click_rate include bots (security gateways, preloads), human_open_rate and human_click_rate set them aside — that is the figure to give the person when they ask how many read it.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

Status of an email sent via send_email: sent, delivered, bounced, or complained. Amazon's delivery callback arrives a few seconds to a few minutes after sending — a "sent" status right after the call is normal.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}