MCP tools - Paubox API Docs

The Paubox MCP Server exposes 30 tools across three areas: Email, Forms, and Email Marketing. Each tool maps to an underlying Paubox API operation. All 30 tools are available over both transports — the hosted HTTP server at https://mcp.paubox.com/mcp and the @paubox/mcp stdio package. How each one receives your API key is the only difference.

The optional apiKey parameter listed on every tool below exists only on the HTTP transport. Over stdio the key comes from the PAUBOX_API_KEY environment variable and the parameter is not accepted; omit it. Over HTTP the key is resolved from the OAuth token, the x-paubox-api-key header, or that parameter.Parameters use camelCase (formId, subscriptionListId) even where the underlying REST API uses snake_case.

Email

send_secure_email

Sends a single HIPAA compliant email through the Paubox Email API. The sender address must belong to a domain you have verified in the Paubox dashboard.

Parameter	Type	Required	Description
`from`	string	Yes	Sender address. Must be on a verified Paubox domain.
`to`	array of strings	Yes	Recipient email addresses.
`subject`	string	Yes	Email subject line.
`message`	string	Yes	Message body. Sent as plain text; the server also generates an HTML version automatically.
`cc`	array of strings	No	CC recipients.
`bcc`	array of strings	No	BCC recipients.
`forceSecureNotification`	boolean	No	Force a secure notification regardless of recipient settings. Defaults to `false`.
`apiKey`	string	No	Paubox API key. Overrides the credential resolved from the connector or headers.

Example payload

{
  "from": "provider@clinic.com",
  "to": ["patient@example.com"],
  "subject": "Your appointment summary",
  "message": "Thank you for visiting us today."
}

Response: returns a sourceTrackingId string you can pass to check_email_status.

check_email_status

Retrieves the current delivery status of a message sent via send_secure_email.

Parameter	Type	Required	Description
`sourceTrackingId`	string	Yes	The tracking ID returned by `send_secure_email`.
`apiKey`	string	No	Paubox API key.

Example payload

{
  "sourceTrackingId": "abc123def456"
}

Response: returns an object with delivery disposition details and a timestamp.

validate_credentials

Verifies that the Paubox API credentials are present and valid by making a live check against the Paubox API. Useful as a first step before sending email.

Parameter	Type	Required	Description
`apiKey`	string	No	Paubox API key. Pass if you want to validate a specific API key rather than the one already configured.

When connecting via stdio (Claude Code), the API key comes from an environment variable and no parameters are needed. Example payload

{}

Response: returns a confirmation with a masked API key on success, or an error description if the API key is missing or invalid.

Forms

The two tools below need no credentials. Everything after them manages forms and submissions and requires an API key carrying the forms scope, sent as a Bearer token; scoped keys are managed in the Paubox admin dashboard. See Forms authentication.

get_form

Retrieves the full definition of a Paubox Form, including its title, description, and field schema, so an agent can present the form questions in a conversation. No authentication is required for active forms. When an API key carrying the forms scope is available, inactive and archived forms become retrievable too.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the Paubox Form to retrieve.
`apiKey`	string	No	Paubox API key with the `forms` scope. Enables retrieving inactive and archived forms.

Example payload

{
  "formId": "550e8400-e29b-41d4-a716-446655440000"
}

Response: returns a form object including title, description, form_json (field definitions), and metadata fields (active, signable, submission_count, created_at, updated_at).

submit_form

Submits a completed response to a Paubox Form. No authentication is required for this tool.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the form being submitted.
`formData`	object	Yes	Key-value pairs matching the form’s field schema (`form_json`). Structure varies per form.
`attachments`	array of objects	No	File attachments. Each object must include `name` (filename) and `content` (base64-encoded file). Max total size: 250 MB.

Example payload: text fields only

{
  "formId": "550e8400-e29b-41d4-a716-446655440000",
  "formData": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com"
  }
}

Example payload: with attachment

