Mailrith Email Marketing

Official55 toolsLive

by anrawool · TypeScript

Manage Subscribers, Broadcasts, Sequences, Automations, and reporting in Mailrith.

com.mailrith/mailrith MCP Server

The com.mailrith/mailrith MCP server manages subscribers, broadcasts, sequences, automations, and reporting in Mailrith. It provides an official MCP interface that uses the stable @modelcontextprotocol/sdk package for hosted and stdio transports while preserving Mailrith’s generated operation schemas.

🛠️ Key Features

Manages subscribers, broadcasts, sequences, automations, and reporting
Uses @modelcontextprotocol/sdk for hosted and stdio transports
Preserves Mailrith-generated operation schemas
Exposes remote MCP endpoint at https://api.mailrith.com/mcp
Supports OAuth authentication via Mailrith

🚀 Use Cases

Integrate Mailrith operations into an MCP-enabled agent workflow
Connect user clients such as Claude Desktop via remote MCP
Run a local server from this repo for stdio or self-hosted HTTP use

⚡ Developer Benefits

Standard MCP integration via @modelcontextprotocol/sdk
Code-first clients can authenticate using Authorization headers
Supports workspace API key or OAuth access token for Authorization: Bearer ...

⚠️ Limitations

Remote MCP clients must authenticate through Mailrith OAuth
Code-first clients must be able to safely store credentials (workspace API key or OAuth token)

Topics

ai-agentsemail-marketingmcppythonsdktypescriptgemini-cli-extension

Captured live from the server via tools/list.

discovery_get_capabilities

Returns the current workspace context, discovery URLs, shared request conventions, supported webhook events, and public resource operations available to the authenticated bearer credential. Permission: none. API reference: https://mailrith.com/developers/api-reference.

Parameters

No parameters.

Raw schema

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

workspace_get

Returns the authenticated workspace profile and mailing context used by broadcasts, sequences, automations, forms, and magic links. Permission: workspace:read. API reference: https://mailrith.com/developers/api-reference.

Parameters

No parameters.

Raw schema

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

sender_identities_list

Returns a bounded page of enabled sender names, addresses, and provider types that can be selected for Broadcasts and Sequences. Provider credentials and configuration are never returned. Permission: workspace:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters2

limit	integer	optional	Maximum number of sender identities to return.
starting_after	string	optional	Opaque next_cursor returned by the previous sender identity page.

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum number of sender identities to return."
    },
    "starting_after": {
      "type": "string",
      "description": "Opaque next_cursor returned by the previous sender identity page."
    }
  },
  "additionalProperties": false
}

sender_identities_get

Returns one enabled sender name, address, and provider type by stable identifier. Provider credentials and configuration are never returned. Permission: workspace:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

sender_identity_id

string

required

The sender identity identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "sender_identity_id": {
      "type": "string",
      "description": "The sender identity identifier."
    }
  },
  "required": [
    "sender_identity_id"
  ],
  "additionalProperties": false
}

analytics_create_report

Runs from compact rollups. Ranges through 31 days complete inline; longer ranges are queued. Results expire after 24 hours and never exceed 100 rows. Effect: workspace-change. Retry with the same idempotency_key. Permission: analytics:read. API reference: https://mailrith.com/developers/api-reference.

Parameters2

idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/AnalyticsReportCreateRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "AnalyticsReportCreateRequest": {
      "type": "object",
      "required": [
        "from",
        "to"
      ],
      "additionalProperties": false,
      "properties": {
        "from": {
          "type": "string",
          "format": "date"
        },
        "to": {
          "type": "string",
          "format": "date"
        },
        "source_types": {
          "type": "array",
          "maxItems": 3,
          "items": {
            "type": "string",
            "enum": [
              "broadcast",
              "sequence",
              "automation"
            ]
          }
        },
        "source_ids": {
          "type": "array",
          "maxItems": 20,
          "items": {
            "type": "string"
          }
        },
        "group_by": {
          "type": "array",
          "maxItems": 2,
          "items": {
            "type": "string",
            "enum": [
              "source_type",
              "source",
              "message",
              "provider",
              "day"
            ]
          }
        },
        "compare_previous": {
          "type": "boolean",
          "default": true
        }
      }
    }
  }
}

analytics_get_report

Returns one unexpired bounded analytics report by identifier. Permission: analytics:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters3

report_id	string	required	Stable analytics report identifier.
limit	integer	optional	Maximum aggregate row count, from 1 to 50.
starting_after	string	optional	Opaque next_cursor returned by the previous report page.

Raw schema

{
  "type": "object",
  "properties": {
    "report_id": {
      "type": "string",
      "description": "Stable analytics report identifier."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Maximum aggregate row count, from 1 to 50."
    },
    "starting_after": {
      "type": "string",
      "description": "Opaque next_cursor returned by the previous report page."
    }
  },
  "required": [
    "report_id"
  ],
  "additionalProperties": false
}

subscribers_list

Returns subscribers in the authenticated workspace, sorted from newest to oldest. Permission: subscribers:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters12

search	string	optional	Filter subscribers by name, email, or status.
email	string	optional	Filter subscribers by an exact subscriber email address.
status	string	optional	Filter subscribers by subscriber status.
cold_only	boolean	optional	When `true`, return only cold subscribers.
tag_id	string	optional	Return subscribers that currently have this tag ID. Repeat `tag_id` or use `tag_ids` to match any of several tags.
tag_ids	string	optional	Comma-separated tag IDs. By default, the API returns subscribers who have any listed tag.
tag_operator	string	optional	Controls how tag filters are applied. Defaults to `has_any_of`.
sequence_id	string	optional	Return subscribers that match this sequence ID. Repeat `sequence_id` or use `sequence_ids` to match any of several sequences.
sequence_ids	string	optional	Comma-separated sequence IDs. By default, the API returns only subscribers who are active in any listed sequence.
sequence_operator	string	optional	Controls how sequence filters are applied. Defaults to `is_active_in_any_of`.
limit	integer	optional	Maximum number of subscribers to return. Defaults to 25 and is capped at 100.
starting_after	string	optional	Use the opaque cursor from the previous page to request the next page.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Filter subscribers by name, email, or status."
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Filter subscribers by an exact subscriber email address."
    },
    "status": {
      "type": "string",
      "enum": [
        "Active",
        "Unconfirmed",
        "Unsubscribed",
        "Complained",
        "Bounced",
        "Blocked"
      ],
      "description": "Filter subscribers by subscriber status."
    },
    "cold_only": {
      "type": "boolean",
      "description": "When `true`, return only cold subscribers."
    },
    "tag_id": {
      "type": "string",
      "description": "Return subscribers that currently have this tag ID. Repeat `tag_id` or use `tag_ids` to match any of several tags."
    },
    "tag_ids": {
      "type": "string",
      "description": "Comma-separated tag IDs. By default, the API returns subscribers who have any listed tag."
    },
    "tag_operator": {
      "type": "string",
      "enum": [
        "has_any_of",
        "has_none_of"
      ],
      "default": "has_any_of",
      "description": "Controls how tag filters are applied. Defaults to `has_any_of`."
    },
    "sequence_id": {
      "type": "string",
      "description": "Return subscribers that match this sequence ID. Repeat `sequence_id` or use `sequence_ids` to match any of several sequences."
    },
    "sequence_ids": {
      "type": "string",
      "description": "Comma-separated sequence IDs. By default, the API returns only subscribers who are active in any listed sequence."
    },
    "sequence_operator": {
      "type": "string",
      "enum": [
        "is_active_in_any_of",
        "is_not_active_in_any_of",
        "has_completed_any_of",
        "has_not_completed_any_of",
        "has_ever_been_in_any_of",
        "has_never_been_in_any_of"
      ],
      "default": "is_active_in_any_of",
      "description": "Controls how sequence filters are applied. Defaults to `is_active_in_any_of`."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum number of subscribers to return. Defaults to 25 and is capped at 100."
    },
    "starting_after": {
      "type": "string",
      "description": "Use the opaque cursor from the previous page to request the next page."
    }
  },
  "additionalProperties": false
}

subscribers_get

Returns one Subscriber by its stable identifier from the authenticated workspace. Permission: subscribers:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

subscriber_id

string

required

The Subscriber identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "string",
      "description": "The Subscriber identifier."
    }
  },
  "required": [
    "subscriber_id"
  ],
  "additionalProperties": false
}

subscribers_upsert

Creates a new subscriber when the email does not exist in the workspace. If the email already exists, the API updates the existing subscriber unless create_only is true. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/SubscriberUpsertRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "SubscriberUpsertRequest": {
      "type": "object",
      "required": [
        "email"
      ],
      "properties": {
        "email": {
          "type": "string",
          "format": "email"
        },
        "name": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "Active",
            "Unconfirmed",
            "Unsubscribed",
            "Complained",
            "Bounced",
            "Blocked"
          ]
        },
        "country": {
          "anyOf": [
            {
              "type": "string",
              "description": "Two-letter country code or country name. Mailrith stores Subscriber country as a two-letter country code."
            },
            {
              "type": "null"
            }
          ]
        },
        "subscribed_on": {
          "type": "string",
          "example": "2026-04-11",
          "description": "Subscriber-local subscription date in YYYY-MM-DD format.",
          "examples": [
            "2026-04-11"
          ]
        },
        "create_only": {
          "type": "boolean",
          "description": "When true, Mailrith returns a 409 conflict instead of updating an existing subscriber with the same email."
        },
        "custom_fields": {
          "type": "object",
          "additionalProperties": true,
          "description": "Custom field values keyed by custom field ID. For Multi Select fields, send an array of option names or a comma-separated string. Blank optional values leave saved values unchanged when updating an existing subscriber, and filled-in invalid values are rejected."
        },
        "consent_evidence": {
          "$ref": "#/$defs/ConsentEvidence"
        }
      },
      "example": {
        "email": "ada@example.com",
        "name": "Ada Lovelace",
        "status": "Unconfirmed",
        "country": "DE",
        "custom_fields": {
          "cf_company": "Analytical Engines"
        }
      },
      "examples": [
        {
          "email": "ada@example.com",
          "name": "Ada Lovelace",
          "status": "Unconfirmed",
          "country": "DE",
          "custom_fields": {
            "cf_company": "Analytical Engines"
          }
        }
      ]
    },
    "ConsentEvidence": {
      "type": "object",
      "description": "Compact evidence required when the public API makes a Subscriber Active. Keep raw consent text, IP addresses, and user-agent data in your evidence system; Mailrith stores only this version, reference, URL, and optional SHA-256 digest.",
      "required": [
        "lawful_basis",
        "collected_at",
        "evidence_reference"
      ],
      "additionalProperties": false,
      "properties": {
        "lawful_basis": {
          "type": "string",
          "maxLength": 64
        },
        "consent_text_version": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 128
            },
            {
              "type": "null"
            }
          ]
        },
        "collected_at": {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
          "description": "When the consent evidence was collected, as ISO 8601 with an explicit UTC offset. This must not be later than Mailrith's server time. Do not treat a workspace-local clock as UTC; use the evidence record's confirmed timestamp."
        },
        "source_url": {
          "anyOf": [
            {
              "type": "string",
              "format": "uri",
              "maxLength": 2048
            },
            {
              "type": "null"
            }
          ]
        },
        "evidence_reference": {
          "type": "string",
          "maxLength": 512
        },
        "technical_evidence_hash": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    }
  }
}

subscribers_update

Updates profile fields, status, custom fields, tags, or sequence assignments for one subscriber. Fields omitted from the request stay unchanged. Blank optional custom field values also leave saved values unchanged, and filled-in invalid values are rejected. Effect: subscriber-change. Retry after reading the current resource state. Permission: subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

subscriber_id	string	required	The subscriber identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "string",
      "description": "The subscriber identifier."
    },
    "body": {
      "$ref": "#/$defs/SubscriberUpdateRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "subscriber_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "SubscriberUpdateRequest": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email"
        },
        "name": {
          "type": "string"
        },
        "country": {
          "anyOf": [
            {
              "type": "string",
              "description": "Two-letter country code or country name. Mailrith stores Subscriber country as a two-letter country code."
            },
            {
              "type": "null"
            }
          ]
        },
        "subscribed_on": {
          "type": "string",
          "example": "2026-04-11",
          "description": "Subscriber-local subscription date in YYYY-MM-DD format.",
          "examples": [
            "2026-04-11"
          ]
        },
        "custom_fields": {
          "type": "object",
          "additionalProperties": true,
          "description": "Custom field values keyed by custom field ID. For Multi Select fields, send an array of option names or a comma-separated string. Blank optional values leave saved values unchanged, and filled-in invalid values are rejected."
        }
      },
      "example": {
        "name": "Ada Lovelace",
        "country": "DE",
        "custom_fields": {
          "cf_company": "Analytical Engines"
        }
      },
      "examples": [
        {
          "name": "Ada Lovelace",
          "country": "DE",
          "custom_fields": {
            "cf_company": "Analytical Engines"
          }
        }
      ]
    }
  }
}

