Mailrith Email Marketing

Official52 toolsLive

by anrawool · TypeScript

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

MCP Server: com.mailrith/mailrith

The com.mailrith/mailrith MCP server provides access to Mailrith functionality for managing subscribers, broadcasts, sequences, and automations, along with reporting. Its scope is described as “Manage Subscribers, Broadcasts, Sequences, Automations, and reporting in Mailrith.”

🛠️ Key Features

Subscriber management
Broadcast management
Sequence management
Automation management
Reporting

🚀 Use Cases

Create and maintain subscriber lists in Mailrith
Send broadcasts to targeted audiences
Run multi-step sequences
Automate marketing workflows
Review reporting data

⚡ Developer Benefits

Integrates with MCP for tool access
Clearly scoped to Mailrith modules (subscribers, broadcasts, sequences, automations, reporting)

⚠️ Limitations

Available information does not specify individual MCP tools, tool count, authentication details, or supported operations beyond the stated categories.

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 after reading the current resource state. Permission: analytics: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/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.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "description": "Optional idempotency key to retry the request safely."
    },
    "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",
          "format": "date-time"
        },
        "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. 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",
          "format": "date-time"
        },
        "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
}

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 for safe retries.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "description": "Optional idempotency key for safe retries."
    },
    "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"
        },
        "preview_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "body_document": {
          "$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.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello from Mailrith."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello from Mailrith."
                }
              ]
            }
          ]
        }
      ]
    },
    "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 a broadcast draft or scheduled send in place. 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"
        },
        "preview_text": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "body_document": {
          "$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.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello from Mailrith."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello from Mailrith."
                }
              ]
            }
          ]
        }
      ]
    },
    "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 to one recipient. 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 make retries safe.
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",
      "description": "Optional idempotency key to make retries safe."
    },
    "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"
        },
        "subscriber_id": {
          "type": "string",
          "description": "The saved Subscriber whose personalization should be rendered in the test message."
        }
      }
    }
  }
}

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",
          "format": "date-time",
          "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 make retries safe.
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",
      "description": "Optional idempotency key to make retries safe."
    },
    "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 make retries safe.

Raw schema

{
  "type": "object",
  "properties": {
    "broadcast_id": {
      "type": "string",
      "description": "The broadcast identifier."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional idempotency key to make retries safe."
    }
  },
  "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 make retries safe.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "description": "Optional idempotency key to make retries safe."
    },
    "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"
        },
        "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.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello from Mailrith."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello from Mailrith."
                }
              ]
            }
          ]
        }
      ]
    },
    "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 sequence. 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"
        },
        "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.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello from Mailrith."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello from Mailrith."
                }
              ]
            }
          ]
        }
      ]
    },
    "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 make retries safe.
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",
      "description": "Optional idempotency key to make retries safe."
    },
    "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 make retries safe.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "description": "Optional idempotency key to make retries safe."
    },
    "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"
        },
        "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.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello from Mailrith."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello from Mailrith."
                }
              ]
            }
          ]
        }
      ]
    },
    "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 automation. 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"
        },
        "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.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello from Mailrith."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello from Mailrith."
                }
              ]
            }
          ]
        }
      ]
    },
    "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 make retries safe.
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",
      "description": "Optional idempotency key to make retries safe."
    },
    "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 for safe retries.
body	object	required	The exact JSON request body defined by the Mailrith public API contract.

Raw schema

{
  "type": "object",
  "properties": {
    "idempotency_key": {
      "type": "string",
      "description": "Optional idempotency key for safe retries."
    },
    "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.",
          "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.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello from Mailrith."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello from Mailrith."
                }
              ]
            }
          ]
        }
      ]
    },
    "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.",
          "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.",
      "example": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello from Mailrith."
              }
            ]
          }
        ]
      },
      "examples": [
        {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Hello from Mailrith."
                }
              ]
            }
          ]
        }
      ]
    },
    "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 and self-hosted HTTP use MAILRITH_API_KEY automatically. An explicit --api-key value takes precedence. Keep either value in the client secret store or process environment; never put it in a committed configuration file. Local stdio stops with a clear setup error when neither value is present because it has no browser-based OAuth flow.

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.

Install

Tools (52)

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.0.1"
      ],
      "env": {
        "MAILRITH_API_KEY": "<YOUR_MAILRITH_API_KEY>"
      }
    }
  }
}