{
  "formId": "550e8400-e29b-41d4-a716-446655440000",
  "formData": {
    "first_name": "Jane"
  },
  "attachments": [
    {
      "name": "consent.pdf",
      "content": "JVBERi0xLjQ..."
    }
  ]
}

Response: returns a success confirmation message on success.

list_forms

Lists a customer’s Paubox Forms with search, filtering, ordering, and pagination.

Parameter	Type	Required	Description
`customerId`	integer	Yes	Paubox customer ID the forms belong to.
`search`	string	No	Search text matched against form title and description.
`formId`	string (UUID)	No	Filter to a specific form.
`archived`	boolean	No	Filter by archived status.
`active`	boolean	No	Filter by active status.
`orderBy`	string	No	Sort field: `title`, `updated_at`, or `submission_count`. Defaults to `created_at`.
`order`	string	No	`asc` or `desc`. Defaults to `desc`.
`page`	integer	No	Page number. Defaults to `1`.
`items`	integer	No	Items per page. Defaults to `50`, maximum `100`.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Example payload

{
  "customerId": 1234,
  "active": true,
  "orderBy": "submission_count",
  "order": "desc"
}

Response: returns a paginated list of form objects with title, status, and submission counts.

create_form

Creates a new Paubox Form.

Parameter	Type	Required	Description
`title`	string	Yes	Form title.
`formJson`	object	Yes	Form field schema (`form_json`). Pass the object itself; a JSON-encoded string is also parsed.
`customerId`	integer	Yes	Paubox customer ID that owns the form.
`description`	string	No	Form description.
`formHtml`	string	No	Rendered form HTML.
`formCss`	string	No	Form CSS.
`recipient`	string	No	Comma-separated email addresses that receive submission notifications.
`signable`	boolean	No	Whether the form collects a signature.
`signatureConfirmationLabel`	string	No	Label shown next to the signature confirmation checkbox.
`subscriptionListId`	string	No	Subscription list to add submitters to.
`type`	string	No	Form type, for example `marketing_form`.
`active`	boolean	No	Whether the form is active. Defaults to `false`.
`version`	integer	No	Form version. Defaults to `1`.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Example payload

{
  "customerId": 1234,
  "title": "Patient intake",
  "recipient": "intake@clinic.com",
  "active": true,
  "formJson": {
    "fields": [
      { "name": "first_name", "label": "First name", "type": "text", "required": true },
      { "name": "date_of_birth", "label": "Date of birth", "type": "date" }
    ]
  }
}

Response: returns the created form, including its UUID.

Because formJson is just a field schema, an agent can build one from a fillable PDF’s extracted fields and create a matching Paubox Form in a single conversation.

update_form

Updates an existing Paubox Form. Only the fields you provide change; omitted fields stay as they are.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the form to update.
`title`	string	No	New form title.
`description`	string	No	New form description.
`formJson`	object	No	New form field schema (`form_json`).
`vanityUrl`	string	No	New vanity URL slug.
`recipient`	string	No	Comma-separated email addresses that receive submission notifications.
`active`	boolean	No	Set the form’s active status.
`subscriptionListId`	string	No	Subscription list to add submitters to.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Example payload

{
  "formId": "550e8400-e29b-41d4-a716-446655440000",
  "active": false
}

Response: returns the updated form.

archive_form

Archives a Paubox Form. This sets archived to true and active to false.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the form to archive.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Response: returns the archived form.

unarchive_form

Restores a previously archived Paubox Form.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the form to unarchive.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Response: returns the restored form.

copy_form

Duplicates an existing Paubox Form under a new title.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the form to copy.
`title`	string	Yes	Title for the new copy.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Response: returns the new form, including its UUID.

get_form_stats

Returns aggregate Paubox Forms statistics: active form count, total submission count, and submissions in the last 7 days.

Parameter	Type	Required	Description
`customerId`	integer	No	Paubox customer ID. Defaults to the API key’s customer.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Response: returns active_form_count, submission_count, and submissions_last_7_days.

list_form_submissions