subscribers_update_status

Changes the delivery status for one Subscriber without changing profile, targeting, or Sequence enrollment fields. Making a Subscriber Active requires consent_evidence; its collected_at value must include the correct UTC offset and must not be later than Mailrith's server time. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

subscriber_id	string	required	The Subscriber identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "string",
      "description": "The Subscriber identifier."
    },
    "body": {
      "$ref": "#/$defs/SubscriberStatusRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "subscriber_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "SubscriberStatusRequest": {
      "type": "object",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "Active",
            "Unconfirmed",
            "Unsubscribed",
            "Complained",
            "Bounced",
            "Blocked"
          ]
        },
        "consent_evidence": {
          "$ref": "#/$defs/ConsentEvidence"
        }
      }
    },
    "ConsentEvidence": {
      "type": "object",
      "description": "Compact evidence required when the public API makes a Subscriber Active. Keep raw consent text, IP addresses, and user-agent data in your evidence system; Mailrith stores only this version, reference, URL, and optional SHA-256 digest.",
      "required": [
        "lawful_basis",
        "collected_at",
        "evidence_reference"
      ],
      "additionalProperties": false,
      "properties": {
        "lawful_basis": {
          "type": "string",
          "maxLength": 64
        },
        "consent_text_version": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 128
            },
            {
              "type": "null"
            }
          ]
        },
        "collected_at": {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
          "description": "When the consent evidence was collected, as ISO 8601 with an explicit UTC offset. This must not be later than Mailrith's server time. Do not treat a workspace-local clock as UTC; use the evidence record's confirmed timestamp."
        },
        "source_url": {
          "anyOf": [
            {
              "type": "string",
              "format": "uri",
              "maxLength": 2048
            },
            {
              "type": "null"
            }
          ]
        },
        "evidence_reference": {
          "type": "string",
          "maxLength": 512
        },
        "technical_evidence_hash": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    }
  }
}

subscribers_add_tag

Adds the selected Tag to a Subscriber. If the Subscriber already has the Tag, the API returns the Subscriber unchanged. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

subscriber_id	string	required	The Subscriber identifier.
tag_id	string	required	The Tag identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "string",
      "description": "The Subscriber identifier."
    },
    "tag_id": {
      "type": "string",
      "description": "The Tag identifier."
    }
  },
  "required": [
    "subscriber_id",
    "tag_id"
  ],
  "additionalProperties": false
}

subscribers_remove_tag

Removes the selected tag from a subscriber. If the subscriber does not have the tag, the API returns the subscriber unchanged. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

subscriber_id	string	required	The subscriber identifier.
tag_id	string	required	The tag identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "string",
      "description": "The subscriber identifier."
    },
    "tag_id": {
      "type": "string",
      "description": "The tag identifier."
    }
  },
  "required": [
    "subscriber_id",
    "tag_id"
  ],
  "additionalProperties": false
}

subscribers_add_to_sequence

Adds the selected subscriber to the selected sequence. If the subscriber is already in the sequence, the API returns the subscriber unchanged. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

subscriber_id	string	required	The subscriber identifier.
sequence_id	string	required	The sequence identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "string",
      "description": "The subscriber identifier."
    },
    "sequence_id": {
      "type": "string",
      "description": "The sequence identifier."
    }
  },
  "required": [
    "subscriber_id",
    "sequence_id"
  ],
  "additionalProperties": false
}

subscribers_remove_from_sequence

Removes the selected subscriber from the selected sequence. If the subscriber is not in the sequence, the API returns the subscriber unchanged. Effect: subscriber-change. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

subscriber_id	string	required	The subscriber identifier.
sequence_id	string	required	The sequence identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "subscriber_id": {
      "type": "string",
      "description": "The subscriber identifier."
    },
    "sequence_id": {
      "type": "string",
      "description": "The sequence identifier."
    }
  },
  "required": [
    "subscriber_id",
    "sequence_id"
  ],
  "additionalProperties": false
}

tags_list

Returns tags in the authenticated workspace. Permission: tags:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters3

search	string	optional	Filter Tags by name or description. Retrieve a known Tag ID through the item endpoint.
limit	integer	optional	Maximum number of tags to return.
starting_after	string	optional	Use the opaque cursor from the previous page to request the next page.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Filter Tags by name or description. Retrieve a known Tag ID through the item endpoint."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum number of tags to return."
    },
    "starting_after": {
      "type": "string",
      "description": "Use the opaque cursor from the previous page to request the next page."
    }
  },
  "additionalProperties": false
}

tags_get

Returns one Tag from the authenticated workspace. Permission: tags:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

tag_id

string

required

The Tag identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "tag_id": {
      "type": "string",
      "description": "The Tag identifier."
    }
  },
  "required": [
    "tag_id"
  ],
  "additionalProperties": false
}

tags_create

Creates a new tag in the authenticated workspace. The GDPR consent tag names can be created and applied like other tags when you need to apply consent collected outside Mailrith. Tag-level double opt-in fields are no longer accepted; configure double opt-in on forms and landing pages instead. Effect: workspace-change. Retry with the same idempotency_key. Permission: tags:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/TagCreateRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "TagCreateRequest": {
      "type": "object",
      "required": [
        "name"
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string",
          "description": "Tag name to create. You can also create the GDPR consent tag names when you need to apply consent collected outside Mailrith."
        },
        "description": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    }
  }
}

custom_fields_list

Returns a bounded page of custom fields in the authenticated workspace, including each field's exact ready-to-use email personalization token. Permission: custom_fields:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters3

search	string	optional	Filter custom fields by label or type.
limit	integer	optional	Maximum number of custom fields to return.
starting_after	string	optional	Use the opaque cursor from the previous page to request the next page.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200,
      "description": "Filter custom fields by label or type."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum number of custom fields to return."
    },
    "starting_after": {
      "type": "string",
      "description": "Use the opaque cursor from the previous page to request the next page."
    }
  },
  "additionalProperties": false
}

custom_fields_get

Returns one custom field from the authenticated workspace, including its exact ready-to-use email personalization token. Permission: custom_fields:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

custom_field_id

string

required

The custom field identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "custom_field_id": {
      "type": "string",
      "description": "The custom field identifier."
    }
  },
  "required": [
    "custom_field_id"
  ],
  "additionalProperties": false
}

segments_list

Returns saved segments from the authenticated workspace. Permission: segments:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters3

search	string	optional	Filter Segments by name or description.
limit	integer	optional	The maximum number of segments to return.
starting_after	string	optional	The opaque cursor from the previous page of saved segments.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200,
      "description": "Filter Segments by name or description."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "The maximum number of segments to return."
    },
    "starting_after": {
      "type": "string",
      "description": "The opaque cursor from the previous page of saved segments."
    }
  },
  "additionalProperties": false
}

segments_get

Returns one saved segment from the authenticated workspace. Permission: segments:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

segment_id

string

required

The identifier of the segment to return.

Raw schema

{
  "type": "object",
  "properties": {
    "segment_id": {
      "type": "string",
      "description": "The identifier of the segment to return."
    }
  },
  "required": [
    "segment_id"
  ],
  "additionalProperties": false
}

segments_preview

Returns subscriber counts for an unsaved segment definition. Include `current_segment_id` when previewing edits to an existing segment so circular segment references are rejected before saving. Permission: segments:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

body

object

required