Lists a form’s submissions, with each submission’s form_data parsed into structured key/value pairs.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the form.
`submissionId`	string (UUID)	No	Filter to a single submission.
`orderBy`	string	No	Sort field: `submitter_email`. Defaults to `created_at`.
`order`	string	No	`asc` or `desc`.
`page`	integer	No	Page number. Defaults to `1`.
`items`	integer	No	Items per page. Maximum `100`.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Response: returns submissions with parsed field data, submitter email, and attachment info.

export_submissions_csv

Exports a form’s submissions as CSV text.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the form.
`submissionId`	string (UUID)	No	Export only this submission.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Response: returns CSV text.

export_submission_pdf

Exports a single form submission as a PDF.

Parameter	Type	Required	Description
`formId`	string (UUID)	Yes	UUID of the form.
`submissionId`	string (UUID)	Yes	UUID of the submission.
`apiKey`	string	No	Paubox API key with the `forms` scope.

Response: returns the PDF, base64-encoded.

Email Marketing

These tools read and write Paubox Email Marketing data. They use the same API key as the email tools — no additional scope is required — but the account must have Email Marketing provisioned. Call validate_marketing_access first if another marketing tool reports that no marketing customer was found.

This set is read-only plus safe subscriber and list writes. Campaign sending and bulk deletion are deliberately not exposed over MCP.

Every tool below accepts an optional apiKey string parameter, which behaves as described above; it is omitted from the tables that have no other parameters.

validate_marketing_access

Checks whether the account has Email Marketing provisioned and returns the marketing customer profile. Example payload

{}

Response: returns the marketing customer name, from_name, from_email, physical address, and global unsubscribe setting.

list_subscribers

Lists Email Marketing subscribers. Omit subscriptionListId to search the account’s default “All contacts” list.

Parameter	Type	Required	Description
`search`	string	No	Search text. Defaults to all subscribers.
`subscriptionListId`	integer	No	Restrict to a subscription list. IDs come from `list_subscription_lists`.
`dynamicListId`	string (UUID)	No	Restrict to a dynamic list. UUIDs come from `list_dynamic_lists`.
`orderBy`	string	No	Sort field. Defaults to `created_at`.
`order`	string	No	`asc` or `desc`. Defaults to `desc`.
`page`	integer	No	Page number. Defaults to `1`.
`items`	integer	No	Items per page. Defaults to `50`, capped at `200`.
`withStats`	boolean	No	Include per-subscriber delivery statistics.
`apiKey`	string	No	Paubox API key.

Response: returns a paginated list of subscribers.

get_subscriber

Retrieves one subscriber by UUID, including custom field values and subscription list memberships.

Parameter	Type	Required	Description
`subscriberId`	string (UUID)	Yes	Subscriber UUID.
`subscriptionListId`	integer	No	Report subscribed/unsubscribed relative to this subscription list.
`dynamicListId`	string (UUID)	No	Report subscribed/unsubscribed relative to this dynamic list.
`withStats`	boolean	No	Include this subscriber’s delivery statistics.
`apiKey`	string	No	Paubox API key.

Response: returns the subscriber object.

create_subscriber

Adds a subscriber. Requires an email address or a phone number. The subscriber always joins the default “All contacts” list, plus subscriptionListId when given. An existing subscriber matching the same email or phone is updated rather than duplicated. Custom field names that do not exist yet are created automatically.

Parameter	Type	Required	Description
`email`	string	No*	Subscriber email address.
`phoneNumber`	string	No*	Subscriber phone number, normalized to E.164.
`firstName`	string	No	First name.
`lastName`	string	No	Last name.
`customFields`	array of objects	No	Custom field values. Each object has `name` and `value`.
`subscriptionListId`	integer	No	Additional subscription list to subscribe them to.
`apiKey`	string	No	Paubox API key.

* One of email or phoneNumber is required. Example payload

{
  "email": "jane@example.com",
  "firstName": "Jane",
  "subscriptionListId": 42,
  "customFields": [{ "name": "clinic", "value": "Downtown" }]
}

Response: returns the created or updated subscriber.

update_subscriber

Updates an existing subscriber by UUID. Only the fields you provide change.

Parameter	Type	Required	Description
`subscriberId`	string (UUID)	Yes	Subscriber UUID.
`email`	string	No	New email address.
`phoneNumber`	string	No	New phone number, normalized to E.164.
`firstName`	string	No	New first name.
`lastName`	string	No	New last name.
`customFields`	array of objects	No	Custom field values to set. Each object has `name` and `value`.
`subscriptionListId`	integer	No	Subscription list to also subscribe them to.
`apiKey`	string	No	Paubox API key.

Response: returns the updated subscriber.

get_subscribed_count

Counts currently subscribed contacts on a list, excluding unsubscribed and deleted contacts.

Parameter	Type	Required	Description
`subscriptionListId`	integer	No	Subscription list ID. Defaults to the account’s default list.
`apiKey`	string	No	Paubox API key.

Response: returns the subscribed contact count.

list_subscriber_custom_fields

Lists the custom subscriber field types defined for the account. Use this to discover which custom field names create_subscriber and update_subscriber can set. Example payload

{}

Response: returns the account’s custom field definitions.

list_marketing_lists

Lists all audiences — both static subscription lists and filter-based dynamic lists — in one view with subscriber counts. Use list_subscription_lists or list_dynamic_lists when you need one kind specifically.

Parameter	Type	Required	Description
`search`	string	No	Search text matched against list names.
`orderBy`	string	No	`name`, `created_at`, `updated_at`, or `subscriber_count`. Defaults to `name`.
`order`	string	No	`asc` or `desc`. Defaults to `asc`.
`page`	integer	No	Page number. Enables pagination.
`items`	integer	No	Items per page. Maximum `200`.
`apiKey`	string	No	Paubox API key.

Response: returns all audiences with their kind, ID, and subscriber count.

list_subscription_lists

Lists static subscription lists with their integer IDs, subscriber counts, and which one is the default “All contacts” list. The IDs returned here are what subscriptionListId expects elsewhere.

Parameter	Type	Required	Description
`orderBy`	string	No	Sort field. Defaults to `name`.
`order`	string	No	`asc` or `desc`. Defaults to `asc`.
`page`	integer	No	Page number. Enables pagination.
`items`	integer	No	Items per page. Maximum `200`.
`apiKey`	string	No	Paubox API key.

Response: returns subscription lists with integer IDs and subscriber counts.

create_subscription_list

Creates a new, empty subscription list.

Parameter	Type	Required	Description
`name`	string	Yes	Name for the new subscription list.
`apiKey`	string	No	Paubox API key.

Response: returns the new list’s integer ID, for use with create_subscriber and list_subscribers.

list_dynamic_lists

Lists dynamic lists — filter-based segments that recompute their membership — with their UUIDs, filter definitions, and subscriber counts.

Parameter	Type	Required	Description
`orderBy`	string	No	Sort field. Defaults to `name`.
`order`	string	No	`asc` or `desc`. Defaults to `asc`.
`page`	integer	No	Page number. Enables pagination.
`items`	integer	No	Items per page. Maximum `200`.
`apiKey`	string	No	Paubox API key.

Response: returns dynamic lists with UUIDs, filter definitions, and subscriber counts.

list_campaign_sends

Lists campaign sends — each time a marketing email went out to a list — with per-send counts for delivered, viewed, clicked, bounced, and unsubscribed.

Parameter	Type	Required	Description
`search`	string	No	Search text matched against the send.
`orderBy`	string	No	Sort field. Defaults to `created_at`.
`order`	string	No	`asc` or `desc`. Defaults to `desc`.
`page`	integer	No	Page number. Defaults to `1`.
`items`	integer	No	Items per page. Maximum `200`.
`apiKey`	string	No	Paubox API key.

Response: returns campaign sends with their integer IDs and per-send engagement counts.

list_campaign_deliveries

Lists individual deliveries — one row per recipient per campaign — showing what happened to each message.