The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "body": {
      "$ref": "#/$defs/SegmentPreviewRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "SegmentPreviewRequest": {
      "type": "object",
      "required": [
        "definition"
      ],
      "properties": {
        "definition": {
          "description": "The segment filters to preview. Include at least one filter group.",
          "allOf": [
            {
              "$ref": "#/$defs/AudienceDefinition"
            }
          ]
        },
        "current_segment_id": {
          "anyOf": [
            {
              "type": "string",
              "description": "When previewing an edit to an existing segment, include that segment id so Mailrith can catch circular segment references before saving."
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "AudienceDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "match",
        "groups"
      ],
      "properties": {
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "groups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AudienceConditionGroup"
          }
        }
      },
      "example": {
        "match": "all",
        "groups": [
          {
            "id": "active-subscribers",
            "match": "all",
            "conditions": [
              {
                "id": "active-status",
                "field": "subscriber_status",
                "operator": "is",
                "value": [
                  "Active"
                ]
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "match": "all",
          "groups": [
            {
              "id": "active-subscribers",
              "match": "all",
              "conditions": [
                {
                  "id": "active-status",
                  "field": "subscriber_status",
                  "operator": "is",
                  "value": [
                    "Active"
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    "AudienceConditionGroup": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "match",
        "conditions"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "conditions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/AudienceCondition"
          }
        }
      }
    },
    "AudienceCondition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "field",
        "operator"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "enum": [
            "subscriber_status",
            "country",
            "segment",
            "tag",
            "sequence",
            "form",
            "custom_field",
            "email_opened",
            "email_unsubscribed",
            "magic_link_clicked"
          ]
        },
        "operator": {
          "type": "string",
          "enum": [
            "is",
            "is_not",
            "has_any_of",
            "has_none_of",
            "is_active_in_any_of",
            "is_not_active_in_any_of",
            "has_completed_any_of",
            "has_not_completed_any_of",
            "has_ever_been_in_any_of",
            "has_never_been_in_any_of",
            "contains",
            "does_not_contain",
            "is_empty",
            "is_not_empty",
            "before",
            "after",
            "on",
            "in_last_days",
            "greater_than",
            "less_than",
            "in_region",
            "not_in_region"
          ]
        },
        "value": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "customFieldId": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}

broadcasts_list

Returns broadcast drafts, scheduled sends, active sends, and completed sends. Permission: broadcasts:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters3

search	string	optional	Filter Broadcasts by subject, preview text, status, or sender.
limit	integer	optional	Maximum number of items to return.
starting_after	string	optional	Opaque cursor returned by the previous page.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200,
      "description": "Filter Broadcasts by subject, preview text, status, or sender."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum number of items to return."
    },
    "starting_after": {
      "type": "string",
      "description": "Opaque cursor returned by the previous page."
    }
  },
  "additionalProperties": false
}

broadcasts_create

Creates a broadcast draft in the authenticated workspace. Effect: workspace-change. Retry with the same idempotency_key. Permission: broadcasts:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/BroadcastUpsertRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "BroadcastUpsertRequest": {
      "type": "object",
      "required": [
        "subject",
        "body_document"
      ],
      "additionalProperties": false,
      "properties": {
        "subject": {
          "type": "string",
          "description": "For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text."
        },
        "preview_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "body_document": {
          "description": "For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
          "allOf": [
            {
              "$ref": "#/$defs/BroadcastEmailDocument"
            }
          ]
        },
        "connection_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "reply_to_email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "audience_definition": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceDefinition"
            },
            {
              "type": "null"
            }
          ]
        },
        "track_opens": {
          "type": "boolean"
        },
        "track_clicks": {
          "type": "boolean"
        },
        "utm_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_medium": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_campaign": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_term": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "BroadcastEmailDocument": {
      "allOf": [
        {
          "$ref": "#/$defs/BroadcastEmailNode"
        }
      ],
      "description": "A structured email document. The root node must use type `doc` and contain supported block nodes. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
                }
              ]
            }
          ]
        }
      ]
    },
    "BroadcastEmailNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "doc",
            "paragraph",
            "heading",
            "text",
            "hardBreak",
            "bulletList",
            "orderedList",
            "listItem",
            "blockquote",
            "emailSection",
            "emailSectionColumn",
            "emailButton",
            "image",
            "horizontalRule"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "textAlign": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ]
            },
            "columns": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "width": {
              "type": "string",
              "enum": [
                "default",
                "large",
                "full",
                "fit"
              ]
            },
            "backgroundColor": {
              "type": "string"
            },
            "blockquoteBorderColor": {
              "type": "string"
            },
            "linkColor": {
              "type": "string"
            },
            "layoutAlignment": {
              "type": "string",
              "enum": [
                "left",
                "center"
              ]
            },
            "backgroundImageUrl": {
              "type": "string"
            },
            "margin": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "padding": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderColor": {
              "type": "string"
            },
            "borderWidth": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderRadius": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "small",
                "large",
                "full"
              ]
            },
            "verticalAlign": {
              "type": "string",
              "enum": [
                "top",
                "middle",
                "bottom"
              ]
            },
            "href": {
              "type": "string"
            },
            "textColor": {
              "type": "string"
            },
            "size": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large"
              ]
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right"
              ]
            },
            "label": {
              "type": "string"
            },
            "src": {
              "type": "string"
            },
            "alt": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "caption": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "unsplash"
              ]
            },
            "unsplash": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photographerName"
              ],
              "properties": {
                "photoId": {
                  "type": "string"
                },
                "photographerName": {
                  "type": "string"
                },
                "photographerUsername": {
                  "type": "string"
                },
                "photographerUrl": {
                  "type": "string"
                },
                "unsplashUrl": {
                  "type": "string"
                }
              }
            },
            "widthPercent": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "crop": {
              "type": "string",
              "enum": [
                "none",
                "square",
                "circle"
              ]
            },
            "fillColumn": {
              "type": "boolean"
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailNode"
          }
        },
        "text": {
          "type": "string"
        },
        "marks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailMark"
          }
        }
      }
    },
    "BroadcastEmailMark": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bold",
            "italic",
            "strike",
            "underline",
            "link",
            "textStyle",
            "highlight"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "href": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "fontSize": {
              "type": "string"
            }
          }
        }
      }
    },
    "AudienceDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "match",
        "groups"
      ],
      "properties": {
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "groups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AudienceConditionGroup"
          }
        }
      },
      "example": {
        "match": "all",
        "groups": [
          {
            "id": "active-subscribers",
            "match": "all",
            "conditions": [
              {
                "id": "active-status",
                "field": "subscriber_status",
                "operator": "is",
                "value": [
                  "Active"
                ]
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "match": "all",
          "groups": [
            {
              "id": "active-subscribers",
              "match": "all",
              "conditions": [
                {
                  "id": "active-status",
                  "field": "subscriber_status",
                  "operator": "is",
                  "value": [
                    "Active"
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    "AudienceConditionGroup": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "match",
        "conditions"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "conditions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/AudienceCondition"
          }
        }
      }
    },
    "AudienceCondition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "field",
        "operator"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "enum": [
            "subscriber_status",
            "country",
            "segment",
            "tag",
            "sequence",
            "form",
            "custom_field",
            "email_opened",
            "email_unsubscribed",
            "magic_link_clicked"
          ]
        },
        "operator": {
          "type": "string",
          "enum": [
            "is",
            "is_not",
            "has_any_of",
            "has_none_of",
            "is_active_in_any_of",
            "is_not_active_in_any_of",
            "has_completed_any_of",
            "has_not_completed_any_of",
            "has_ever_been_in_any_of",
            "has_never_been_in_any_of",
            "contains",
            "does_not_contain",
            "is_empty",
            "is_not_empty",
            "before",
            "after",
            "on",
            "in_last_days",
            "greater_than",
            "less_than",
            "in_region",
            "not_in_region"
          ]
        },
        "value": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "customFieldId": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}

broadcasts_get

Returns a broadcast draft, scheduled send, active send, or completed send. Permission: broadcasts:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

broadcast_id

string

required

The broadcast identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    }
  },
  "required": [
    "broadcast_id"
  ],
  "additionalProperties": false
}

broadcasts_update

Updates an existing Broadcast draft. Scheduled, running, completed, and failed Broadcasts cannot be changed here. Before changing a scheduled Broadcast, read it by ID and retain its scheduled_at in the current task only. If the saved time is no longer safely in the future, ask the user for a new time before unscheduling. Otherwise unschedule it, apply the update, reschedule it for the same time, and verify both status and scheduled_at. If the update fails after unscheduling, restore the unchanged Broadcast to the same future time when possible. If the schedule cannot be restored, leave it as a Draft and immediately report that it will not send; never choose a replacement time without the user. Effect: workspace-change. Retry after reading the current resource state. Permission: broadcasts:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

broadcast_id	string	required	The broadcast identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    },
    "body": {
      "$ref": "#/$defs/BroadcastUpdateRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "broadcast_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "BroadcastUpdateRequest": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": false,
      "properties": {
        "subject": {
          "type": "string",
          "description": "For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text."
        },
        "preview_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "body_document": {
          "description": "For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
          "allOf": [
            {
              "$ref": "#/$defs/BroadcastEmailDocument"
            }
          ]
        },
        "connection_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "reply_to_email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "audience_definition": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceDefinition"
            },
            {
              "type": "null"
            }
          ]
        },
        "track_opens": {
          "type": "boolean"
        },
        "track_clicks": {
          "type": "boolean"
        },
        "utm_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_medium": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_campaign": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_term": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "BroadcastEmailDocument": {
      "allOf": [
        {
          "$ref": "#/$defs/BroadcastEmailNode"
        }
      ],
      "description": "A structured email document. The root node must use type `doc` and contain supported block nodes. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
                }
              ]
            }
          ]
        }
      ]
    },
    "BroadcastEmailNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "doc",
            "paragraph",
            "heading",
            "text",
            "hardBreak",
            "bulletList",
            "orderedList",
            "listItem",
            "blockquote",
            "emailSection",
            "emailSectionColumn",
            "emailButton",
            "image",
            "horizontalRule"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "textAlign": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ]
            },
            "columns": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "width": {
              "type": "string",
              "enum": [
                "default",
                "large",
                "full",
                "fit"
              ]
            },
            "backgroundColor": {
              "type": "string"
            },
            "blockquoteBorderColor": {
              "type": "string"
            },
            "linkColor": {
              "type": "string"
            },
            "layoutAlignment": {
              "type": "string",
              "enum": [
                "left",
                "center"
              ]
            },
            "backgroundImageUrl": {
              "type": "string"
            },
            "margin": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "padding": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderColor": {
              "type": "string"
            },
            "borderWidth": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderRadius": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "small",
                "large",
                "full"
              ]
            },
            "verticalAlign": {
              "type": "string",
              "enum": [
                "top",
                "middle",
                "bottom"
              ]
            },
            "href": {
              "type": "string"
            },
            "textColor": {
              "type": "string"
            },
            "size": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large"
              ]
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right"
              ]
            },
            "label": {
              "type": "string"
            },
            "src": {
              "type": "string"
            },
            "alt": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "caption": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "unsplash"
              ]
            },
            "unsplash": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photographerName"
              ],
              "properties": {
                "photoId": {
                  "type": "string"
                },
                "photographerName": {
                  "type": "string"
                },
                "photographerUsername": {
                  "type": "string"
                },
                "photographerUrl": {
                  "type": "string"
                },
                "unsplashUrl": {
                  "type": "string"
                }
              }
            },
            "widthPercent": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "crop": {
              "type": "string",
              "enum": [
                "none",
                "square",
                "circle"
              ]
            },
            "fillColumn": {
              "type": "boolean"
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailNode"
          }
        },
        "text": {
          "type": "string"
        },
        "marks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailMark"
          }
        }
      }
    },
    "BroadcastEmailMark": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bold",
            "italic",
            "strike",
            "underline",
            "link",
            "textStyle",
            "highlight"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "href": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "fontSize": {
              "type": "string"
            }
          }
        }
      }
    },
    "AudienceDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "match",
        "groups"
      ],
      "properties": {
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "groups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AudienceConditionGroup"
          }
        }
      },
      "example": {
        "match": "all",
        "groups": [
          {
            "id": "active-subscribers",
            "match": "all",
            "conditions": [
              {
                "id": "active-status",
                "field": "subscriber_status",
                "operator": "is",
                "value": [
                  "Active"
                ]
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "match": "all",
          "groups": [
            {
              "id": "active-subscribers",
              "match": "all",
              "conditions": [
                {
                  "id": "active-status",
                  "field": "subscriber_status",
                  "operator": "is",
                  "value": [
                    "Active"
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    "AudienceConditionGroup": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "match",
        "conditions"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "conditions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/AudienceCondition"
          }
        }
      }
    },
    "AudienceCondition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "field",
        "operator"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "enum": [
            "subscriber_status",
            "country",
            "segment",
            "tag",
            "sequence",
            "form",
            "custom_field",
            "email_opened",
            "email_unsubscribed",
            "magic_link_clicked"
          ]
        },
        "operator": {
          "type": "string",
          "enum": [
            "is",
            "is_not",
            "has_any_of",
            "has_none_of",
            "is_active_in_any_of",
            "is_not_active_in_any_of",
            "has_completed_any_of",
            "has_not_completed_any_of",
            "has_ever_been_in_any_of",
            "has_never_been_in_any_of",
            "contains",
            "does_not_contain",
            "is_empty",
            "is_not_empty",
            "before",
            "after",
            "on",
            "in_last_days",
            "greater_than",
            "less_than",
            "in_region",
            "not_in_region"
          ]
        },
        "value": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "customFieldId": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}

broadcasts_preflight

Optionally checks the current Subscriber estimate, provider capacity, sender setup, event tracking, and blocking issues. This diagnostic is not required before starting a durable send. Permission: broadcasts:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

broadcast_id

string

required

The broadcast identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    }
  },
  "required": [
    "broadcast_id"
  ],
  "additionalProperties": false
}

broadcasts_send_test

Sends a test message from an existing Broadcast that has an email delivery connection. Provide a saved Subscriber ID for personalization; use subscribers_list to find one when needed. The recipient may be any test inbox and does not have to match the saved Subscriber. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, subscribers:read, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.

Parameters3

broadcast_id	string	required	The broadcast identifier.
idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/BroadcastTestRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "broadcast_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "BroadcastTestRequest": {
      "type": "object",
      "required": [
        "recipient",
        "subscriber_id"
      ],
      "additionalProperties": false,
      "properties": {
        "recipient": {
          "type": "string",
          "format": "email",
          "description": "The inbox that receives the test message. It may differ from the saved Subscriber used for personalization."
        },
        "subscriber_id": {
          "type": "string",
          "description": "Required saved Subscriber ID whose profile supplies personalization. Use subscribers_list to find one before sending the test when needed."
        }
      }
    }
  }
}

broadcasts_schedule

Schedules a draft for future delivery, or changes the delivery time of an existing scheduled Broadcast. This uses Mailrith's durable scheduled-send path and does not start delivery immediately. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

broadcast_id	string	required	The broadcast identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    },
    "body": {
      "$ref": "#/$defs/BroadcastScheduleRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "broadcast_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "BroadcastScheduleRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "scheduled_at"
      ],
      "properties": {
        "scheduled_at": {
          "type": "string",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|[+-](?:[01]\\d|2[0-3]):[0-5]\\d)$",
          "description": "A future date and time. Include an explicit UTC offset or Z suffix."
        }
      },
      "example": {
        "scheduled_at": "2026-08-01T09:30:00.000Z"
      },
      "examples": [
        {
          "scheduled_at": "2026-08-01T09:30:00.000Z"
        }
      ]
    }
  }
}

broadcasts_unschedule

Returns a scheduled Broadcast to draft state before delivery starts. Effect: workspace-change. Retry after reading the current resource state. Permissions: live_actions:write, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.

Parameters1

broadcast_id

string

required

The broadcast identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    }
  },
  "required": [
    "broadcast_id"
  ],
  "additionalProperties": false
}

broadcasts_send

Immediately creates durable preparation for a broadcast draft or scheduled send. Mailrith calculates the exact Subscriber total and checks provider readiness in the background before delivery. A 202 response means the durable send was accepted, not that provider delivery is complete. Reuse the same idempotency key if the response is lost. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.

Parameters3

broadcast_id	string	required	The broadcast identifier.
idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	optional	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "type": "object",
      "properties": {
        "preflight_proof": {
          "type": "string",
          "description": "Optional unchanged short-lived send_proof returned by a recent diagnostic preflight. A valid proof can seed its checked estimate. If it is omitted, expired, or no longer matches, Mailrith still creates the run immediately and calculates the exact total during durable preparation."
        }
      },
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "broadcast_id"
  ],
  "additionalProperties": false
}

broadcasts_cancel

Requests cancellation for delivery work that has not reached the provider. Provider-accepted emails cannot be recalled. Repeat the same request with the same idempotency key when the response is lost. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

broadcast_id	string	required	The broadcast identifier.
idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    }
  },
  "required": [
    "broadcast_id"
  ],
  "additionalProperties": false
}

broadcasts_get_send_progress

Returns bounded delivery progress, current rates, timing, outcome counts, and pause state. Poll until terminal is true; use 5 to 10 second intervals while progress changes and back off to 30 seconds when unchanged. Permission: broadcasts:read. Polling: wait at least 2 seconds, use exponential backoff up to 30 seconds, stop at a terminal state, and stop after 15 minutes. API reference: https://mailrith.com/developers/api-reference.

Parameters1

broadcast_id

string

required

The broadcast identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    }
  },
  "required": [
    "broadcast_id"
  ],
  "additionalProperties": false
}

sequences_list

Returns sequences in the authenticated workspace. Permission: sequences:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters3