Parameter	Type	Required	Description
`campaignMailingId`	integer	No	Restrict to one campaign mailing.
`campaignMailingSendId`	integer	No	Restrict to one send of a campaign mailing. IDs come from `list_campaign_sends`.
`search`	string	No	Search text.
`orderBy`	string	No	Sort field. Defaults to `created_at`.
`order`	string	No	`asc` or `desc`. Defaults to `desc`.
`page`	integer	No	Page number. Defaults to `1`.
`items`	integer	No	Items per page. Maximum `200`.
`apiKey`	string	No	Paubox API key.

Response: returns per-recipient delivery rows.

get_campaign_analytics

Runs an Email Marketing analytics report.

Parameter	Type	Required	Description
`report`	string	Yes	Which report to run. See the table below.
`campaignMailingId`	integer	No	Scope to one campaign mailing.
`campaignMailingSendId`	integer	No	Scope to one campaign send.
`dripCampaignId`	integer	No	Scope to one drip campaign.
`trackingLinkId`	integer	No	Scope to one tracking link.
`emailType`	string	No	Filter by email type.
`search`	string	No	Search text.
`orderBy`	string	No	Sort field, for example `marketing_email_id`, `sent_at`, or `subscription_list_name`.
`order`	string	No	`asc` or `desc`. Defaults to `desc`.
`byDate`	boolean	No	For `campaign_mailing_send_totals`: bucket results by date.
`startDate`	string	No	Start of the date range. Pair with `endDate`.
`endDate`	string	No	End of the date range. Pair with `startDate`.
`dateOffset`	integer	No	For `campaign_mailing_send_totals` with `byDate`: look back this many days instead of giving `startDate`/`endDate`.
`withStats`	boolean	No	Include summed delivery statistics columns.
`apiKey`	string	No	Paubox API key.

`report` value	Returns
`campaign_mailing_sends_table`	Per-send performance rows.
`campaign_mailing_send_totals`	Aggregate totals, optionally bucketed by date.
`campaign_mailing_deliveries_table`	Per-recipient detail for one campaign or send.
`subscribers_by_tracking_link`	Which subscribers clicked a link.
`tracking_links_by_unique_link`	Click counts per link.

Example payload

{
  "report": "campaign_mailing_send_totals",
  "byDate": true,
  "dateOffset": 30
}

Response: returns the requested report rows.

get_marketing_bulk_job

Checks the progress of an asynchronous bulk job. Bulk subscriber imports and CSV exports return a job ID (jid or bid) instead of a result; pass it here.

Parameter	Type	Required	Description
`bulkJobId`	string	Yes	The `bid` or `jid` returned by a bulk operation.
`apiKey`	string	No	Paubox API key.

Response: returns total, pending, and failed counts for the job.

​Email

​send_secure_email

​check_email_status

​validate_credentials

​Forms

​get_form

​submit_form

​list_forms

​create_form

​update_form

​archive_form

​unarchive_form

​copy_form

​get_form_stats

​list_form_submissions

​export_submissions_csv

​export_submission_pdf

​Email Marketing

​validate_marketing_access

​list_subscribers

​get_subscriber

​create_subscriber

​update_subscriber

​get_subscribed_count

​list_subscriber_custom_fields

​list_marketing_lists

​list_subscription_lists

​create_subscription_list

​list_dynamic_lists

​list_campaign_sends

​list_campaign_deliveries

​get_campaign_analytics

​get_marketing_bulk_job

Email

send_secure_email

check_email_status

validate_credentials

Forms

get_form

submit_form

list_forms

create_form

update_form

archive_form

unarchive_form

copy_form

get_form_stats

list_form_submissions

export_submissions_csv

export_submission_pdf

Email Marketing

validate_marketing_access

list_subscribers

get_subscriber

create_subscriber

update_subscriber

get_subscribed_count

list_subscriber_custom_fields

list_marketing_lists

list_subscription_lists

create_subscription_list

list_dynamic_lists

list_campaign_sends

list_campaign_deliveries

get_campaign_analytics

get_marketing_bulk_job