search	string	optional	Filter sequences by name, status, or sender details. Retrieve a known Sequence ID through the item endpoint.
limit	integer	optional	Maximum number of sequences to return.
starting_after	string	optional	Use the opaque cursor from the previous page to request the next page.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Filter sequences by name, status, or sender details. Retrieve a known Sequence ID through the item endpoint."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum number of sequences to return."
    },
    "starting_after": {
      "type": "string",
      "description": "Use the opaque cursor from the previous page to request the next page."
    }
  },
  "additionalProperties": false
}

sequences_create

Creates a sequence in the authenticated workspace. Effect: workspace-change. Retry with the same idempotency_key. Permission: sequences:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/SequenceUpsertRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "SequenceUpsertRequest": {
      "type": "object",
      "required": [
        "name",
        "definition"
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "connection_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "reply_to_email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "track_opens": {
          "type": "boolean"
        },
        "track_clicks": {
          "type": "boolean"
        },
        "utm_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_medium": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_campaign": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_term": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "definition": {
          "$ref": "#/$defs/SequenceDefinition"
        }
      }
    },
    "SequenceDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "emails"
      ],
      "properties": {
        "emails": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SequenceEmail"
          }
        },
        "defaultTemplateId": {
          "type": [
            "string",
            "null"
          ]
        },
        "sendOnWeekdays": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": [
              "Mon",
              "Tue",
              "Wed",
              "Thu",
              "Fri",
              "Sat",
              "Sun"
            ]
          }
        },
        "excludeAudienceDefinition": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceDefinition"
            },
            {
              "type": "null"
            }
          ]
        },
        "restartSequenceForCompletedSubscribers": {
          "type": "boolean"
        },
        "sendNewEmailsToCompletedSubscribers": {
          "type": "boolean"
        }
      },
      "example": {
        "emails": [
          {
            "id": "welcome",
            "subject": "Welcome",
            "previewText": "Thanks for joining",
            "bodyDocument": {
              "type": "doc",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Welcome to the newsletter."
                    }
                  ]
                }
              ]
            },
            "status": "Published",
            "delayValue": 0,
            "delayUnit": "day",
            "sendOnWeekdays": [
              "Mon",
              "Tue",
              "Wed",
              "Thu",
              "Fri"
            ],
            "audienceMode": "all",
            "audienceDefinition": null
          }
        ]
      },
      "examples": [
        {
          "emails": [
            {
              "id": "welcome",
              "subject": "Welcome",
              "previewText": "Thanks for joining",
              "bodyDocument": {
                "type": "doc",
                "content": [
                  {
                    "type": "paragraph",
                    "content": [
                      {
                        "type": "text",
                        "text": "Welcome to the newsletter."
                      }
                    ]
                  }
                ]
              },
              "status": "Published",
              "delayValue": 0,
              "delayUnit": "day",
              "sendOnWeekdays": [
                "Mon",
                "Tue",
                "Wed",
                "Thu",
                "Fri"
              ],
              "audienceMode": "all",
              "audienceDefinition": null
            }
          ]
        }
      ]
    },
    "SequenceEmail": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "subject",
        "previewText",
        "bodyDocument",
        "status",
        "delayValue",
        "delayUnit",
        "sendOnWeekdays"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "subject": {
          "type": "string",
          "description": "For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text."
        },
        "previewText": {
          "type": [
            "string",
            "null"
          ]
        },
        "bodyDocument": {
          "$ref": "#/$defs/BroadcastEmailDocument"
        },
        "status": {
          "type": "string",
          "enum": [
            "Draft",
            "Published"
          ]
        },
        "delayValue": {
          "type": "number",
          "minimum": 0
        },
        "delayUnit": {
          "type": "string",
          "enum": [
            "minute",
            "hour",
            "day"
          ]
        },
        "sendOnWeekdays": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": [
              "Mon",
              "Tue",
              "Wed",
              "Thu",
              "Fri",
              "Sat",
              "Sun"
            ]
          }
        },
        "audienceMode": {
          "type": "string",
          "enum": [
            "all",
            "include",
            "exclude"
          ]
        },
        "audienceDefinition": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceDefinition"
            },
            {
              "type": "null"
            }
          ]
        },
        "stats": {
          "$ref": "#/$defs/EmailEngagementStats"
        }
      }
    },
    "BroadcastEmailDocument": {
      "allOf": [
        {
          "$ref": "#/$defs/BroadcastEmailNode"
        }
      ],
      "description": "A structured email document. The root node must use type `doc` and contain supported block nodes. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
                }
              ]
            }
          ]
        }
      ]
    },
    "BroadcastEmailNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "doc",
            "paragraph",
            "heading",
            "text",
            "hardBreak",
            "bulletList",
            "orderedList",
            "listItem",
            "blockquote",
            "emailSection",
            "emailSectionColumn",
            "emailButton",
            "image",
            "horizontalRule"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "textAlign": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ]
            },
            "columns": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "width": {
              "type": "string",
              "enum": [
                "default",
                "large",
                "full",
                "fit"
              ]
            },
            "backgroundColor": {
              "type": "string"
            },
            "blockquoteBorderColor": {
              "type": "string"
            },
            "linkColor": {
              "type": "string"
            },
            "layoutAlignment": {
              "type": "string",
              "enum": [
                "left",
                "center"
              ]
            },
            "backgroundImageUrl": {
              "type": "string"
            },
            "margin": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "padding": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderColor": {
              "type": "string"
            },
            "borderWidth": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderRadius": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "small",
                "large",
                "full"
              ]
            },
            "verticalAlign": {
              "type": "string",
              "enum": [
                "top",
                "middle",
                "bottom"
              ]
            },
            "href": {
              "type": "string"
            },
            "textColor": {
              "type": "string"
            },
            "size": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large"
              ]
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right"
              ]
            },
            "label": {
              "type": "string"
            },
            "src": {
              "type": "string"
            },
            "alt": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "caption": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "unsplash"
              ]
            },
            "unsplash": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photographerName"
              ],
              "properties": {
                "photoId": {
                  "type": "string"
                },
                "photographerName": {
                  "type": "string"
                },
                "photographerUsername": {
                  "type": "string"
                },
                "photographerUrl": {
                  "type": "string"
                },
                "unsplashUrl": {
                  "type": "string"
                }
              }
            },
            "widthPercent": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "crop": {
              "type": "string",
              "enum": [
                "none",
                "square",
                "circle"
              ]
            },
            "fillColumn": {
              "type": "boolean"
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailNode"
          }
        },
        "text": {
          "type": "string"
        },
        "marks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailMark"
          }
        }
      }
    },
    "BroadcastEmailMark": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bold",
            "italic",
            "strike",
            "underline",
            "link",
            "textStyle",
            "highlight"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "href": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "fontSize": {
              "type": "string"
            }
          }
        }
      }
    },
    "AudienceDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "match",
        "groups"
      ],
      "properties": {
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "groups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AudienceConditionGroup"
          }
        }
      },
      "example": {
        "match": "all",
        "groups": [
          {
            "id": "active-subscribers",
            "match": "all",
            "conditions": [
              {
                "id": "active-status",
                "field": "subscriber_status",
                "operator": "is",
                "value": [
                  "Active"
                ]
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "match": "all",
          "groups": [
            {
              "id": "active-subscribers",
              "match": "all",
              "conditions": [
                {
                  "id": "active-status",
                  "field": "subscriber_status",
                  "operator": "is",
                  "value": [
                    "Active"
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    "AudienceConditionGroup": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "match",
        "conditions"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "conditions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/AudienceCondition"
          }
        }
      }
    },
    "AudienceCondition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "field",
        "operator"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "enum": [
            "subscriber_status",
            "country",
            "segment",
            "tag",
            "sequence",
            "form",
            "custom_field",
            "email_opened",
            "email_unsubscribed",
            "magic_link_clicked"
          ]
        },
        "operator": {
          "type": "string",
          "enum": [
            "is",
            "is_not",
            "has_any_of",
            "has_none_of",
            "is_active_in_any_of",
            "is_not_active_in_any_of",
            "has_completed_any_of",
            "has_not_completed_any_of",
            "has_ever_been_in_any_of",
            "has_never_been_in_any_of",
            "contains",
            "does_not_contain",
            "is_empty",
            "is_not_empty",
            "before",
            "after",
            "on",
            "in_last_days",
            "greater_than",
            "less_than",
            "in_region",
            "not_in_region"
          ]
        },
        "value": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "customFieldId": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "EmailEngagementStats": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "recipientCount",
        "openedCount",
        "clickedCount",
        "unsubscribedCount"
      ],
      "properties": {
        "recipientCount": {
          "type": "integer",
          "minimum": 0
        },
        "engagedCount": {
          "type": "integer",
          "minimum": 0
        },
        "openedCount": {
          "type": "integer",
          "minimum": 0
        },
        "clickedCount": {
          "type": "integer",
          "minimum": 0
        },
        "clickedSubscriberCount": {
          "type": "integer",
          "minimum": 0
        },
        "unsubscribedCount": {
          "type": "integer",
          "minimum": 0
        },
        "bouncedCount": {
          "type": "integer",
          "minimum": 0
        },
        "complainedCount": {
          "type": "integer",
          "minimum": 0
        },
        "sentCountsByDay": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    }
  }
}

sequences_get

Returns one sequence from the authenticated workspace. Permission: sequences:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

sequence_id

string

required

The sequence identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "sequence_id": {
      "type": "string",
      "description": "The sequence identifier."
    }
  },
  "required": [
    "sequence_id"
  ],
  "additionalProperties": false
}

sequences_update

Updates an existing paused Sequence. Before changing a running Sequence, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Sequence, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate a Sequence that was not already running. Effect: workspace-change. Retry after reading the current resource state. Permission: sequences:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

sequence_id	string	required	The sequence identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "sequence_id": {
      "type": "string",
      "description": "The sequence identifier."
    },
    "body": {
      "$ref": "#/$defs/SequenceUpdateRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "sequence_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "SequenceUpdateRequest": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "connection_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "reply_to_email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "track_opens": {
          "type": "boolean"
        },
        "track_clicks": {
          "type": "boolean"
        },
        "utm_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_medium": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_campaign": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_term": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "utm_content": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "definition": {
          "$ref": "#/$defs/SequenceDefinition"
        }
      }
    },
    "SequenceDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "emails"
      ],
      "properties": {
        "emails": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SequenceEmail"
          }
        },
        "defaultTemplateId": {
          "type": [
            "string",
            "null"
          ]
        },
        "sendOnWeekdays": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": [
              "Mon",
              "Tue",
              "Wed",
              "Thu",
              "Fri",
              "Sat",
              "Sun"
            ]
          }
        },
        "excludeAudienceDefinition": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceDefinition"
            },
            {
              "type": "null"
            }
          ]
        },
        "restartSequenceForCompletedSubscribers": {
          "type": "boolean"
        },
        "sendNewEmailsToCompletedSubscribers": {
          "type": "boolean"
        }
      },
      "example": {
        "emails": [
          {
            "id": "welcome",
            "subject": "Welcome",
            "previewText": "Thanks for joining",
            "bodyDocument": {
              "type": "doc",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Welcome to the newsletter."
                    }
                  ]
                }
              ]
            },
            "status": "Published",
            "delayValue": 0,
            "delayUnit": "day",
            "sendOnWeekdays": [
              "Mon",
              "Tue",
              "Wed",
              "Thu",
              "Fri"
            ],
            "audienceMode": "all",
            "audienceDefinition": null
          }
        ]
      },
      "examples": [
        {
          "emails": [
            {
              "id": "welcome",
              "subject": "Welcome",
              "previewText": "Thanks for joining",
              "bodyDocument": {
                "type": "doc",
                "content": [
                  {
                    "type": "paragraph",
                    "content": [
                      {
                        "type": "text",
                        "text": "Welcome to the newsletter."
                      }
                    ]
                  }
                ]
              },
              "status": "Published",
              "delayValue": 0,
              "delayUnit": "day",
              "sendOnWeekdays": [
                "Mon",
                "Tue",
                "Wed",
                "Thu",
                "Fri"
              ],
              "audienceMode": "all",
              "audienceDefinition": null
            }
          ]
        }
      ]
    },
    "SequenceEmail": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "subject",
        "previewText",
        "bodyDocument",
        "status",
        "delayValue",
        "delayUnit",
        "sendOnWeekdays"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "subject": {
          "type": "string",
          "description": "For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text."
        },
        "previewText": {
          "type": [
            "string",
            "null"
          ]
        },
        "bodyDocument": {
          "$ref": "#/$defs/BroadcastEmailDocument"
        },
        "status": {
          "type": "string",
          "enum": [
            "Draft",
            "Published"
          ]
        },
        "delayValue": {
          "type": "number",
          "minimum": 0
        },
        "delayUnit": {
          "type": "string",
          "enum": [
            "minute",
            "hour",
            "day"
          ]
        },
        "sendOnWeekdays": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": [
              "Mon",
              "Tue",
              "Wed",
              "Thu",
              "Fri",
              "Sat",
              "Sun"
            ]
          }
        },
        "audienceMode": {
          "type": "string",
          "enum": [
            "all",
            "include",
            "exclude"
          ]
        },
        "audienceDefinition": {
          "anyOf": [
            {
              "$ref": "#/$defs/AudienceDefinition"
            },
            {
              "type": "null"
            }
          ]
        },
        "stats": {
          "$ref": "#/$defs/EmailEngagementStats"
        }
      }
    },
    "BroadcastEmailDocument": {
      "allOf": [
        {
          "$ref": "#/$defs/BroadcastEmailNode"
        }
      ],
      "description": "A structured email document. The root node must use type `doc` and contain supported block nodes. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
                }
              ]
            }
          ]
        }
      ]
    },
    "BroadcastEmailNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "doc",
            "paragraph",
            "heading",
            "text",
            "hardBreak",
            "bulletList",
            "orderedList",
            "listItem",
            "blockquote",
            "emailSection",
            "emailSectionColumn",
            "emailButton",
            "image",
            "horizontalRule"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "textAlign": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ]
            },
            "columns": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "width": {
              "type": "string",
              "enum": [
                "default",
                "large",
                "full",
                "fit"
              ]
            },
            "backgroundColor": {
              "type": "string"
            },
            "blockquoteBorderColor": {
              "type": "string"
            },
            "linkColor": {
              "type": "string"
            },
            "layoutAlignment": {
              "type": "string",
              "enum": [
                "left",
                "center"
              ]
            },
            "backgroundImageUrl": {
              "type": "string"
            },
            "margin": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "padding": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderColor": {
              "type": "string"
            },
            "borderWidth": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderRadius": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "small",
                "large",
                "full"
              ]
            },
            "verticalAlign": {
              "type": "string",
              "enum": [
                "top",
                "middle",
                "bottom"
              ]
            },
            "href": {
              "type": "string"
            },
            "textColor": {
              "type": "string"
            },
            "size": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large"
              ]
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right"
              ]
            },
            "label": {
              "type": "string"
            },
            "src": {
              "type": "string"
            },
            "alt": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "caption": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "unsplash"
              ]
            },
            "unsplash": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photographerName"
              ],
              "properties": {
                "photoId": {
                  "type": "string"
                },
                "photographerName": {
                  "type": "string"
                },
                "photographerUsername": {
                  "type": "string"
                },
                "photographerUrl": {
                  "type": "string"
                },
                "unsplashUrl": {
                  "type": "string"
                }
              }
            },
            "widthPercent": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "crop": {
              "type": "string",
              "enum": [
                "none",
                "square",
                "circle"
              ]
            },
            "fillColumn": {
              "type": "boolean"
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailNode"
          }
        },
        "text": {
          "type": "string"
        },
        "marks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailMark"
          }
        }
      }
    },
    "BroadcastEmailMark": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bold",
            "italic",
            "strike",
            "underline",
            "link",
            "textStyle",
            "highlight"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "href": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "fontSize": {
              "type": "string"
            }
          }
        }
      }
    },
    "AudienceDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "match",
        "groups"
      ],
      "properties": {
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "groups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AudienceConditionGroup"
          }
        }
      },
      "example": {
        "match": "all",
        "groups": [
          {
            "id": "active-subscribers",
            "match": "all",
            "conditions": [
              {
                "id": "active-status",
                "field": "subscriber_status",
                "operator": "is",
                "value": [
                  "Active"
                ]
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "match": "all",
          "groups": [
            {
              "id": "active-subscribers",
              "match": "all",
              "conditions": [
                {
                  "id": "active-status",
                  "field": "subscriber_status",
                  "operator": "is",
                  "value": [
                    "Active"
                  ]
                }
              ]
            }
          ]
        }
      ]
    },
    "AudienceConditionGroup": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "match",
        "conditions"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "match": {
          "type": "string",
          "enum": [
            "all",
            "any"
          ]
        },
        "conditions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/AudienceCondition"
          }
        }
      }
    },
    "AudienceCondition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "field",
        "operator"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "enum": [
            "subscriber_status",
            "country",
            "segment",
            "tag",
            "sequence",
            "form",
            "custom_field",
            "email_opened",
            "email_unsubscribed",
            "magic_link_clicked"
          ]
        },
        "operator": {
          "type": "string",
          "enum": [
            "is",
            "is_not",
            "has_any_of",
            "has_none_of",
            "is_active_in_any_of",
            "is_not_active_in_any_of",
            "has_completed_any_of",
            "has_not_completed_any_of",
            "has_ever_been_in_any_of",
            "has_never_been_in_any_of",
            "contains",
            "does_not_contain",
            "is_empty",
            "is_not_empty",
            "before",
            "after",
            "on",
            "in_last_days",
            "greater_than",
            "less_than",
            "in_region",
            "not_in_region"
          ]
        },
        "value": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "customFieldId": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "EmailEngagementStats": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "recipientCount",
        "openedCount",
        "clickedCount",
        "unsubscribedCount"
      ],
      "properties": {
        "recipientCount": {
          "type": "integer",
          "minimum": 0
        },
        "engagedCount": {
          "type": "integer",
          "minimum": 0
        },
        "openedCount": {
          "type": "integer",
          "minimum": 0
        },
        "clickedCount": {
          "type": "integer",
          "minimum": 0
        },
        "clickedSubscriberCount": {
          "type": "integer",
          "minimum": 0
        },
        "unsubscribedCount": {
          "type": "integer",
          "minimum": 0
        },
        "bouncedCount": {
          "type": "integer",
          "minimum": 0
        },
        "complainedCount": {
          "type": "integer",
          "minimum": 0
        },
        "sentCountsByDay": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    }
  }
}

sequences_preflight

Checks the saved Sequence, its published emails, and its email delivery connection without changing data or sending email. Permission: sequences:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

sequence_id

string

required

The Sequence identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "sequence_id": {
      "type": "string",
      "description": "The Sequence identifier."
    }
  },
  "required": [
    "sequence_id"
  ],
  "additionalProperties": false
}

sequences_preview_journey

Returns the bounded saved email timeline and shows which messages a selected Subscriber is eligible to receive, without enrolling the Subscriber or sending email. Permissions: subscribers:read, sequences:read. API reference: https://mailrith.com/developers/api-reference.

Parameters2

sequence_id	string	required	The Sequence identifier.
subscriber_id	string	required	The saved Subscriber whose personalization and targeting should be previewed.

Raw schema

{
  "type": "object",
  "properties": {
    "sequence_id": {
      "type": "string",
      "description": "The Sequence identifier."
    },
    "subscriber_id": {
      "type": "string",
      "description": "The saved Subscriber whose personalization and targeting should be previewed."
    }
  },
  "required": [
    "sequence_id",
    "subscriber_id"
  ],
  "additionalProperties": false
}

sequences_send_test

Sends up to five selected saved Sequence emails to one explicit test address. This does not enroll a Subscriber, start the Sequence, or write delivery activity. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, subscribers:read, sequences:write. API reference: https://mailrith.com/developers/api-reference.

Parameters3

sequence_id	string	required	The Sequence identifier.
idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "sequence_id": {
      "type": "string",
      "description": "The Sequence identifier."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/WorkflowTestRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "sequence_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "WorkflowTestRequest": {
      "type": "object",
      "required": [
        "recipient",
        "subscriber_id"
      ],
      "additionalProperties": false,
      "properties": {
        "recipient": {
          "type": "string",
          "format": "email"
        },
        "subscriber_id": {
          "type": "string",
          "description": "The saved Subscriber whose personalization should be rendered in every test message."
        },
        "message_ids": {
          "type": "array",
          "maxItems": 5,
          "uniqueItems": true,
          "items": {
            "type": "string"
          },
          "description": "Optional Sequence email IDs or Automation step IDs. Omit to test the first five available messages."
        }
      }
    }
  }
}

sequences_update_status

Starts or pauses one Sequence without changing its content or delivery settings. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, sequences:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

sequence_id	string	required	The Sequence identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "sequence_id": {
      "type": "string",
      "description": "The Sequence identifier."
    },
    "body": {
      "$ref": "#/$defs/SequenceStatusRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "sequence_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "SequenceStatusRequest": {
      "type": "object",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "running",
            "paused"
          ]
        }
      }
    }
  }
}

automations_list

Returns automations in the authenticated workspace. Permission: automations:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters3

search	string	optional	Filter Automations by name or status.
limit	integer	optional	Maximum number of automations to return.
starting_after	string	optional	Use the opaque cursor from the previous page to request the next page.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200,
      "description": "Filter Automations by name or status."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum number of automations to return."
    },
    "starting_after": {
      "type": "string",
      "description": "Use the opaque cursor from the previous page to request the next page."
    }
  },
  "additionalProperties": false
}

automations_create

Creates an automation in the authenticated workspace. Effect: workspace-change. Retry with the same idempotency_key. Permission: automations:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/AutomationUpsertRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "AutomationUpsertRequest": {
      "type": "object",
      "required": [
        "name",
        "definition"
      ],
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "definition": {
          "$ref": "#/$defs/AutomationDefinition"
        }
      }
    },
    "AutomationDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "steps"
      ],
      "properties": {
        "version": {
          "type": "integer",
          "enum": [
            2
          ]
        },
        "trigger": {
          "anyOf": [
            {
              "$ref": "#/$defs/AutomationTrigger"
            },
            {
              "type": "null"
            }
          ]
        },
        "triggers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationTrigger"
          }
        },
        "entryPoints": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationEntryPoint"
          }
        },
        "steps": {
          "type": "array",
          "maxItems": 256,
          "items": {
            "$ref": "#/$defs/AutomationStep"
          }
        }
      },
      "example": {
        "version": 2,
        "trigger": {
          "type": "tag_added",
          "tagIds": [
            "tag_welcome"
          ]
        },
        "steps": [
          {
            "id": "send-welcome-email",
            "kind": "action",
            "type": "send_email",
            "config": {
              "subject": "Welcome",
              "previewText": "Thanks for joining",
              "bodyDocument": {
                "type": "doc",
                "content": [
                  {
                    "type": "paragraph",
                    "content": [
                      {
                        "type": "text",
                        "text": "Welcome to Mailrith."
                      }
                    ]
                  }
                ]
              },
              "replyToEmail": "",
              "trackOpens": true,
              "trackClicks": true,
              "utmSource": "",
              "utmMedium": "",
              "utmCampaign": "",
              "utmTerm": "",
              "utmContent": ""
            }
          }
        ]
      },
      "examples": [
        {
          "version": 2,
          "trigger": {
            "type": "tag_added",
            "tagIds": [
              "tag_welcome"
            ]
          },
          "steps": [
            {
              "id": "send-welcome-email",
              "kind": "action",
              "type": "send_email",
              "config": {
                "subject": "Welcome",
                "previewText": "Thanks for joining",
                "bodyDocument": {
                  "type": "doc",
                  "content": [
                    {
                      "type": "paragraph",
                      "content": [
                        {
                          "type": "text",
                          "text": "Welcome to Mailrith."
                        }
                      ]
                    }
                  ]
                },
                "replyToEmail": "",
                "trackOpens": true,
                "trackClicks": true,
                "utmSource": "",
                "utmMedium": "",
                "utmCampaign": "",
                "utmTerm": "",
                "utmContent": ""
              }
            }
          ]
        }
      ]
    },
    "AutomationTrigger": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "tag_added",
            "tag_removed",
            "magic_link_clicked",
            "subscriber_status"
          ]
        },
        "tagId": {
          "type": [
            "string",
            "null"
          ]
        },
        "tagIds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "magicLinkId": {
          "type": [
            "string",
            "null"
          ]
        },
        "magicLinkIds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "operator": {
          "type": "string",
          "enum": [
            "is",
            "is_not"
          ]
        },
        "statuses": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "Active",
              "Unconfirmed",
              "Unsubscribed",
              "Complained",
              "Bounced",
              "Blocked"
            ]
          }
        }
      }
    },
    "AutomationEntryPoint": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "trigger"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "trigger": {
          "$ref": "#/$defs/AutomationTrigger"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "AutomationStep": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "kind",
        "type"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "event",
            "action",
            "condition"
          ]
        },
        "type": {
          "type": "string",
          "enum": [
            "tag_added",
            "tag_removed",
            "magic_link_clicked",
            "sequence_completed",
            "add_tag",
            "remove_tag",
            "add_to_sequence",
            "remove_from_sequence",
            "change_subscriber_status",
            "wait",
            "update_custom_field",
            "send_email",
            "send_internal_notification",
            "start_automation",
            "remove_from_automation",
            "webhook",
            "end_automation",
            "has_tag",
            "custom_field_match",
            "sequence_membership",
            "subscriber_status",
            "email_opened",
            "email_clicked"
          ]
        },
        "config": {
          "$ref": "#/$defs/AutomationStepConfig"
        },
        "stats": {
          "$ref": "#/$defs/EmailEngagementStats"
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        },
        "nextStepId": {
          "type": [
            "string",
            "null"
          ]
        },
        "branches": {
          "type": "object",
          "additionalProperties": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "paths": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationPath"
          }
        }
      }
    },
    "AutomationStepConfig": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "tagId": {
          "type": "string"
        },
        "sequenceId": {
          "type": "string"
        },
        "magicLinkId": {
          "type": "string"
        },
        "customFieldId": {
          "type": "string"
        },
        "automationId": {
          "type": "string"
        },
        "emailId": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "statuses": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "operation": {
          "type": "string",
          "enum": [
            "set",
            "clear",
            "increment",
            "decrement",
            "set_today",
            "add_choices",
            "remove_choices",
            "set_true",
            "set_false",
            "toggle"
          ]
        },
        "operator": {
          "type": "string",
          "enum": [
            "equals",
            "not_equals",
            "contains",
            "not_contains",
            "starts_with",
            "ends_with",
            "exists",
            "missing",
            "greater_than",
            "greater_than_or_equal",
            "less_than",
            "less_than_or_equal",
            "on",
            "not_on",
            "before",
            "on_or_before",
            "after",
            "on_or_after",
            "contains_any",
            "contains_all",
            "does_not_contain_any",
            "is_checked",
            "is_not_checked"
          ]
        },
        "value": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "mode": {
          "type": "string",
          "enum": [
            "duration",
            "until_custom_date",
            "until_custom_field_date"
          ]
        },
        "waitMode": {
          "type": "string",
          "enum": [
            "duration",
            "custom_date"
          ]
        },
        "dateSource": {
          "type": "string",
          "enum": [
            "custom_field",
            "fixed_date"
          ]
        },
        "date": {
          "type": "string",
          "format": "date"
        },
        "timeOfDay": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
        },
        "durationValue": {
          "type": "number",
          "minimum": 0
        },
        "durationUnit": {
          "type": "string",
          "enum": [
            "minute",
            "hour",
            "day",
            "week"
          ]
        },
        "waitForCompletion": {
          "type": "boolean"
        },
        "waitUntilComplete": {
          "type": "boolean"
        },
        "exitNextStepId": {
          "type": [
            "string",
            "null"
          ]
        },
        "lookbackDays": {
          "type": "integer",
          "minimum": 1
        },
        "recipientEmail": {
          "type": "string",
          "format": "email"
        },
        "subject": {
          "type": "string",
          "description": "For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text."
        },
        "previewText": {
          "type": "string"
        },
        "bodyDocument": {
          "$ref": "#/$defs/BroadcastEmailDocument"
        },
        "replyToEmail": {
          "type": "string"
        },
        "trackOpens": {
          "type": "boolean"
        },
        "trackClicks": {
          "type": "boolean"
        },
        "utmSource": {
          "type": "string"
        },
        "utmMedium": {
          "type": "string"
        },
        "utmCampaign": {
          "type": "string"
        },
        "utmTerm": {
          "type": "string"
        },
        "utmContent": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "method": {
          "type": "string",
          "enum": [
            "POST",
            "PUT",
            "PATCH"
          ]
        },
        "authType": {
          "type": "string",
          "enum": [
            "none",
            "bearer"
          ]
        },
        "bearerToken": {
          "type": "string",
          "writeOnly": true
        },
        "bearerTokenConfigured": {
          "type": "boolean",
          "description": "True when Mailrith has a saved webhook bearer token. Send this unchanged during an update to preserve the saved value. The token value is never returned."
        },
        "headers": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "key"
            ],
            "properties": {
              "key": {
                "type": "string"
              },
              "value": {
                "type": "string",
                "writeOnly": true,
                "description": "A secret header value accepted on writes and never returned."
              },
              "configured": {
                "type": "boolean",
                "description": "True when Mailrith has a saved value for this header. Send this unchanged during an update to preserve the saved value."
              }
            }
          }
        },
        "includeSubscriber": {
          "type": "boolean"
        },
        "includeTags": {
          "type": "boolean"
        },
        "includeCustomFields": {
          "type": "boolean"
        }
      }
    },
    "BroadcastEmailDocument": {
      "allOf": [
        {
          "$ref": "#/$defs/BroadcastEmailNode"
        }
      ],
      "description": "A structured email document. The root node must use type `doc` and contain supported block nodes. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
                }
              ]
            }
          ]
        }
      ]
    },
    "BroadcastEmailNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "doc",
            "paragraph",
            "heading",
            "text",
            "hardBreak",
            "bulletList",
            "orderedList",
            "listItem",
            "blockquote",
            "emailSection",
            "emailSectionColumn",
            "emailButton",
            "image",
            "horizontalRule"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "textAlign": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ]
            },
            "columns": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "width": {
              "type": "string",
              "enum": [
                "default",
                "large",
                "full",
                "fit"
              ]
            },
            "backgroundColor": {
              "type": "string"
            },
            "blockquoteBorderColor": {
              "type": "string"
            },
            "linkColor": {
              "type": "string"
            },
            "layoutAlignment": {
              "type": "string",
              "enum": [
                "left",
                "center"
              ]
            },
            "backgroundImageUrl": {
              "type": "string"
            },
            "margin": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "padding": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderColor": {
              "type": "string"
            },
            "borderWidth": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderRadius": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "small",
                "large",
                "full"
              ]
            },
            "verticalAlign": {
              "type": "string",
              "enum": [
                "top",
                "middle",
                "bottom"
              ]
            },
            "href": {
              "type": "string"
            },
            "textColor": {
              "type": "string"
            },
            "size": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large"
              ]
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right"
              ]
            },
            "label": {
              "type": "string"
            },
            "src": {
              "type": "string"
            },
            "alt": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "caption": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "unsplash"
              ]
            },
            "unsplash": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photographerName"
              ],
              "properties": {
                "photoId": {
                  "type": "string"
                },
                "photographerName": {
                  "type": "string"
                },
                "photographerUsername": {
                  "type": "string"
                },
                "photographerUrl": {
                  "type": "string"
                },
                "unsplashUrl": {
                  "type": "string"
                }
              }
            },
            "widthPercent": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "crop": {
              "type": "string",
              "enum": [
                "none",
                "square",
                "circle"
              ]
            },
            "fillColumn": {
              "type": "boolean"
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailNode"
          }
        },
        "text": {
          "type": "string"
        },
        "marks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailMark"
          }
        }
      }
    },
    "BroadcastEmailMark": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bold",
            "italic",
            "strike",
            "underline",
            "link",
            "textStyle",
            "highlight"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "href": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "fontSize": {
              "type": "string"
            }
          }
        }
      }
    },
    "EmailEngagementStats": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "recipientCount",
        "openedCount",
        "clickedCount",
        "unsubscribedCount"
      ],
      "properties": {
        "recipientCount": {
          "type": "integer",
          "minimum": 0
        },
        "engagedCount": {
          "type": "integer",
          "minimum": 0
        },
        "openedCount": {
          "type": "integer",
          "minimum": 0
        },
        "clickedCount": {
          "type": "integer",
          "minimum": 0
        },
        "clickedSubscriberCount": {
          "type": "integer",
          "minimum": 0
        },
        "unsubscribedCount": {
          "type": "integer",
          "minimum": 0
        },
        "bouncedCount": {
          "type": "integer",
          "minimum": 0
        },
        "complainedCount": {
          "type": "integer",
          "minimum": 0
        },
        "sentCountsByDay": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    },
    "AutomationPath": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "label"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "nextStepId": {
          "type": [
            "string",
            "null"
          ]
        },
        "weight": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    }
  }
}

automations_get

Returns one automation from the authenticated workspace. Permission: automations:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

automation_id

string

required

The automation identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "automation_id": {
      "type": "string",
      "description": "The automation identifier."
    }
  },
  "required": [
    "automation_id"
  ],
  "additionalProperties": false
}

automations_update

Updates an existing draft or paused Automation. Before changing a running Automation, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Automation, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate an Automation that was not already running. Effect: workspace-change. Retry after reading the current resource state. Permission: automations:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

automation_id	string	required	The automation identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "automation_id": {
      "type": "string",
      "description": "The automation identifier."
    },
    "body": {
      "$ref": "#/$defs/AutomationUpdateRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "automation_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "AutomationUpdateRequest": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": false,
      "properties": {
        "name": {
          "type": "string"
        },
        "definition": {
          "$ref": "#/$defs/AutomationDefinition"
        }
      }
    },
    "AutomationDefinition": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "steps"
      ],
      "properties": {
        "version": {
          "type": "integer",
          "enum": [
            2
          ]
        },
        "trigger": {
          "anyOf": [
            {
              "$ref": "#/$defs/AutomationTrigger"
            },
            {
              "type": "null"
            }
          ]
        },
        "triggers": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationTrigger"
          }
        },
        "entryPoints": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationEntryPoint"
          }
        },
        "steps": {
          "type": "array",
          "maxItems": 256,
          "items": {
            "$ref": "#/$defs/AutomationStep"
          }
        }
      },
      "example": {
        "version": 2,
        "trigger": {
          "type": "tag_added",
          "tagIds": [
            "tag_welcome"
          ]
        },
        "steps": [
          {
            "id": "send-welcome-email",
            "kind": "action",
            "type": "send_email",
            "config": {
              "subject": "Welcome",
              "previewText": "Thanks for joining",
              "bodyDocument": {
                "type": "doc",
                "content": [
                  {
                    "type": "paragraph",
                    "content": [
                      {
                        "type": "text",
                        "text": "Welcome to Mailrith."
                      }
                    ]
                  }
                ]
              },
              "replyToEmail": "",
              "trackOpens": true,
              "trackClicks": true,
              "utmSource": "",
              "utmMedium": "",
              "utmCampaign": "",
              "utmTerm": "",
              "utmContent": ""
            }
          }
        ]
      },
      "examples": [
        {
          "version": 2,
          "trigger": {
            "type": "tag_added",
            "tagIds": [
              "tag_welcome"
            ]
          },
          "steps": [
            {
              "id": "send-welcome-email",
              "kind": "action",
              "type": "send_email",
              "config": {
                "subject": "Welcome",
                "previewText": "Thanks for joining",
                "bodyDocument": {
                  "type": "doc",
                  "content": [
                    {
                      "type": "paragraph",
                      "content": [
                        {
                          "type": "text",
                          "text": "Welcome to Mailrith."
                        }
                      ]
                    }
                  ]
                },
                "replyToEmail": "",
                "trackOpens": true,
                "trackClicks": true,
                "utmSource": "",
                "utmMedium": "",
                "utmCampaign": "",
                "utmTerm": "",
                "utmContent": ""
              }
            }
          ]
        }
      ]
    },
    "AutomationTrigger": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "tag_added",
            "tag_removed",
            "magic_link_clicked",
            "subscriber_status"
          ]
        },
        "tagId": {
          "type": [
            "string",
            "null"
          ]
        },
        "tagIds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "magicLinkId": {
          "type": [
            "string",
            "null"
          ]
        },
        "magicLinkIds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "operator": {
          "type": "string",
          "enum": [
            "is",
            "is_not"
          ]
        },
        "statuses": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "Active",
              "Unconfirmed",
              "Unsubscribed",
              "Complained",
              "Bounced",
              "Blocked"
            ]
          }
        }
      }
    },
    "AutomationEntryPoint": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "trigger"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "trigger": {
          "$ref": "#/$defs/AutomationTrigger"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "AutomationStep": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "kind",
        "type"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "event",
            "action",
            "condition"
          ]
        },
        "type": {
          "type": "string",
          "enum": [
            "tag_added",
            "tag_removed",
            "magic_link_clicked",
            "sequence_completed",
            "add_tag",
            "remove_tag",
            "add_to_sequence",
            "remove_from_sequence",
            "change_subscriber_status",
            "wait",
            "update_custom_field",
            "send_email",
            "send_internal_notification",
            "start_automation",
            "remove_from_automation",
            "webhook",
            "end_automation",
            "has_tag",
            "custom_field_match",
            "sequence_membership",
            "subscriber_status",
            "email_opened",
            "email_clicked"
          ]
        },
        "config": {
          "$ref": "#/$defs/AutomationStepConfig"
        },
        "stats": {
          "$ref": "#/$defs/EmailEngagementStats"
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        },
        "nextStepId": {
          "type": [
            "string",
            "null"
          ]
        },
        "branches": {
          "type": "object",
          "additionalProperties": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "paths": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AutomationPath"
          }
        }
      }
    },
    "AutomationStepConfig": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "tagId": {
          "type": "string"
        },
        "sequenceId": {
          "type": "string"
        },
        "magicLinkId": {
          "type": "string"
        },
        "customFieldId": {
          "type": "string"
        },
        "automationId": {
          "type": "string"
        },
        "emailId": {
          "type": "string"
        },
        "status": {
          "type": "string"
        },
        "statuses": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "operation": {
          "type": "string",
          "enum": [
            "set",
            "clear",
            "increment",
            "decrement",
            "set_today",
            "add_choices",
            "remove_choices",
            "set_true",
            "set_false",
            "toggle"
          ]
        },
        "operator": {
          "type": "string",
          "enum": [
            "equals",
            "not_equals",
            "contains",
            "not_contains",
            "starts_with",
            "ends_with",
            "exists",
            "missing",
            "greater_than",
            "greater_than_or_equal",
            "less_than",
            "less_than_or_equal",
            "on",
            "not_on",
            "before",
            "on_or_before",
            "after",
            "on_or_after",
            "contains_any",
            "contains_all",
            "does_not_contain_any",
            "is_checked",
            "is_not_checked"
          ]
        },
        "value": {
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ]
        },
        "mode": {
          "type": "string",
          "enum": [
            "duration",
            "until_custom_date",
            "until_custom_field_date"
          ]
        },
        "waitMode": {
          "type": "string",
          "enum": [
            "duration",
            "custom_date"
          ]
        },
        "dateSource": {
          "type": "string",
          "enum": [
            "custom_field",
            "fixed_date"
          ]
        },
        "date": {
          "type": "string",
          "format": "date"
        },
        "timeOfDay": {
          "type": "string",
          "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
        },
        "durationValue": {
          "type": "number",
          "minimum": 0
        },
        "durationUnit": {
          "type": "string",
          "enum": [
            "minute",
            "hour",
            "day",
            "week"
          ]
        },
        "waitForCompletion": {
          "type": "boolean"
        },
        "waitUntilComplete": {
          "type": "boolean"
        },
        "exitNextStepId": {
          "type": [
            "string",
            "null"
          ]
        },
        "lookbackDays": {
          "type": "integer",
          "minimum": 1
        },
        "recipientEmail": {
          "type": "string",
          "format": "email"
        },
        "subject": {
          "type": "string",
          "description": "For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text."
        },
        "previewText": {
          "type": "string"
        },
        "bodyDocument": {
          "$ref": "#/$defs/BroadcastEmailDocument"
        },
        "replyToEmail": {
          "type": "string"
        },
        "trackOpens": {
          "type": "boolean"
        },
        "trackClicks": {
          "type": "boolean"
        },
        "utmSource": {
          "type": "string"
        },
        "utmMedium": {
          "type": "string"
        },
        "utmCampaign": {
          "type": "string"
        },
        "utmTerm": {
          "type": "string"
        },
        "utmContent": {
          "type": "string"
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "method": {
          "type": "string",
          "enum": [
            "POST",
            "PUT",
            "PATCH"
          ]
        },
        "authType": {
          "type": "string",
          "enum": [
            "none",
            "bearer"
          ]
        },
        "bearerToken": {
          "type": "string",
          "writeOnly": true
        },
        "bearerTokenConfigured": {
          "type": "boolean",
          "description": "True when Mailrith has a saved webhook bearer token. Send this unchanged during an update to preserve the saved value. The token value is never returned."
        },
        "headers": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "key"
            ],
            "properties": {
              "key": {
                "type": "string"
              },
              "value": {
                "type": "string",
                "writeOnly": true,
                "description": "A secret header value accepted on writes and never returned."
              },
              "configured": {
                "type": "boolean",
                "description": "True when Mailrith has a saved value for this header. Send this unchanged during an update to preserve the saved value."
              }
            }
          }
        },
        "includeSubscriber": {
          "type": "boolean"
        },
        "includeTags": {
          "type": "boolean"
        },
        "includeCustomFields": {
          "type": "boolean"
        }
      }
    },
    "BroadcastEmailDocument": {
      "allOf": [
        {
          "$ref": "#/$defs/BroadcastEmailNode"
        }
      ],
      "description": "A structured email document. The root node must use type `doc` and contain supported block nodes. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
                }
              ]
            }
          ]
        }
      ]
    },
    "BroadcastEmailNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "doc",
            "paragraph",
            "heading",
            "text",
            "hardBreak",
            "bulletList",
            "orderedList",
            "listItem",
            "blockquote",
            "emailSection",
            "emailSectionColumn",
            "emailButton",
            "image",
            "horizontalRule"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "textAlign": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ]
            },
            "columns": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "width": {
              "type": "string",
              "enum": [
                "default",
                "large",
                "full",
                "fit"
              ]
            },
            "backgroundColor": {
              "type": "string"
            },
            "blockquoteBorderColor": {
              "type": "string"
            },
            "linkColor": {
              "type": "string"
            },
            "layoutAlignment": {
              "type": "string",
              "enum": [
                "left",
                "center"
              ]
            },
            "backgroundImageUrl": {
              "type": "string"
            },
            "margin": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "padding": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderColor": {
              "type": "string"
            },
            "borderWidth": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderRadius": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "small",
                "large",
                "full"
              ]
            },
            "verticalAlign": {
              "type": "string",
              "enum": [
                "top",
                "middle",
                "bottom"
              ]
            },
            "href": {
              "type": "string"
            },
            "textColor": {
              "type": "string"
            },
            "size": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large"
              ]
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right"
              ]
            },
            "label": {
              "type": "string"
            },
            "src": {
              "type": "string"
            },
            "alt": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "caption": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "unsplash"
              ]
            },
            "unsplash": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photographerName"
              ],
              "properties": {
                "photoId": {
                  "type": "string"
                },
                "photographerName": {
                  "type": "string"
                },
                "photographerUsername": {
                  "type": "string"
                },
                "photographerUrl": {
                  "type": "string"
                },
                "unsplashUrl": {
                  "type": "string"
                }
              }
            },
            "widthPercent": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "crop": {
              "type": "string",
              "enum": [
                "none",
                "square",
                "circle"
              ]
            },
            "fillColumn": {
              "type": "boolean"
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailNode"
          }
        },
        "text": {
          "type": "string"
        },
        "marks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailMark"
          }
        }
      }
    },
    "BroadcastEmailMark": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bold",
            "italic",
            "strike",
            "underline",
            "link",
            "textStyle",
            "highlight"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "href": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "fontSize": {
              "type": "string"
            }
          }
        }
      }
    },
    "EmailEngagementStats": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "recipientCount",
        "openedCount",
        "clickedCount",
        "unsubscribedCount"
      ],
      "properties": {
        "recipientCount": {
          "type": "integer",
          "minimum": 0
        },
        "engagedCount": {
          "type": "integer",
          "minimum": 0
        },
        "openedCount": {
          "type": "integer",
          "minimum": 0
        },
        "clickedCount": {
          "type": "integer",
          "minimum": 0
        },
        "clickedSubscriberCount": {
          "type": "integer",
          "minimum": 0
        },
        "unsubscribedCount": {
          "type": "integer",
          "minimum": 0
        },
        "bouncedCount": {
          "type": "integer",
          "minimum": 0
        },
        "complainedCount": {
          "type": "integer",
          "minimum": 0
        },
        "sentCountsByDay": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    },
    "AutomationPath": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "label"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "label": {
          "type": "string"
        },
        "nextStepId": {
          "type": [
            "string",
            "null"
          ]
        },
        "weight": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    }
  }
}

automations_preflight

Checks the saved Automation definition and email delivery prerequisite without running any action. Permission: automations:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

automation_id

string

required

The Automation identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "automation_id": {
      "type": "string",
      "description": "The Automation identifier."
    }
  },
  "required": [
    "automation_id"
  ],
  "additionalProperties": false
}

automations_preview_journey

Shows the bounded path a selected Subscriber would take through the current saved conditions without running actions or writing history. Permissions: subscribers:read, automations:read. API reference: https://mailrith.com/developers/api-reference.

Parameters2

automation_id	string	required	The Automation identifier.
subscriber_id	string	required	The saved Subscriber whose current state should be evaluated.

Raw schema

{
  "type": "object",
  "properties": {
    "automation_id": {
      "type": "string",
      "description": "The Automation identifier."
    },
    "subscriber_id": {
      "type": "string",
      "description": "The saved Subscriber whose current state should be evaluated."
    }
  },
  "required": [
    "automation_id",
    "subscriber_id"
  ],
  "additionalProperties": false
}

automations_send_test

Sends up to five selected saved Automation email steps to one explicit test address. This does not start the Automation or run other actions. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, subscribers:read, automations:write. API reference: https://mailrith.com/developers/api-reference.

Parameters3

automation_id	string	required	The Automation identifier.
idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "automation_id": {
      "type": "string",
      "description": "The Automation identifier."
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/WorkflowTestRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "automation_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "WorkflowTestRequest": {
      "type": "object",
      "required": [
        "recipient",
        "subscriber_id"
      ],
      "additionalProperties": false,
      "properties": {
        "recipient": {
          "type": "string",
          "format": "email"
        },
        "subscriber_id": {
          "type": "string",
          "description": "The saved Subscriber whose personalization should be rendered in every test message."
        },
        "message_ids": {
          "type": "array",
          "maxItems": 5,
          "uniqueItems": true,
          "items": {
            "type": "string"
          },
          "description": "Optional Sequence email IDs or Automation step IDs. Omit to test the first five available messages."
        }
      }
    }
  }
}

automations_update_status

Starts, pauses, or returns one Automation to draft without changing its definition. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, automations:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

automation_id	string	required	The Automation identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "automation_id": {
      "type": "string",
      "description": "The Automation identifier."
    },
    "body": {
      "$ref": "#/$defs/AutomationStatusRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "automation_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "AutomationStatusRequest": {
      "type": "object",
      "required": [
        "status"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "draft",
            "running",
            "paused"
          ]
        }
      }
    }
  }
}

email_templates_list

Returns reusable email templates linked to the authenticated workspace. Permission: email_templates:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.

Parameters3

search	string	optional	Filter email templates by name.
limit	integer	optional	Maximum number of items to return.
starting_after	string	optional	Opaque cursor returned by the previous page.

Raw schema

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "maxLength": 200,
      "description": "Filter email templates by name."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum number of items to return."
    },
    "starting_after": {
      "type": "string",
      "description": "Opaque cursor returned by the previous page."
    }
  },
  "additionalProperties": false
}

email_templates_create

Creates a reusable email template scoped to the authenticated workspace. Effect: workspace-change. Retry with the same idempotency_key. Permission: email_templates:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

idempotency_key	string	optional	Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "maxLength": 256,
      "description": "Optional idempotency key to retry the request safely. It must not exceed 256 UTF-8 bytes."
    },
    "body": {
      "$ref": "#/$defs/EmailTemplateUpsertRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "EmailTemplateUpsertRequest": {
      "type": "object",
      "required": [
        "name"
      ],
      "anyOf": [
        {
          "required": [
            "body_document"
          ]
        },
        {
          "required": [
            "starting_point_id"
          ]
        }
      ],
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 160
        },
        "body_document": {
          "description": "Structured email editor content. The serialized document must be 512000 bytes or less. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
          "allOf": [
            {
              "$ref": "#/$defs/BroadcastEmailDocument"
            }
          ]
        },
        "starting_point_id": {
          "type": "string",
          "description": "Creates the email template from this canonical starting point. Do not also provide body_document."
        },
        "enabled": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "BroadcastEmailDocument": {
      "allOf": [
        {
          "$ref": "#/$defs/BroadcastEmailNode"
        }
      ],
      "description": "A structured email document. The root node must use type `doc` and contain supported block nodes. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
                }
              ]
            }
          ]
        }
      ]
    },
    "BroadcastEmailNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "doc",
            "paragraph",
            "heading",
            "text",
            "hardBreak",
            "bulletList",
            "orderedList",
            "listItem",
            "blockquote",
            "emailSection",
            "emailSectionColumn",
            "emailButton",
            "image",
            "horizontalRule"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "textAlign": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ]
            },
            "columns": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "width": {
              "type": "string",
              "enum": [
                "default",
                "large",
                "full",
                "fit"
              ]
            },
            "backgroundColor": {
              "type": "string"
            },
            "blockquoteBorderColor": {
              "type": "string"
            },
            "linkColor": {
              "type": "string"
            },
            "layoutAlignment": {
              "type": "string",
              "enum": [
                "left",
                "center"
              ]
            },
            "backgroundImageUrl": {
              "type": "string"
            },
            "margin": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "padding": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderColor": {
              "type": "string"
            },
            "borderWidth": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderRadius": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "small",
                "large",
                "full"
              ]
            },
            "verticalAlign": {
              "type": "string",
              "enum": [
                "top",
                "middle",
                "bottom"
              ]
            },
            "href": {
              "type": "string"
            },
            "textColor": {
              "type": "string"
            },
            "size": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large"
              ]
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right"
              ]
            },
            "label": {
              "type": "string"
            },
            "src": {
              "type": "string"
            },
            "alt": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "caption": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "unsplash"
              ]
            },
            "unsplash": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photographerName"
              ],
              "properties": {
                "photoId": {
                  "type": "string"
                },
                "photographerName": {
                  "type": "string"
                },
                "photographerUsername": {
                  "type": "string"
                },
                "photographerUrl": {
                  "type": "string"
                },
                "unsplashUrl": {
                  "type": "string"
                }
              }
            },
            "widthPercent": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "crop": {
              "type": "string",
              "enum": [
                "none",
                "square",
                "circle"
              ]
            },
            "fillColumn": {
              "type": "boolean"
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailNode"
          }
        },
        "text": {
          "type": "string"
        },
        "marks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailMark"
          }
        }
      }
    },
    "BroadcastEmailMark": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bold",
            "italic",
            "strike",
            "underline",
            "link",
            "textStyle",
            "highlight"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "href": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "fontSize": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

email_templates_get

Returns a reusable email template linked to the authenticated workspace. Permission: email_templates:read. API reference: https://mailrith.com/developers/api-reference.

Parameters1

template_id

string

required

The email template identifier.

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "The email template identifier."
    }
  },
  "required": [
    "template_id"
  ],
  "additionalProperties": false
}

email_templates_preview

Renders one template using a saved Subscriber's name, email, and custom fields without sending or saving anything. Permissions: subscribers:read, email_templates:read. API reference: https://mailrith.com/developers/api-reference.

Parameters2

template_id	string	required	The email template identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "The email template identifier."
    },
    "body": {
      "$ref": "#/$defs/SubscriberPreviewRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "template_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "SubscriberPreviewRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "subscriber_id"
      ],
      "properties": {
        "subscriber_id": {
          "type": "string",
          "description": "The saved Subscriber whose name, email, and custom fields should be used for personalization."
        }
      }
    }
  }
}

email_templates_update

Updates the content or enabled state of an existing email template. Effect: workspace-change. Retry after reading the current resource state. Permission: email_templates:write. API reference: https://mailrith.com/developers/api-reference.

Parameters2

template_id	string	required	The email template identifier.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "description": "The email template identifier."
    },
    "body": {
      "$ref": "#/$defs/EmailTemplateUpdateRequest",
      "type": "object",
      "description": "The exact JSON request body defined by the Mailrith public API contract."
    }
  },
  "required": [
    "template_id",
    "body"
  ],
  "additionalProperties": false,
  "$defs": {
    "EmailTemplateUpdateRequest": {
      "type": "object",
      "minProperties": 1,
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 160
        },
        "body_document": {
          "description": "Structured email editor content. The serialized document must be 512000 bytes or less. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
          "allOf": [
            {
              "$ref": "#/$defs/BroadcastEmailDocument"
            }
          ]
        },
        "enabled": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "BroadcastEmailDocument": {
      "allOf": [
        {
          "$ref": "#/$defs/BroadcastEmailNode"
        }
      ],
      "description": "A structured email document. The root node must use type `doc` and contain supported block nodes. For Subscriber personalization in email subjects and body text nodes, use Mailrith bracket tokens such as [Subscriber_Name, fallback=\"friend\"] or [Subscriber_Email, fallback=\"\"]. Before using a custom field, call custom_fields_list or custom_fields_get and copy its personalization_token exactly. Do not use Handlebars-style variables such as {{ subscriber.name }}; Mailrith sends them as literal text.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello [Subscriber_Name, fallback=\"friend\"]."
                }
              ]
            }
          ]
        }
      ]
    },
    "BroadcastEmailNode": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "doc",
            "paragraph",
            "heading",
            "text",
            "hardBreak",
            "bulletList",
            "orderedList",
            "listItem",
            "blockquote",
            "emailSection",
            "emailSectionColumn",
            "emailButton",
            "image",
            "horizontalRule"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "level": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "textAlign": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right",
                "justify"
              ]
            },
            "columns": {
              "type": "integer",
              "enum": [
                1,
                2,
                3
              ]
            },
            "width": {
              "type": "string",
              "enum": [
                "default",
                "large",
                "full",
                "fit"
              ]
            },
            "backgroundColor": {
              "type": "string"
            },
            "blockquoteBorderColor": {
              "type": "string"
            },
            "linkColor": {
              "type": "string"
            },
            "layoutAlignment": {
              "type": "string",
              "enum": [
                "left",
                "center"
              ]
            },
            "backgroundImageUrl": {
              "type": "string"
            },
            "margin": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "padding": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderColor": {
              "type": "string"
            },
            "borderWidth": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "large"
              ]
            },
            "borderRadius": {
              "type": "string",
              "enum": [
                "none",
                "normal",
                "small",
                "large",
                "full"
              ]
            },
            "verticalAlign": {
              "type": "string",
              "enum": [
                "top",
                "middle",
                "bottom"
              ]
            },
            "href": {
              "type": "string"
            },
            "textColor": {
              "type": "string"
            },
            "size": {
              "type": "string",
              "enum": [
                "small",
                "medium",
                "large"
              ]
            },
            "align": {
              "type": "string",
              "enum": [
                "left",
                "center",
                "right"
              ]
            },
            "label": {
              "type": "string"
            },
            "src": {
              "type": "string"
            },
            "alt": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "caption": {
              "type": "string"
            },
            "source": {
              "type": "string",
              "enum": [
                "unsplash"
              ]
            },
            "unsplash": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "photographerName"
              ],
              "properties": {
                "photoId": {
                  "type": "string"
                },
                "photographerName": {
                  "type": "string"
                },
                "photographerUsername": {
                  "type": "string"
                },
                "photographerUrl": {
                  "type": "string"
                },
                "unsplashUrl": {
                  "type": "string"
                }
              }
            },
            "widthPercent": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "crop": {
              "type": "string",
              "enum": [
                "none",
                "square",
                "circle"
              ]
            },
            "fillColumn": {
              "type": "boolean"
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailNode"
          }
        },
        "text": {
          "type": "string"
        },
        "marks": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/BroadcastEmailMark"
          }
        }
      }
    },
    "BroadcastEmailMark": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "bold",
            "italic",
            "strike",
            "underline",
            "link",
            "textStyle",
            "highlight"
          ]
        },
        "attrs": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "href": {
              "type": "string"
            },
            "color": {
              "type": "string"
            },
            "fontSize": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

packages/mcp-server/README.md5 KBView on GitHub

Mailrith MCP Server

Official MCP server for Mailrith.

The server uses the stable @modelcontextprotocol/sdk package for hosted and stdio transports while preserving Mailrith's generated operation schemas.

Use the remote MCP endpoint at https://api.mailrith.com/mcp for hosted agent integrations, or run the local server from this repo for stdio or self-hosted HTTP use. Claude Desktop and other user-connected remote MCP clients authenticate through Mailrith OAuth. Code-first clients that can safely store credentials may send a workspace API key or OAuth access token as Authorization: Bearer <credential>.

Official MCP Registry

The registry metadata in server.json identifies the server as com.mailrith/mailrith. Clients can use the canonical Streamable HTTP endpoint at https://api.mailrith.com/mcp, which authenticates through OAuth, or install the local stdio package from npm. Local installs require a workspace API key in MAILRITH_API_KEY.

The hosted server requests Full Email Marketing Access by default for a general-purpose agent. It covers every public email-marketing operation in the selected workspace, but not billing, team, account-security, credential-reading, or internal administration. The discovery_get_capabilities connection check requests the complete public permission catalog so Mailrith can show every Work Profile and default to Full Email Marketing Access. The user can choose Reporting, another focused Work Profile, or custom permissions instead. OAuth stores only the permissions the user approves, and every tool checks those permissions again when it runs.

bash

MAILRITH_API_KEY="<secret>" pnpm --filter @mailrith/mcp-server exec tsx src/cli.ts --transport stdio

Local stdio reads MAILRITH_API_KEY from the client secret environment. The server rejects credentials passed as command arguments so they do not appear in process listings or shell history. Local stdio stops with a clear setup error when the environment variable is missing because it has no browser-based OAuth flow.

Self-hosted HTTP does not read a process-wide API key. Each client must send its own workspace API key or OAuth access token in the Authorization header. The built-in HTTP listener accepts only 127.0.0.1 or localhost; put a TLS reverse proxy in front of it when another machine needs access.

The default submitted profile exposes a fixed reviewed catalog of focused tools such as:

subscribers_list
broadcasts_create
broadcasts_preflight
broadcasts_schedule
broadcasts_send
sequences_update_status
automations_update_status

Every submitted tool has a human-readable top-level title and annotations.title, a narrow description, exact input and output schemas, explicit safety annotations, and machine-readable operation permissions. Request-body inputs expose their JSON type directly as well as their exact referenced schema so connector review tools can validate them without expanding $ref values first. Tools other than the connection check advertise their exact OAuth permissions. The connection check advertises the complete permission catalog so OAuth can offer every Work Profile; its result still reports the exact permissions granted to the connection. The catalog stays the same for every user so clients can review and select tools reliably. Workspace role, plan, product readiness, and granted permissions are enforced when a tool runs.

Anonymous clients may initialize and list this static catalog so ChatGPT and other hosts can start OAuth linking. Anonymous tool calls never reach the Mailrith product API and return HTTP 401 with a standards-based WWW-Authenticate challenge instead. Authenticated calls that need more permissions return HTTP 403 with the complete replacement permission set. Single-tool responses also include MCP's tool-level OAuth challenge metadata for clients that use it when linking or reconnecting an account. Each anonymous HTTP request accepts one JSON-RPC message. Authenticated requests may batch up to 25 messages. These limits keep discovery and tool responses predictable for every connected workspace.

Automation reads never return saved webhook bearer tokens or custom header values. They return only whether each value is configured. If a client reads an Automation and sends the redacted definition back during an update, Mailrith preserves the existing values unless the client explicitly replaces or removes them. Changing the webhook destination requires new credential values so an old secret cannot be carried to another service.

The package also preserves two explicit compatibility profiles:

compact exposes the earlier seven discovery and routing tools.
custom exposes generated focused tools with caller-selected Work Profile, permission, and read-only filters.

Use these profiles only for local or purpose-built clients. Public ChatGPT, Codex, Claude, and Cursor packages use the fixed submitted profile at the single /mcp endpoint.

Official Builds And Forks

Modified public versions must use distinct package, registry, plugin, and service names and clearly say that they are unofficial. See the Mailrith Trademark And Unofficial Fork Policy.

Install

Tools (55)

discovery_get_capabilitiesworkspace_getsender_identities_listsender_identities_getanalytics_create_reportanalytics_get_reportsubscribers_listsubscribers_get

Configuration

Environment variables

MAILRITH_API_KEYrequiredsecret

A Mailrith workspace API key.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mailrith": {
      "command": "npx",
      "args": [
        "-y",
        "@mailrith/mcp-server@1.1.1"
      ],
      "env": {
        "MAILRITH_API_KEY": "<YOUR_MAILRITH_API_KEY>"
      }
    }
  }
}

com.mailrith/mailrith MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

discovery_get_capabilities

workspace_get

sender_identities_list

sender_identities_get

analytics_create_report

analytics_get_report

subscribers_list

subscribers_get

subscribers_upsert

subscribers_update

subscribers_update_status

subscribers_add_tag

subscribers_remove_tag

subscribers_add_to_sequence

subscribers_remove_from_sequence

tags_list

tags_get

tags_create

custom_fields_list

custom_fields_get

segments_list

segments_get

segments_preview

broadcasts_list

broadcasts_create

broadcasts_get

broadcasts_update

broadcasts_preflight

broadcasts_send_test

broadcasts_schedule

broadcasts_unschedule

broadcasts_send

broadcasts_cancel

broadcasts_get_send_progress

sequences_list

sequences_create

sequences_get

sequences_update

sequences_preflight

sequences_preview_journey

sequences_send_test

sequences_update_status

automations_list

automations_create

automations_get

automations_update

automations_preflight

automations_preview_journey

automations_send_test

automations_update_status

email_templates_list

email_templates_create

email_templates_get

email_templates_preview

email_templates_update

Mailrith MCP Server

Official MCP Registry

Official Builds And Forks

Install

Configuration

Related servers