PieterPost MCP
PieterPost 让 AI 代理能够通过一个安全的、基于 OAuth 的 MCP 服务器,准备、定价、审核、支付并发送真实的信件和明信片。
文档
MCP reference for account-free letters and postcards, plus account tools with OAuth. Includes tool schemas, safety rules, and examples.
Public MCP URL (no authentication)
https://pieterpost.com/mcp/public/
Markdown docs
https://pieterpost.com/api/docs/mcp.md
MCP Markdown reference
This is the same markdown returned from the public MCP docs URL for agents.
Markdown-only URL
https://pieterpost.com/api/docs/mcp.md
# PieterPost MCP docs
Docs page: https://pieterpost.com/api/docs/mcp
Source: https://pieterpost.com/api/docs/mcp.md
Public MCP server URL (no authentication): \`https://pieterpost.com/mcp/public/\`
Account MCP server URL (OAuth): \`https://pieterpost.com/mcp/setup/\`
Protocol version: \`2025-11-25\`
Supported protocol versions: \`2025-11-25\`, \`2025-06-18\`, \`2025-03-26\`, \`2024-11-05\`
Server version: \`2026.08.27.1\`
This is the markdown-only reference for agents and MCP clients that connect to PieterPost. Use it for tool descriptions, input types, OAuth details, safety rules, and examples.
## Public MCP: no account required
Connect to \`https://pieterpost.com/mcp/public/\` for account-free letters and postcards. No PieterPost account, API key, OAuth client, bearer token, or scope is required. Each public tool declares \`securitySchemes: [{ "type": "noauth" }]\`.
Use the public endpoint for guest connectors. The account endpoint below exposes a separate set of tools for signed-in users.
\`\`\`json
{
"type": "mcp",
"server_label": "pieterpost-public",
"server_url": "https://pieterpost.com/mcp/public/"
}
\`\`\`
Send JSON-RPC requests with POST and Content-Type: application/json. Discovery supports initialize, notifications/initialized, tools/list, and ping. GET is not supported. Use tools/list for the current public tool schemas.
### Public mail workflow
1. Collect the recipient name, structured postal address, and exact final message. Preserve the text and line breaks. Never guess missing address details.
2. Use upload_asset for PDFs or images when needed. Custom postcard fronts must be square. Letters support up to three attachments and requests support up to 25 recipients.
3. Use quote_order to validate the address and price without creating a mail order. Ask the user to correct or accept any address warning before proceeding.
4. Use prepare_letter or prepare_postcard to create an unpaid draft. Give each create operation a fresh random UUID idempotencyKey. Reuse it only when retrying the same operation with the same payload.
For registered letters, set \`deliveryService: "registered"\` on \`quote_order\` and \`prepare_letter\`. Omission means standard delivery. For US recipients this selects Certified Mail with return receipt. The server checks destination availability, page limits, and provider prices. Unsupported requests return an error; they do not switch to standard mail. Postcards do not support registered delivery. Payment uses the same prepared order and price.
5. Use create_payment_link with the returned preparedOrderRef, a new idempotencyKey, and the same mode. Return paymentLinkUrl so the user can review and pay in hosted checkout. The public MCP tools do not execute payment or direct sending; printing and posting start only after confirmed payment.
6. Use get_order_status with the private orderRef returned in this conversation or supplied by the user. It returns minimal payment and fulfillment status, without the message, address, email, or checkout link. Never guess references or claim that mail was sent before the status confirms it.
\`get_order_status\` also returns \`delivery\` with per-recipient postal status, tracking number and carrier URL when available, delivered date, estimates, and \`statusPageUrl\`. \`fulfilled\` means submission for printing and posting, not confirmed delivery. Check \`delivery.items[].status\` for delivery. Tracking may be pending. \`availability: "unavailable"\` means no current delivery data is available; it does not mean failed delivery. Test mode has no live tracking. For bulk orders use \`deliveryLimit\` (1 to 25) and \`deliveryOffset\`, then continue with \`delivery.nextOffset\` until null. No message or recipient address is returned.
Public MCP has no saved contacts, wallet, account history, top-ups, API-key management, direct-order tool, or agentic payment tool. The user supplies the postal address for each request. search and fetch read public postal guidance only.
### Review and test mode
No test user or login credentials are needed for the public endpoint. Set mode: "test" on every mail operation during review; keep the same mode for preparation, checkout, and status. Test-mode orders never send physical mail. Do not pay during a demonstration. Public writable tools default to live when mode is omitted.
\`\`\`json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "prepare_letter",
"arguments": {
"mode": "test",
"idempotencyKey": "45bda36c-36bd-4eb7-a4f5-6b8d8c8e61b0",
"letters": [
{
"recipient": {
"city": "Amsterdam",
"country": "NL",
"customFields": {
"gift_code": "SPRING-10"
},
"name": "Pieter Example",
"postalCode": "1012 AB",
"streetAddress": "Damrak 1"
},
"message": "This is a review demonstration. Do not send physical mail."
}
]
}
}
}
\`\`\`
### Public errors, limits, and approval
Tool failures return isError with an error code, message, retryable flag, and field details where available. Correct validation errors before retrying. For retryable errors, use backoff and preserve the original idempotencyKey. Check order status before retrying an operation with an uncertain result.
Guest operations allow up to 120 requests per minute per IP address. A rate-limited response uses HTTP 429 or a tool error with code rate_limited; reduce request frequency and retry with backoff. File, recipient, and input limits are included in the schemas below.
No authentication does not remove user approval requirements. Review the exact content, recipient, price, and payment action with the user. Apply the host's approval policy for each action. Tool annotations describe effects; they are not a substitute for user consent.
### Public tool definitions
These definitions come from the same getPublicMcpTools function used by the public tools/list response. They describe the public tools only.
\`\`\`json
{
"tools": [
{
"name": "search",
"title": "Search PieterPost Guide",
"description": "Search public PieterPost postal workflow guidance. Does not search accounts, contacts, orders, or credentials.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"query": {
"type": "string"
}
},
"required": [
"query"
]
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"title": "Search PieterPost Guide"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"name": "fetch",
"title": "Read PieterPost Guide",
"description": "Read a public guide returned by search. Only mail-workflow, postal-addresses, and checkout-and-status IDs are supported.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
]
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"title": "Read PieterPost Guide"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"name": "create_payment_link",
"title": "Create Guest Mail Checkout",
"description": "Create hosted checkout for an unpaid prepared guest order. Supply preparedOrderRef, a new random UUID idempotencyKey, and the same mode. No login required. The user reviews and pays; this tool does not pay or send mail.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"preparedOrderRef": {
"type": "string"
},
"idempotencyKey": {
"type": "string",
"minLength": 32,
"maxLength": 140,
"description": "Fresh random UUID for this operation. Reuse only for retries of the same payload."
},
"mode": {
"type": "string",
"enum": [
"test",
"live"
],
"description": "Defaults to live. Use test for demonstrations; test orders never send mail."
},
"paymentMethod": {
"type": "string",
"enum": [
"auto",
"card",
"ideal"
]
}
},
"required": [
"preparedOrderRef",
"idempotencyKey"
]
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": true,
"title": "Create Guest Mail Checkout"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"name": "get_order_status",
"title": "Check Guest Mail Status",
"description": "Get payment, fulfillment, and postal delivery status for a guest orderRef from this conversation or supplied by the user. delivery includes per-recipient status, tracking number/link when available, delivery date, and status-page link. fulfilled means submission for printing and posting, not delivery. Use deliveryOffset and deliveryLimit (1-25) for bulk orders. Returns no content, postal address, email, or payment URL.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"properties": {
"orderRef": {
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"test",
"live"
],
"description": "Defaults to live. Use test for demonstrations; test orders never send mail."
},
"deliveryOffset": {
"type": "integer",
"minimum": 0
},
"deliveryLimit": {
"type": "integer",
"minimum": 1,
"maximum": 25
}
},
"required": [
"orderRef"
]
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"title": "Check Guest Mail Status"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": true,
"title": "Create Review Link"
},
"description": "Create an encrypted, expiring URL to review and edit a letter on PieterPost without login. Provide a recipient, optional message, and random UUID idempotencyKey. Does not create, pay, or send a mail order.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"idempotencyKey": {
"type": "string",
"minLength": 32,
"maxLength": 140,
"description": "Fresh random UUID for this operation. Reuse only for retries of the same payload."
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"message": {
"description": "Prepared message. Trimmed to 6,000 characters.",
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"test",
"live"
],
"description": "Defaults to live. Use test for demonstrations; test orders never send mail."
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient",
"idempotencyKey"
],
"type": "object"
},
"name": "create_compose_link",
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"title": "Create Review Link",
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": true,
"openWorldHint": true,
"readOnlyHint": false,
"title": "Prepare Agent Letter"
},
"description": "Prepare and price an unpaid physical letter without login. Set deliveryService=registered for registered mail or US Certified Mail with return receipt; standard is the default. Provide letters and a random UUID idempotencyKey. Defaults to live; use mode=test for demonstrations. Returns preparedOrderRef for create_payment_link. Never pays or sends mail.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"composeMode": {
"description": "Letter compose mode. Allowed values: \"personal\" or \"template\". personal uses each letter.message; template uses templateMessage and recipient customFields to generate each letter.",
"type": "string"
},
"deliveryService": {
"description": "Letter delivery service. Allowed values: \"standard\" or \"registered\". Defaults to standard. registered uses the destination service, or Certified Mail with return receipt for US recipients. The server checks availability and page limits and quotes the full price. Applies to all letters in a bulk request; unavailable services return an error. Not available for postcards.",
"type": "string"
},
"idempotencyKey": {
"type": "string",
"minLength": 32,
"maxLength": 140,
"description": "Fresh random UUID for this operation. Reuse only for retries of the same payload."
},
"letters": {
"description": "Bulk letters. Maximum 25.",
"items": {
"additionalProperties": false,
"description": "One letter for one recipient. In personal mode include a message, uploaded attachments, or both. In template mode, templateMessage can supply the message for every recipient. Destination page limits apply to the combined message and attachment pages.",
"properties": {
"attachments": {
"description": "Letter attachment asset IDs or upload_asset objects. Assets must be kind letter-attachment.",
"items": {
"description": "Attachment asset ID string or upload_asset-style object with assetId."
},
"type": "array"
},
"message": {
"description": "Letter body. Trimmed to 6,000 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient"
],
"type": "object"
},
"type": "array"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"test",
"live"
],
"description": "Defaults to live. Use test for demonstrations; test orders never send mail."
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
},
"stampImageAssetId": {
"description": "Asset ID returned by upload_asset for a letter-stamp-image.",
"type": "string"
},
"templateMessage": {
"description": "Shared letter template used when composeMode is template. Supports {{name}}, {{first_name}}, {{address}}, {{street}}, {{city}}, {{postal_code}}, {{country}}, and recipient customFields. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"variableKeys": {
"description": "Letter template variable keys used for recipient customFields.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"idempotencyKey",
"letters"
],
"type": "object"
},
"name": "prepare_letter",
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"title": "Prepare Agent Letter",
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": true,
"openWorldHint": true,
"readOnlyHint": false,
"title": "Prepare Agent Postcard"
},
"description": "Prepare and price an unpaid postcard without login. Provide postcard and a random UUID idempotencyKey. Defaults to live; use mode=test for demonstrations. Returns preparedOrderRef for create_payment_link. Never pays or sends mail.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"idempotencyKey": {
"type": "string",
"minLength": 32,
"maxLength": 140,
"description": "Fresh random UUID for this operation. Reuse only for retries of the same payload."
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"test",
"live"
],
"description": "Defaults to live. Use test for demonstrations; test orders never send mail."
},
"postcard": {
"additionalProperties": false,
"description": "Postcard payload. Provide recipient for one card or recipients for bulk cards up to 25 recipients. Add frontImageAssetId or frontImage when you want a square 1:1 custom front instead of the default one.",
"properties": {
"composeMode": {
"description": "Compose mode. Allowed values: \"personal\" or \"template\". personal sends one message as written; template lets recipient customFields replace variables in supported templates.",
"type": "string"
},
"frontImage": {
"description": "Optional square 1:1 postcard image asset ID string or upload_asset-style object. Equivalent to frontImageAssetId."
},
"frontImageAssetId": {
"description": "Optional asset ID returned by upload_asset for a square 1:1 postcard-image.",
"type": "string"
},
"message": {
"description": "Postcard message. Trimmed to 1,200 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"recipients": {
"description": "Bulk postcard recipients. Maximum 25.",
"items": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"variableKeys": {
"description": "Template variable keys to use for postcard personalization.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
}
},
"required": [
"idempotencyKey",
"postcard"
],
"type": "object"
},
"name": "prepare_postcard",
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"title": "Prepare Agent Postcard",
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": true,
"title": "Quote Mail Order"
},
"description": "Validate and price exactly one of letters or postcard without creating an order, paying, or sending mail. For letters, deliveryService=registered quotes registered mail or US Certified Mail. Unsupported destinations and page counts return errors. No account or wallet data is accessed. US address verification can contact the postal provider.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"composeMode": {
"description": "Letter compose mode. Allowed values: \"personal\" or \"template\". personal uses each letter.message; template uses templateMessage and recipient customFields to generate each letter.",
"type": "string"
},
"deliveryService": {
"description": "Letter delivery service. Allowed values: \"standard\" or \"registered\". Defaults to standard. registered uses the destination service, or Certified Mail with return receipt for US recipients. The server checks availability and page limits and quotes the full price. Applies to all letters in a bulk request; unavailable services return an error. Not available for postcards.",
"type": "string"
},
"idempotencyKey": {
"type": "string",
"minLength": 32,
"maxLength": 140,
"description": "Fresh random UUID for this operation. Reuse only for retries of the same payload."
},
"letters": {
"description": "Bulk letters. Maximum 25.",
"items": {
"additionalProperties": false,
"description": "One letter for one recipient. In personal mode include a message, uploaded attachments, or both. In template mode, templateMessage can supply the message for every recipient. Destination page limits apply to the combined message and attachment pages.",
"properties": {
"attachments": {
"description": "Letter attachment asset IDs or upload_asset objects. Assets must be kind letter-attachment.",
"items": {
"description": "Attachment asset ID string or upload_asset-style object with assetId."
},
"type": "array"
},
"message": {
"description": "Letter body. Trimmed to 6,000 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient"
],
"type": "object"
},
"type": "array"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"mode": {
"type": "string",
"enum": [
"test",
"live"
],
"description": "Defaults to live. Use test for demonstrations; test orders never send mail."
},
"postcard": {
"additionalProperties": false,
"description": "Postcard payload. Provide recipient for one card or recipients for bulk cards up to 25 recipients. Add frontImageAssetId or frontImage when you want a square 1:1 custom front instead of the default one.",
"properties": {
"composeMode": {
"description": "Compose mode. Allowed values: \"personal\" or \"template\". personal sends one message as written; template lets recipient customFields replace variables in supported templates.",
"type": "string"
},
"frontImage": {
"description": "Optional square 1:1 postcard image asset ID string or upload_asset-style object. Equivalent to frontImageAssetId."
},
"frontImageAssetId": {
"description": "Optional asset ID returned by upload_asset for a square 1:1 postcard-image.",
"type": "string"
},
"message": {
"description": "Postcard message. Trimmed to 1,200 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"recipients": {
"description": "Bulk postcard recipients. Maximum 25.",
"items": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"variableKeys": {
"description": "Template variable keys to use for postcard personalization.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
},
"senderEmail": {
"description": "Optional order contact email. Hosted Stripe Checkout collects the payer email when omitted.",
"type": "string"
},
"stampImageAssetId": {
"description": "Asset ID returned by upload_asset for a letter-stamp-image.",
"type": "string"
},
"templateMessage": {
"description": "Shared letter template used when composeMode is template. Supports {{name}}, {{first_name}}, {{address}}, {{street}}, {{city}}, {{postal_code}}, {{country}}, and recipient customFields. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"variableKeys": {
"description": "Letter template variable keys used for recipient customFields.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object",
"required": []
},
"name": "quote_order",
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"title": "Quote Mail Order",
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": true,
"openWorldHint": true,
"readOnlyHint": false,
"title": "Upload Mail Asset"
},
"description": "Upload a supplied PDF, PNG, or JPEG for a letter attachment, stamp, square postcard front, or an image for a card or designed letter (kind postcard-image; any aspect ratio works for cards and designed letters). No login required. Returns the assetId to use when preparing mail or in add_image.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"contentType": {
"description": "Content type. Common values: \"application/pdf\" for letter attachments, or \"image/png\" / \"image/jpeg\" for images.",
"type": "string"
},
"fileBase64": {
"description": "Base64-encoded file contents.",
"type": "string"
},
"fileName": {
"description": "Original file name, used for extension validation.",
"type": "string"
},
"fileUrl": {
"description": "Public HTTPS URL to fetch. Private and localhost URLs are rejected.",
"type": "string"
},
"kind": {
"description": "Upload kind. Allowed values: \"letter-attachment\", \"letter-stamp-image\", or \"postcard-image\".",
"type": "string"
}
},
"required": [
"kind",
"fileName",
"contentType"
],
"type": "object"
},
"name": "upload_asset",
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"title": "Upload Mail Asset",
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true,
"title": "List Card Options"
},
"description": "List what a PieterPost card can be: starter designs (templateId, name, occasion, format, sample text), material presets, formats and sizes (profileId), print techniques (standard print, foil, letterpress) with their papers, finishes and rules, letterpress inks, built-in illustrations (iconId) and fonts (search with fontQuery). Read-only; no login.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"fontQuery": {
"description": "Search all fonts by family name; returns only fonts unless sections is given.",
"maxLength": 100,
"type": "string"
},
"sections": {
"description": "Which parts to return: templates, presets, formats, techniques, fonts, icons. Default all (only fonts with fontQuery).",
"items": {
"type": "string",
"description": "Allowed values: \"templates\", \"presets\", \"formats\", \"techniques\", \"fonts\", \"icons\"."
},
"type": "array"
}
},
"type": "object"
},
"name": "list_card_options",
"title": "List Card Options",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": true,
"readOnlyHint": false,
"title": "Create Card Design"
},
"description": "Start a printed greeting card design without login: from a starter design (templateId) or blank, optionally with a material preset, size and a first batch of edits. Returns a private draftToken, an editorUrl where the person can adjust the card and order it from PieterPost, the version, every element with its id and style, technique issues and PNG previews. Give the editorUrl to the person; it gives edit access, so don't post it publicly. Drafts expire 30 days after their last change. Iterate with update_card_design. Call get_card_preview for each side to inspect the rendered card. Nothing is printed, paid or sent.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"locale": {
"description": "Language of starter texts and the editor, e.g. en or nl.",
"maxLength": 10,
"type": "string"
},
"name": {
"description": "Name of the design, shown in the editor.",
"maxLength": 120,
"type": "string"
},
"operations": {
"description": "Edits applied in order, all or nothing (max 50). Element ids come from get_card_design or earlier results; add_element and add_image take an optional id so later operations in the same call can use it.",
"items": {
"additionalProperties": false,
"description": "One edit; send only the fields its op uses. apply_template: Replace the whole design with a starter design. Optional preset (classic, special, deluxe) picks its material; profileId keeps a size. Required: templateId. Optional: preset, profileId. set_card_options: Change technique, paper, format/size or corners. Elements adapt to a new size. Required: nothing else. Optional: corners, glued, glueFirst, paper, backPaper, profileId, technique. rename: Required: name. Optional: none. add_element: Add a text box, shape, QR code (text = the URL; the code is drawn with a white quiet zone, about 80% of the box) or built-in illustration (kind icon with iconId). Any style field can be set at creation. New text is regular weight (fontWeight 400); new shapes have no border and square corners. Text boxes don't grow: give long text enough heightMm. New elements go on top unless behindElementId is given. Required: kind, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). add_image: Place a photo or image: as a new image (target new, default), as the page background (target background), or replacing the picture of an image element (target = its id). Required: image, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). update_element: Change an element's text, position, size, rotation or style, or swap an illustration (iconId). Only the given fields change. Required: elementId. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). delete_element: Required: elementId. Optional: none. set_layer: Change stacking order on its side. Elements stay above the page background: back puts the element just above it. Required: elementId, direction. Optional: none. set_page_background: Set a page's background colour, or use an existing image on that page as its background (elementId). Give one. Required: pageIndex. Optional: backgroundColor, elementId.",
"properties": {
"op": {
"description": "Operation: apply_template, set_card_options, rename, add_element, add_image, update_element, delete_element, set_layer, set_page_background.",
"type": "string"
},
"preset": {
"type": "string",
"description": "Allowed values: \"classic\", \"special\", \"deluxe\"."
},
"profileId": {
"description": "Card size id from list_card_options. set_card_options: Card format and size id from list_card_options. Choose by the format's name, fold and sides (see formatNote there): a card is flat (front and back) unless the person asks for a folded or opening card.",
"type": "string"
},
"templateId": {
"type": "string",
"description": "Allowed values: \"blank\", \"baby_tree\", \"baby_stork\", \"baby_bunny\", \"baby_bw\", \"baby_moon\", \"baby_1\", \"baby_2\", \"baby_bow\", \"baby_elephant\", \"baby_starry\", \"baby_bear\", \"baby_balloon\", \"baby_robin\", \"baby_fox\", \"baby_fawn\", \"baby_meadow\", \"baby_whale\", \"baby_lamb\", \"baby_owl\", \"baby_hedgehog\", \"baby_sailboat\", \"baby_rainbow\", \"baby_wreath\", \"wedding_dunes\", \"wedding_wreath\", \"wedding_1\", \"wedding_pressed\", \"wedding_gold\", \"wedding_farmhouse\", \"wedding_save_date\", \"wedding_summer\", \"wedding_lemons\", \"wedding_doves\", \"wedding_seaside\", \"wedding_blossom\", \"wedding_winter\", \"wedding_tulips\", \"wedding_canal\", \"wedding_windmill\", \"wedding_delft\", \"wedding_tandem\", \"wedding_lavender\", \"wedding_olive\", \"wedding_vineyard\", \"wedding_peonies\", \"wedding_roses\", \"wedding_sunflowers\", \"wedding_autumn\", \"wedding_forest\", \"wedding_mountains\", \"wedding_swans\", \"wedding_champagne\", \"wedding_artdeco\", \"wedding_celestial\", \"wedding_disco\", \"wedding_rings\", \"wedding_cake\", \"wedding_shapes\", \"wedding_rainbow\", \"wedding_pampas\", \"wedding_desert\", \"wedding_tropical\", \"wedding_cherries\", \"wedding_strawberries\", \"wedding_greenhouse\", \"wedding_castle\", \"wedding_paris\", \"wedding_amalfi\", \"wedding_santorini\", \"wedding_cranes\", \"wedding_marigold\", \"wedding_festoon\", \"wedding_festival\", \"wedding_campervan\", \"wedding_sailing\", \"wedding_hearts\", \"wedding_swallows\", \"wedding_butterflies\", \"wedding_bees\", \"wedding_magnolia\", \"wedding_anemones\", \"wedding_dahlias\", \"wedding_wheat\", \"wedding_aurora\", \"wedding_skyline\", \"wedding_oneline\", \"funeral_sea\", \"funeral_willow\", \"funeral_1\", \"thank_you\"."
},
"corners": {
"description": "Corner shape of a rectangular card: square (sharp) or rounded. This is not the card's shape; a square card is a profileId. Allowed values: \"square\", \"rounded\".",
"type": "string"
},
"glued": {
"description": "Flat letterpress, papers under 600 g only: glue a second sheet of the same paper behind the card. By default it's glued after pressing, so no impression shows on the back and the back can be printed freely (at the offer's glued price, see list_card_options). The card gets thicker; its colour doesn't change.",
"type": "boolean"
},
"glueFirst": {
"description": "Glued cards only: glue the two sheets before pressing instead (no surcharge). The card presses like one 600 g sheet, so the impression may show on the back.",
"type": "boolean"
},
"paper": {
"description": "Paper id from list_card_options.",
"type": "string"
},
"backPaper": {
"description": "Glued cards only: the paper id of the sheet glued behind the card, for a card with another colour on the back (one of the technique's papers). The front's paper id or null means the same paper on both sides.",
"type": "string"
},
"technique": {
"type": "string",
"description": "Allowed values: \"digital\", \"letterpress\"."
},
"name": {
"maxLength": 120,
"minLength": 1,
"type": "string"
},
"backgroundColor": {
"description": "Fill colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderColor": {
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderRadiusMm": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"borderWidthMm": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"color": {
"description": "Text colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"finish": {
"description": "Cards only. Text and shapes: foil_* (a foil colour: foil_gold, foil_silver, foil_copper on the foil technique, where foil is a raised 3D layer on top of the print; letterpress offers the printer's foil colours pressed into the paper, also with blind or emboss; the two never mix on one card; colours per technique in list_card_options), print (letterpress, printed in its own colour but not pressed in; use it for text that doesn't need pressing), blind (letterpress, pressed in without colour; without a finish, text and shapes on a letterpress front are printed and pressed in; pressing needs 600 g paper) or emboss (letterpress, raised from the back; nothing may be printed behind it on the inside); none removes it. Images and icons can be blind or emboss only: their visible part is pressed and a transparent background stays flat, so use a transparent PNG with clean, hard edges (soft edges and shadows are pressed all or nothing). On a shape the whole fill becomes foil (there is no foil outline), so keep foil shapes small. Which finishes are allowed depends on the card's technique (list_card_options). Allowed values: \"none\", \"print\", \"foil_white_gold\", \"foil_gold\", \"foil_gold_matte\", \"foil_gold_holo\", \"foil_caramel_gold\", \"foil_caramel_glitter\", \"foil_rose_gold\", \"foil_copper\", \"foil_copper_matte\", \"foil_bronze\", \"foil_brown\", \"foil_white\", \"foil_pearl\", \"foil_silver\", \"foil_silver_holo\", \"foil_light_pink\", \"foil_holo_pink\", \"foil_magenta\", \"foil_cherry_red\", \"foil_lilac\", \"foil_purple\", \"foil_ice_blue_matte\", \"foil_silver_blue\", \"foil_blue\", \"foil_dark_blue_gloss\", \"foil_ocean\", \"foil_spring_green_matte\", \"foil_green\", \"foil_grass_green_gloss\", \"foil_petrol\", \"blind\", \"emboss\".",
"type": "string"
},
"fontFamily": {
"description": "Font ID from list_card_options (fonts), or legacy inter, mono, serif.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"italic\", \"normal\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"heightMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"curve": {
"description": "Text only: bend the text along an arc, -100 to 100. Positive arches up (like a rainbow), negative bows down (like a smile); 0 is straight. Curved text is one line (line breaks become spaces) centred in its box; make the box wide and tall enough for the arc. 30 to 60 is a gentle arch.",
"minimum": -100,
"maximum": 100,
"type": "number"
},
"letterSpacingPt": {
"description": "Extra space after each text grapheme in points (1 pt = 1/72 inch). Default 0. Does not change text or rich-text runs.",
"minimum": -2,
"maximum": 30,
"type": "number"
},
"lineHeight": {
"description": "Text baseline distance as a font-size multiplier. Default 1.35.",
"minimum": 0.5,
"maximum": 5,
"type": "number"
},
"imagePositionX": {
"description": "Horizontal cover crop anchor in percent: 0 left, 50 centre, 100 right. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imagePositionY": {
"description": "Vertical cover crop anchor in percent: 0 top, 50 centre, 100 bottom. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imageZoom": {
"description": "Cover crop zoom multiplier, 1 to 3. Ignored for contain.",
"minimum": 1,
"maximum": 3,
"type": "number"
},
"textRuns": {
"description": "Rich text runs. Concatenated run text must equal text (or the current text on update). Omitted styles inherit the element style; a run's fontFamily, fontSizePt and color override the element's (not on curved text, which uses the element's). An empty array clears rich formatting. Whole-element font style, weight and underline changes also update existing runs, and whole-element font, size and colour changes replace the runs' own, unless textRuns is supplied.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"normal\", \"italic\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"fontFamily": {
"description": "Font ID from list_card_options (fonts) for this run.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"color": {
"description": "Run colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
}
}
}
},
"imageFit": {
"type": "string",
"description": "Allowed values: \"contain\", \"cover\"."
},
"opacity": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"rotation": {
"maximum": 360,
"minimum": -360,
"type": "number"
},
"shadow": {
"type": "string",
"description": "Allowed values: \"none\", \"soft\"."
},
"text": {
"description": "Text content, or the URL for a QR code. On letters, supports tags such as {{first_name}}; cards have no personal fields (every card in an order is the same).",
"maxLength": 5000,
"type": "string"
},
"textAlign": {
"type": "string",
"description": "Allowed values: \"center\", \"left\", \"right\"."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"widthMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"xMm": {
"description": "Left edge in mm from the page's left edge.",
"type": "number"
},
"yMm": {
"description": "Top edge in mm from the page's top edge.",
"type": "number"
},
"behindElementId": {
"description": "Place the new element directly behind this element instead of on top. add_image: Place a new image directly behind this element instead of on top.",
"type": "string"
},
"iconId": {
"description": "Illustration from list_card_options icons. Icons can't be recoloured. update_element: Swap the artwork of an illustration element. Allowed values: \"cardBabyBalloon\", \"cardBabyFox\", \"cardBabyFawn\", \"cardBabyMeadow\", \"cardBabyWhale\", \"cardBabyLamb\", \"cardBabyOwl\", \"cardBabyHedgehog\", \"cardBabySailboat\", \"cardBabyRainbow\", \"cardBabyWreath\", \"cardBabyBear\", \"cardBabyBow\", \"cardBabyBunny\", \"cardBabyElephant\", \"cardBabyFeetBw\", \"cardBabyMoon\", \"cardBabyRobin\", \"cardBabyStarry\", \"cardBabyStork\", \"cardBabyTree\", \"cardFuneralSea\", \"cardFuneralWillow\", \"cardWeddingCouple\", \"cardWeddingPressed\", \"cardWeddingVenue\", \"cardWeddingWreath\", \"cardWeddingSummer\", \"cardWeddingLemons\", \"cardWeddingDoves\", \"cardWeddingSeaside\", \"cardWeddingWinter\", \"cardWeddingBlossom\", \"cardWeddingTulips\", \"cardWeddingCanal\", \"cardWeddingWindmill\", \"cardWeddingDelft\", \"cardWeddingTandem\", \"cardWeddingLavender\", \"cardWeddingOlive\", \"cardWeddingVineyard\", \"cardWeddingPeonies\", \"cardWeddingRoses\", \"cardWeddingSunflowers\", \"cardWeddingAutumn\", \"cardWeddingForest\", \"cardWeddingMountains\", \"cardWeddingSwans\", \"cardWeddingChampagne\", \"cardWeddingArtdeco\", \"cardWeddingCelestial\", \"cardWeddingDisco\", \"cardWeddingRings\", \"cardWeddingCake\", \"cardWeddingShapes\", \"cardWeddingRainbow\", \"cardWeddingPampas\", \"cardWeddingDesert\", \"cardWeddingTropical\", \"cardWeddingCherries\", \"cardWeddingStrawberries\", \"cardWeddingGreenhouse\", \"cardWeddingCastle\", \"cardWeddingParis\", \"cardWeddingAmalfi\", \"cardWeddingSantorini\", \"cardWeddingCranes\", \"cardWeddingMarigold\", \"cardWeddingFestoon\", \"cardWeddingFestival\", \"cardWeddingCampervan\", \"cardWeddingSailing\", \"cardWeddingHearts\", \"cardWeddingSwallows\", \"cardWeddingButterflies\", \"cardWeddingBees\", \"cardWeddingMagnolia\", \"cardWeddingAnemones\", \"cardWeddingDahlias\", \"cardWeddingWheat\", \"cardWeddingAurora\", \"cardWeddingSkyline\", \"cardWeddingOneline\", \"recipeHeart\", \"weddingThankYouConfetti\", \"weddingThankYouDance\", \"weddingThankYouEmbrace\", \"weddingThankYouStrip\", \"weddingThankYouWalk\".",
"type": "string"
},
"id": {
"description": "Optional id for the new element, so later operations in this batch can refer to it. add_image: Optional id for the new image or background image.",
"pattern": "^[A-Za-z0-9_-]{1,40}$",
"type": "string"
},
"kind": {
"type": "string",
"description": "Allowed values: \"text\", \"shape\", \"qr\", \"icon\"."
},
"pageIndex": {
"description": "Flat card: 0 = front, 1 = back. Folded card: each page is the whole open sheet, 0 = outside (front, back and door panels), 1 = inside; design.pages[].panels gives each panel's rectangle.",
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"image": {
"additionalProperties": false,
"description": "A JPEG or PNG, max 5 MB: the assetId of an image uploaded with upload_asset (use this for photos the person shared, or to send base64), or a public HTTPS fileUrl. Give one.",
"properties": {
"assetId": {
"maxLength": 80,
"type": "string"
},
"fileUrl": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
},
"target": {
"description": "new (default): a new image; background: the page background image; or the id of an image element whose picture to replace.",
"type": "string"
},
"elementId": {
"description": "Element id from get_card_design or an earlier operation.",
"type": "string"
},
"direction": {
"type": "string",
"description": "Allowed values: \"front\", \"forward\", \"backward\", \"back\"."
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 50,
"type": "array"
},
"preset": {
"description": "classic, special or deluxe material. Allowed values: \"classic\", \"special\", \"deluxe\".",
"type": "string"
},
"previewPages": {
"description": "Sides to return as PNG previews: 0 = front/outside, 1 = back/inside. Default [0, 1] on create and update; [] skips previews.",
"items": {
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"maxItems": 2,
"type": "array"
},
"profileId": {
"description": "Card size id from list_card_options.",
"type": "string"
},
"templateId": {
"description": "Starter design from list_card_options; blank by default. Allowed values: \"blank\", \"baby_tree\", \"baby_stork\", \"baby_bunny\", \"baby_bw\", \"baby_moon\", \"baby_1\", \"baby_2\", \"baby_bow\", \"baby_elephant\", \"baby_starry\", \"baby_bear\", \"baby_balloon\", \"baby_robin\", \"baby_fox\", \"baby_fawn\", \"baby_meadow\", \"baby_whale\", \"baby_lamb\", \"baby_owl\", \"baby_hedgehog\", \"baby_sailboat\", \"baby_rainbow\", \"baby_wreath\", \"wedding_dunes\", \"wedding_wreath\", \"wedding_1\", \"wedding_pressed\", \"wedding_gold\", \"wedding_farmhouse\", \"wedding_save_date\", \"wedding_summer\", \"wedding_lemons\", \"wedding_doves\", \"wedding_seaside\", \"wedding_blossom\", \"wedding_winter\", \"wedding_tulips\", \"wedding_canal\", \"wedding_windmill\", \"wedding_delft\", \"wedding_tandem\", \"wedding_lavender\", \"wedding_olive\", \"wedding_vineyard\", \"wedding_peonies\", \"wedding_roses\", \"wedding_sunflowers\", \"wedding_autumn\", \"wedding_forest\", \"wedding_mountains\", \"wedding_swans\", \"wedding_champagne\", \"wedding_artdeco\", \"wedding_celestial\", \"wedding_disco\", \"wedding_rings\", \"wedding_cake\", \"wedding_shapes\", \"wedding_rainbow\", \"wedding_pampas\", \"wedding_desert\", \"wedding_tropical\", \"wedding_cherries\", \"wedding_strawberries\", \"wedding_greenhouse\", \"wedding_castle\", \"wedding_paris\", \"wedding_amalfi\", \"wedding_santorini\", \"wedding_cranes\", \"wedding_marigold\", \"wedding_festoon\", \"wedding_festival\", \"wedding_campervan\", \"wedding_sailing\", \"wedding_hearts\", \"wedding_swallows\", \"wedding_butterflies\", \"wedding_bees\", \"wedding_magnolia\", \"wedding_anemones\", \"wedding_dahlias\", \"wedding_wheat\", \"wedding_aurora\", \"wedding_skyline\", \"wedding_oneline\", \"funeral_sea\", \"funeral_willow\", \"funeral_1\", \"thank_you\".",
"type": "string"
}
},
"type": "object"
},
"name": "create_card_design",
"title": "Create Card Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true,
"title": "Read Card Design"
},
"description": "Read the current card design, including edits the person made in the editor since your last call: version, every element with its id and style, layout rules, technique issues and optional PNG previews. Call it before editing when time has passed. Use get_card_preview to inspect the rendered card.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draftToken": {
"description": "draftToken returned by create_card_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"previewPages": {
"description": "Sides to preview; none by default.",
"items": {
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"maxItems": 2,
"type": "array"
}
},
"required": [
"draftToken"
],
"type": "object"
},
"name": "get_card_design",
"title": "Read Card Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true,
"title": "View Card Preview"
},
"description": "View one rendered card side as a PNG image. Call after creating or editing a card to inspect its actual appearance. Returns text and image content only, so ChatGPT can see the pixels. Read-only: does not change, order, pay for, print or send the card. Read design data and print warnings with get_card_design.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draftToken": {
"description": "draftToken returned by create_card_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"pageIndex": {
"description": "Card side: 0 = front/outside, 1 = back/inside.",
"maximum": 1,
"minimum": 0,
"type": "integer"
}
},
"required": [
"draftToken",
"pageIndex"
],
"type": "object"
},
"name": "get_card_preview",
"title": "View Card Preview",
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": true,
"readOnlyHint": false,
"title": "Update Card Design"
},
"description": "Edit a card design: change texts, fonts, colours, positions, images, background, technique, paper or size with a batch of operations. Pass the version you last saw as baseVersion; if the person changed the design in the editor meanwhile, nothing is applied and the error returns the current design to edit instead. Returns the new version, elements, issues and PNG previews. The editorUrl stays the same. Call get_card_preview for each side after editing.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"baseVersion": {
"description": "version from the latest create, get or update result.",
"minimum": 1,
"type": "integer"
},
"draftToken": {
"description": "draftToken returned by create_card_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"operations": {
"description": "Edits applied in order, all or nothing (max 50). Element ids come from get_card_design or earlier results; add_element and add_image take an optional id so later operations in the same call can use it.",
"items": {
"additionalProperties": false,
"description": "One edit; send only the fields its op uses. apply_template: Replace the whole design with a starter design. Optional preset (classic, special, deluxe) picks its material; profileId keeps a size. Required: templateId. Optional: preset, profileId. set_card_options: Change technique, paper, format/size or corners. Elements adapt to a new size. Required: nothing else. Optional: corners, glued, glueFirst, paper, backPaper, profileId, technique. rename: Required: name. Optional: none. add_element: Add a text box, shape, QR code (text = the URL; the code is drawn with a white quiet zone, about 80% of the box) or built-in illustration (kind icon with iconId). Any style field can be set at creation. New text is regular weight (fontWeight 400); new shapes have no border and square corners. Text boxes don't grow: give long text enough heightMm. New elements go on top unless behindElementId is given. Required: kind, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). add_image: Place a photo or image: as a new image (target new, default), as the page background (target background), or replacing the picture of an image element (target = its id). Required: image, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). update_element: Change an element's text, position, size, rotation or style, or swap an illustration (iconId). Only the given fields change. Required: elementId. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). delete_element: Required: elementId. Optional: none. set_layer: Change stacking order on its side. Elements stay above the page background: back puts the element just above it. Required: elementId, direction. Optional: none. set_page_background: Set a page's background colour, or use an existing image on that page as its background (elementId). Give one. Required: pageIndex. Optional: backgroundColor, elementId.",
"properties": {
"op": {
"description": "Operation: apply_template, set_card_options, rename, add_element, add_image, update_element, delete_element, set_layer, set_page_background.",
"type": "string"
},
"preset": {
"type": "string",
"description": "Allowed values: \"classic\", \"special\", \"deluxe\"."
},
"profileId": {
"description": "Card size id from list_card_options. set_card_options: Card format and size id from list_card_options. Choose by the format's name, fold and sides (see formatNote there): a card is flat (front and back) unless the person asks for a folded or opening card.",
"type": "string"
},
"templateId": {
"type": "string",
"description": "Allowed values: \"blank\", \"baby_tree\", \"baby_stork\", \"baby_bunny\", \"baby_bw\", \"baby_moon\", \"baby_1\", \"baby_2\", \"baby_bow\", \"baby_elephant\", \"baby_starry\", \"baby_bear\", \"baby_balloon\", \"baby_robin\", \"baby_fox\", \"baby_fawn\", \"baby_meadow\", \"baby_whale\", \"baby_lamb\", \"baby_owl\", \"baby_hedgehog\", \"baby_sailboat\", \"baby_rainbow\", \"baby_wreath\", \"wedding_dunes\", \"wedding_wreath\", \"wedding_1\", \"wedding_pressed\", \"wedding_gold\", \"wedding_farmhouse\", \"wedding_save_date\", \"wedding_summer\", \"wedding_lemons\", \"wedding_doves\", \"wedding_seaside\", \"wedding_blossom\", \"wedding_winter\", \"wedding_tulips\", \"wedding_canal\", \"wedding_windmill\", \"wedding_delft\", \"wedding_tandem\", \"wedding_lavender\", \"wedding_olive\", \"wedding_vineyard\", \"wedding_peonies\", \"wedding_roses\", \"wedding_sunflowers\", \"wedding_autumn\", \"wedding_forest\", \"wedding_mountains\", \"wedding_swans\", \"wedding_champagne\", \"wedding_artdeco\", \"wedding_celestial\", \"wedding_disco\", \"wedding_rings\", \"wedding_cake\", \"wedding_shapes\", \"wedding_rainbow\", \"wedding_pampas\", \"wedding_desert\", \"wedding_tropical\", \"wedding_cherries\", \"wedding_strawberries\", \"wedding_greenhouse\", \"wedding_castle\", \"wedding_paris\", \"wedding_amalfi\", \"wedding_santorini\", \"wedding_cranes\", \"wedding_marigold\", \"wedding_festoon\", \"wedding_festival\", \"wedding_campervan\", \"wedding_sailing\", \"wedding_hearts\", \"wedding_swallows\", \"wedding_butterflies\", \"wedding_bees\", \"wedding_magnolia\", \"wedding_anemones\", \"wedding_dahlias\", \"wedding_wheat\", \"wedding_aurora\", \"wedding_skyline\", \"wedding_oneline\", \"funeral_sea\", \"funeral_willow\", \"funeral_1\", \"thank_you\"."
},
"corners": {
"description": "Corner shape of a rectangular card: square (sharp) or rounded. This is not the card's shape; a square card is a profileId. Allowed values: \"square\", \"rounded\".",
"type": "string"
},
"glued": {
"description": "Flat letterpress, papers under 600 g only: glue a second sheet of the same paper behind the card. By default it's glued after pressing, so no impression shows on the back and the back can be printed freely (at the offer's glued price, see list_card_options). The card gets thicker; its colour doesn't change.",
"type": "boolean"
},
"glueFirst": {
"description": "Glued cards only: glue the two sheets before pressing instead (no surcharge). The card presses like one 600 g sheet, so the impression may show on the back.",
"type": "boolean"
},
"paper": {
"description": "Paper id from list_card_options.",
"type": "string"
},
"backPaper": {
"description": "Glued cards only: the paper id of the sheet glued behind the card, for a card with another colour on the back (one of the technique's papers). The front's paper id or null means the same paper on both sides.",
"type": "string"
},
"technique": {
"type": "string",
"description": "Allowed values: \"digital\", \"letterpress\"."
},
"name": {
"maxLength": 120,
"minLength": 1,
"type": "string"
},
"backgroundColor": {
"description": "Fill colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderColor": {
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderRadiusMm": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"borderWidthMm": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"color": {
"description": "Text colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"finish": {
"description": "Cards only. Text and shapes: foil_* (a foil colour: foil_gold, foil_silver, foil_copper on the foil technique, where foil is a raised 3D layer on top of the print; letterpress offers the printer's foil colours pressed into the paper, also with blind or emboss; the two never mix on one card; colours per technique in list_card_options), print (letterpress, printed in its own colour but not pressed in; use it for text that doesn't need pressing), blind (letterpress, pressed in without colour; without a finish, text and shapes on a letterpress front are printed and pressed in; pressing needs 600 g paper) or emboss (letterpress, raised from the back; nothing may be printed behind it on the inside); none removes it. Images and icons can be blind or emboss only: their visible part is pressed and a transparent background stays flat, so use a transparent PNG with clean, hard edges (soft edges and shadows are pressed all or nothing). On a shape the whole fill becomes foil (there is no foil outline), so keep foil shapes small. Which finishes are allowed depends on the card's technique (list_card_options). Allowed values: \"none\", \"print\", \"foil_white_gold\", \"foil_gold\", \"foil_gold_matte\", \"foil_gold_holo\", \"foil_caramel_gold\", \"foil_caramel_glitter\", \"foil_rose_gold\", \"foil_copper\", \"foil_copper_matte\", \"foil_bronze\", \"foil_brown\", \"foil_white\", \"foil_pearl\", \"foil_silver\", \"foil_silver_holo\", \"foil_light_pink\", \"foil_holo_pink\", \"foil_magenta\", \"foil_cherry_red\", \"foil_lilac\", \"foil_purple\", \"foil_ice_blue_matte\", \"foil_silver_blue\", \"foil_blue\", \"foil_dark_blue_gloss\", \"foil_ocean\", \"foil_spring_green_matte\", \"foil_green\", \"foil_grass_green_gloss\", \"foil_petrol\", \"blind\", \"emboss\".",
"type": "string"
},
"fontFamily": {
"description": "Font ID from list_card_options (fonts), or legacy inter, mono, serif.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"italic\", \"normal\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"heightMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"curve": {
"description": "Text only: bend the text along an arc, -100 to 100. Positive arches up (like a rainbow), negative bows down (like a smile); 0 is straight. Curved text is one line (line breaks become spaces) centred in its box; make the box wide and tall enough for the arc. 30 to 60 is a gentle arch.",
"minimum": -100,
"maximum": 100,
"type": "number"
},
"letterSpacingPt": {
"description": "Extra space after each text grapheme in points (1 pt = 1/72 inch). Default 0. Does not change text or rich-text runs.",
"minimum": -2,
"maximum": 30,
"type": "number"
},
"lineHeight": {
"description": "Text baseline distance as a font-size multiplier. Default 1.35.",
"minimum": 0.5,
"maximum": 5,
"type": "number"
},
"imagePositionX": {
"description": "Horizontal cover crop anchor in percent: 0 left, 50 centre, 100 right. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imagePositionY": {
"description": "Vertical cover crop anchor in percent: 0 top, 50 centre, 100 bottom. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imageZoom": {
"description": "Cover crop zoom multiplier, 1 to 3. Ignored for contain.",
"minimum": 1,
"maximum": 3,
"type": "number"
},
"textRuns": {
"description": "Rich text runs. Concatenated run text must equal text (or the current text on update). Omitted styles inherit the element style; a run's fontFamily, fontSizePt and color override the element's (not on curved text, which uses the element's). An empty array clears rich formatting. Whole-element font style, weight and underline changes also update existing runs, and whole-element font, size and colour changes replace the runs' own, unless textRuns is supplied.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"normal\", \"italic\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"fontFamily": {
"description": "Font ID from list_card_options (fonts) for this run.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"color": {
"description": "Run colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
}
}
}
},
"imageFit": {
"type": "string",
"description": "Allowed values: \"contain\", \"cover\"."
},
"opacity": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"rotation": {
"maximum": 360,
"minimum": -360,
"type": "number"
},
"shadow": {
"type": "string",
"description": "Allowed values: \"none\", \"soft\"."
},
"text": {
"description": "Text content, or the URL for a QR code. On letters, supports tags such as {{first_name}}; cards have no personal fields (every card in an order is the same).",
"maxLength": 5000,
"type": "string"
},
"textAlign": {
"type": "string",
"description": "Allowed values: \"center\", \"left\", \"right\"."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"widthMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"xMm": {
"description": "Left edge in mm from the page's left edge.",
"type": "number"
},
"yMm": {
"description": "Top edge in mm from the page's top edge.",
"type": "number"
},
"behindElementId": {
"description": "Place the new element directly behind this element instead of on top. add_image: Place a new image directly behind this element instead of on top.",
"type": "string"
},
"iconId": {
"description": "Illustration from list_card_options icons. Icons can't be recoloured. update_element: Swap the artwork of an illustration element. Allowed values: \"cardBabyBalloon\", \"cardBabyFox\", \"cardBabyFawn\", \"cardBabyMeadow\", \"cardBabyWhale\", \"cardBabyLamb\", \"cardBabyOwl\", \"cardBabyHedgehog\", \"cardBabySailboat\", \"cardBabyRainbow\", \"cardBabyWreath\", \"cardBabyBear\", \"cardBabyBow\", \"cardBabyBunny\", \"cardBabyElephant\", \"cardBabyFeetBw\", \"cardBabyMoon\", \"cardBabyRobin\", \"cardBabyStarry\", \"cardBabyStork\", \"cardBabyTree\", \"cardFuneralSea\", \"cardFuneralWillow\", \"cardWeddingCouple\", \"cardWeddingPressed\", \"cardWeddingVenue\", \"cardWeddingWreath\", \"cardWeddingSummer\", \"cardWeddingLemons\", \"cardWeddingDoves\", \"cardWeddingSeaside\", \"cardWeddingWinter\", \"cardWeddingBlossom\", \"cardWeddingTulips\", \"cardWeddingCanal\", \"cardWeddingWindmill\", \"cardWeddingDelft\", \"cardWeddingTandem\", \"cardWeddingLavender\", \"cardWeddingOlive\", \"cardWeddingVineyard\", \"cardWeddingPeonies\", \"cardWeddingRoses\", \"cardWeddingSunflowers\", \"cardWeddingAutumn\", \"cardWeddingForest\", \"cardWeddingMountains\", \"cardWeddingSwans\", \"cardWeddingChampagne\", \"cardWeddingArtdeco\", \"cardWeddingCelestial\", \"cardWeddingDisco\", \"cardWeddingRings\", \"cardWeddingCake\", \"cardWeddingShapes\", \"cardWeddingRainbow\", \"cardWeddingPampas\", \"cardWeddingDesert\", \"cardWeddingTropical\", \"cardWeddingCherries\", \"cardWeddingStrawberries\", \"cardWeddingGreenhouse\", \"cardWeddingCastle\", \"cardWeddingParis\", \"cardWeddingAmalfi\", \"cardWeddingSantorini\", \"cardWeddingCranes\", \"cardWeddingMarigold\", \"cardWeddingFestoon\", \"cardWeddingFestival\", \"cardWeddingCampervan\", \"cardWeddingSailing\", \"cardWeddingHearts\", \"cardWeddingSwallows\", \"cardWeddingButterflies\", \"cardWeddingBees\", \"cardWeddingMagnolia\", \"cardWeddingAnemones\", \"cardWeddingDahlias\", \"cardWeddingWheat\", \"cardWeddingAurora\", \"cardWeddingSkyline\", \"cardWeddingOneline\", \"recipeHeart\", \"weddingThankYouConfetti\", \"weddingThankYouDance\", \"weddingThankYouEmbrace\", \"weddingThankYouStrip\", \"weddingThankYouWalk\".",
"type": "string"
},
"id": {
"description": "Optional id for the new element, so later operations in this batch can refer to it. add_image: Optional id for the new image or background image.",
"pattern": "^[A-Za-z0-9_-]{1,40}$",
"type": "string"
},
"kind": {
"type": "string",
"description": "Allowed values: \"text\", \"shape\", \"qr\", \"icon\"."
},
"pageIndex": {
"description": "Flat card: 0 = front, 1 = back. Folded card: each page is the whole open sheet, 0 = outside (front, back and door panels), 1 = inside; design.pages[].panels gives each panel's rectangle.",
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"image": {
"additionalProperties": false,
"description": "A JPEG or PNG, max 5 MB: the assetId of an image uploaded with upload_asset (use this for photos the person shared, or to send base64), or a public HTTPS fileUrl. Give one.",
"properties": {
"assetId": {
"maxLength": 80,
"type": "string"
},
"fileUrl": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
},
"target": {
"description": "new (default): a new image; background: the page background image; or the id of an image element whose picture to replace.",
"type": "string"
},
"elementId": {
"description": "Element id from get_card_design or an earlier operation.",
"type": "string"
},
"direction": {
"type": "string",
"description": "Allowed values: \"front\", \"forward\", \"backward\", \"back\"."
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 50,
"type": "array",
"minItems": 1
},
"previewPages": {
"description": "Sides to return as PNG previews: 0 = front/outside, 1 = back/inside. Default [0, 1] on create and update; [] skips previews.",
"items": {
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"maxItems": 2,
"type": "array"
}
},
"required": [
"draftToken",
"baseVersion",
"operations"
],
"type": "object"
},
"name": "update_card_design",
"title": "Update Card Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true,
"title": "List Letter Options"
},
"description": "List what a designed PieterPost letter can be: starter letters (templateId, name, sample text), postal layouts (A4 with the address window left or right, A4 France, US Letter) with their page size, address window and postal zones in mm and the recipient countries each is printed for, personal fields, built-in illustrations (iconId) and fonts (search with fontQuery). Read-only; no login.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"fontQuery": {
"description": "Search all fonts by family name; returns only fonts unless sections is given.",
"maxLength": 100,
"type": "string"
},
"sections": {
"description": "Which parts to return: templates, layouts, fonts, icons. Default all (only fonts with fontQuery).",
"items": {
"type": "string",
"description": "Allowed values: \"templates\", \"layouts\", \"fonts\", \"icons\"."
},
"type": "array"
}
},
"type": "object"
},
"name": "list_letter_options",
"title": "List Letter Options",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": true,
"readOnlyHint": false,
"title": "Create Letter Design"
},
"description": "Start a designed letter without login: from a starter letter (templateId) or blank, in a postal layout, optionally with a first batch of edits. Returns a private draftToken, an editorUrl where the person can adjust the letter, add recipients and order it from PieterPost, the version, every element by page with its id and style, print issues and PNG previews. Give the editorUrl to the person; it gives edit access, so don't post it publicly. Drafts expire 30 days after their last change. Iterate with update_letter_design. Nothing is printed, paid or sent.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"layoutId": {
"description": "Postal layout from list_letter_options; pingen_a4_left (A4, address window left) by default. Pick the one printed for the recipient's country. Allowed values: \"pingen_a4_left\", \"pingen_a4_right\", \"pingen_fr_a4_right\", \"lob_us_letter\".",
"type": "string"
},
"locale": {
"description": "Language of the editor, e.g. en or nl.",
"maxLength": 10,
"type": "string"
},
"name": {
"description": "Name of the design, shown in the editor.",
"maxLength": 120,
"type": "string"
},
"operations": {
"description": "Edits applied in order, all or nothing (max 50). Element ids come from get_letter_design or earlier results; add_element and add_image take an optional id so later operations in the same call can use it.",
"items": {
"additionalProperties": false,
"description": "One edit; send only the fields its op uses. apply_template: Replace the whole letter with a starter letter from list_letter_options, in the current layout. Required: templateId. Optional: none. set_layout: Switch the postal layout (page size, address window side). Elements are scaled to the new page. Required: layoutId. Optional: none. add_page: Add a blank page after afterPageIndex (default: after the last page), up to 20 pages. Later pages have no address window. Every sheet adds to the price. Required: nothing else. Optional: afterPageIndex. delete_page: Delete a page and everything on it. The first page (0) can't be deleted. Required: pageIndex. Optional: none. rename: Required: name. Optional: none. add_element: Add a text box, shape, QR code (text = the URL; the code is drawn with a white quiet zone, about 80% of the box) or built-in illustration (kind icon with iconId). Any style field can be set at creation. New text is regular weight (fontWeight 400); new shapes have no border and square corners. Text boxes don't grow: give long text enough heightMm. New elements go on top unless behindElementId is given. Required: kind, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). add_image: Place a photo or image: as a new image (target new, default), as the page background (target background), or replacing the picture of an image element (target = its id). Required: image, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). update_element: Change an element's text, position, size, rotation or style, or swap an illustration (iconId). Only the given fields change. Required: elementId. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). delete_element: Required: elementId. Optional: none. set_layer: Change stacking order on its side. Elements stay above the page background: back puts the element just above it. Required: elementId, direction. Optional: none. set_page_background: Set a page's background colour, or use an existing image on that page as its background (elementId). Give one. On page 0 the address window and postal zones stay white. Required: pageIndex. Optional: backgroundColor, elementId.",
"properties": {
"op": {
"description": "Operation: apply_template, set_layout, add_page, delete_page, rename, add_element, add_image, update_element, delete_element, set_layer, set_page_background.",
"type": "string"
},
"templateId": {
"type": "string",
"description": "Allowed values: \"blank\", \"businessLetter\", \"event\", \"invoice\", \"loveLetter\", \"nonprofit\", \"realEstate\", \"recipe\", \"thankYou\", \"travel\", \"welcome\", \"winback\"."
},
"layoutId": {
"type": "string",
"description": "Allowed values: \"pingen_a4_left\", \"pingen_a4_right\", \"pingen_fr_a4_right\", \"lob_us_letter\"."
},
"afterPageIndex": {
"minimum": 0,
"type": "integer"
},
"pageIndex": {
"description": "0-based letter page. Page 0 is the first page, with the address window and postal zones; add pages with add_page.",
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"name": {
"maxLength": 120,
"minLength": 1,
"type": "string"
},
"backgroundColor": {
"description": "Fill colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderColor": {
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderRadiusMm": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"borderWidthMm": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"color": {
"description": "Text colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"fontFamily": {
"description": "Font ID from list_letter_options (fonts), or legacy inter, mono, serif.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"italic\", \"normal\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"heightMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"curve": {
"description": "Text only: bend the text along an arc, -100 to 100. Positive arches up (like a rainbow), negative bows down (like a smile); 0 is straight. Curved text is one line (line breaks become spaces) centred in its box; make the box wide and tall enough for the arc. 30 to 60 is a gentle arch.",
"minimum": -100,
"maximum": 100,
"type": "number"
},
"letterSpacingPt": {
"description": "Extra space after each text grapheme in points (1 pt = 1/72 inch). Default 0. Does not change text or rich-text runs.",
"minimum": -2,
"maximum": 30,
"type": "number"
},
"lineHeight": {
"description": "Text baseline distance as a font-size multiplier. Default 1.35.",
"minimum": 0.5,
"maximum": 5,
"type": "number"
},
"imagePositionX": {
"description": "Horizontal cover crop anchor in percent: 0 left, 50 centre, 100 right. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imagePositionY": {
"description": "Vertical cover crop anchor in percent: 0 top, 50 centre, 100 bottom. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imageZoom": {
"description": "Cover crop zoom multiplier, 1 to 3. Ignored for contain.",
"minimum": 1,
"maximum": 3,
"type": "number"
},
"textRuns": {
"description": "Rich text runs. Concatenated run text must equal text (or the current text on update). Omitted styles inherit the element style; a run's fontFamily, fontSizePt and color override the element's (not on curved text, which uses the element's). An empty array clears rich formatting. Whole-element font style, weight and underline changes also update existing runs, and whole-element font, size and colour changes replace the runs' own, unless textRuns is supplied.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"normal\", \"italic\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"fontFamily": {
"description": "Font ID from list_letter_options (fonts) for this run.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"color": {
"description": "Run colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
}
}
}
},
"imageFit": {
"type": "string",
"description": "Allowed values: \"contain\", \"cover\"."
},
"opacity": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"rotation": {
"maximum": 360,
"minimum": -360,
"type": "number"
},
"shadow": {
"type": "string",
"description": "Allowed values: \"none\", \"soft\"."
},
"text": {
"description": "Text content, or the URL for a QR code. Personal fields such as {{first_name}} are filled in per recipient.",
"maxLength": 5000,
"type": "string"
},
"textAlign": {
"type": "string",
"description": "Allowed values: \"center\", \"left\", \"right\"."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"widthMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"xMm": {
"description": "Left edge in mm from the page's left edge.",
"type": "number"
},
"yMm": {
"description": "Top edge in mm from the page's top edge.",
"type": "number"
},
"behindElementId": {
"description": "Place the new element directly behind this element instead of on top. add_image: Place a new image directly behind this element instead of on top.",
"type": "string"
},
"iconId": {
"description": "Illustration from list_letter_options icons. Icons can't be recoloured. update_element: Swap the artwork of an illustration element. Allowed values: \"cardBabyBalloon\", \"cardBabyFox\", \"cardBabyFawn\", \"cardBabyMeadow\", \"cardBabyWhale\", \"cardBabyLamb\", \"cardBabyOwl\", \"cardBabyHedgehog\", \"cardBabySailboat\", \"cardBabyRainbow\", \"cardBabyWreath\", \"cardBabyBear\", \"cardBabyBow\", \"cardBabyBunny\", \"cardBabyElephant\", \"cardBabyFeetBw\", \"cardBabyMoon\", \"cardBabyRobin\", \"cardBabyStarry\", \"cardBabyStork\", \"cardBabyTree\", \"cardFuneralSea\", \"cardFuneralWillow\", \"cardWeddingCouple\", \"cardWeddingPressed\", \"cardWeddingVenue\", \"cardWeddingWreath\", \"cardWeddingSummer\", \"cardWeddingLemons\", \"cardWeddingDoves\", \"cardWeddingSeaside\", \"cardWeddingWinter\", \"cardWeddingBlossom\", \"cardWeddingTulips\", \"cardWeddingCanal\", \"cardWeddingWindmill\", \"cardWeddingDelft\", \"cardWeddingTandem\", \"cardWeddingLavender\", \"cardWeddingOlive\", \"cardWeddingVineyard\", \"cardWeddingPeonies\", \"cardWeddingRoses\", \"cardWeddingSunflowers\", \"cardWeddingAutumn\", \"cardWeddingForest\", \"cardWeddingMountains\", \"cardWeddingSwans\", \"cardWeddingChampagne\", \"cardWeddingArtdeco\", \"cardWeddingCelestial\", \"cardWeddingDisco\", \"cardWeddingRings\", \"cardWeddingCake\", \"cardWeddingShapes\", \"cardWeddingRainbow\", \"cardWeddingPampas\", \"cardWeddingDesert\", \"cardWeddingTropical\", \"cardWeddingCherries\", \"cardWeddingStrawberries\", \"cardWeddingGreenhouse\", \"cardWeddingCastle\", \"cardWeddingParis\", \"cardWeddingAmalfi\", \"cardWeddingSantorini\", \"cardWeddingCranes\", \"cardWeddingMarigold\", \"cardWeddingFestoon\", \"cardWeddingFestival\", \"cardWeddingCampervan\", \"cardWeddingSailing\", \"cardWeddingHearts\", \"cardWeddingSwallows\", \"cardWeddingButterflies\", \"cardWeddingBees\", \"cardWeddingMagnolia\", \"cardWeddingAnemones\", \"cardWeddingDahlias\", \"cardWeddingWheat\", \"cardWeddingAurora\", \"cardWeddingSkyline\", \"cardWeddingOneline\", \"checkmark\", \"loveLetterPhoto\", \"love\", \"pie\", \"recipeAccent\", \"recipeFlour\", \"recipeHeart\", \"recipeHeader\", \"typewriter\", \"weddingThankYouConfetti\", \"weddingThankYouDance\", \"weddingThankYouEmbrace\", \"weddingThankYouStrip\", \"weddingThankYouWalk\".",
"type": "string"
},
"id": {
"description": "Optional id for the new element, so later operations in this batch can refer to it. add_image: Optional id for the new image or background image.",
"pattern": "^[A-Za-z0-9_-]{1,40}$",
"type": "string"
},
"kind": {
"type": "string",
"description": "Allowed values: \"text\", \"shape\", \"qr\", \"icon\"."
},
"image": {
"additionalProperties": false,
"description": "A JPEG or PNG, max 5 MB: the assetId of an image uploaded with upload_asset (use this for photos the person shared, or to send base64), or a public HTTPS fileUrl. Give one.",
"properties": {
"assetId": {
"maxLength": 80,
"type": "string"
},
"fileUrl": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
},
"target": {
"description": "new (default): a new image; background: the page background image; or the id of an image element whose picture to replace.",
"type": "string"
},
"elementId": {
"description": "Element id from get_letter_design or an earlier operation.",
"type": "string"
},
"direction": {
"type": "string",
"description": "Allowed values: \"front\", \"forward\", \"backward\", \"back\"."
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 50,
"type": "array"
},
"previewPages": {
"description": "Pages to return as PNG previews (0-based, at most 4). Default: the first two pages on create and update; [] skips previews. Page 0 shows a grey sample address where the recipient's address is printed.",
"items": {
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"maxItems": 4,
"type": "array"
},
"templateId": {
"description": "Starter letter from list_letter_options; blank by default. Allowed values: \"blank\", \"businessLetter\", \"event\", \"invoice\", \"loveLetter\", \"nonprofit\", \"realEstate\", \"recipe\", \"thankYou\", \"travel\", \"welcome\", \"winback\".",
"type": "string"
}
},
"type": "object"
},
"name": "create_letter_design",
"title": "Create Letter Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true,
"title": "Read Letter Design"
},
"description": "Read the current letter design, including edits the person made in the editor since your last call: version, layout and postal zones, every element by page with its id and style, print issues and optional PNG previews. Call it before editing when time has passed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draftToken": {
"description": "draftToken returned by create_letter_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"previewPages": {
"description": "Pages to preview (0-based); none by default.",
"items": {
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"maxItems": 4,
"type": "array"
}
},
"required": [
"draftToken"
],
"type": "object"
},
"name": "get_letter_design",
"title": "Read Letter Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
},
{
"annotations": {
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": true,
"readOnlyHint": false,
"title": "Update Letter Design"
},
"description": "Edit a letter design: change texts, fonts, colours, positions, images, background, pages or postal layout with a batch of operations. Pass the version you last saw as baseVersion; if the person changed the design in the editor meanwhile, nothing is applied and the error returns the current design to edit instead. Returns the new version, elements, issues and PNG previews. The editorUrl stays the same.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"baseVersion": {
"description": "version from the latest create, get or update result.",
"minimum": 1,
"type": "integer"
},
"draftToken": {
"description": "draftToken returned by create_letter_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"operations": {
"description": "Edits applied in order, all or nothing (max 50). Element ids come from get_letter_design or earlier results; add_element and add_image take an optional id so later operations in the same call can use it.",
"items": {
"additionalProperties": false,
"description": "One edit; send only the fields its op uses. apply_template: Replace the whole letter with a starter letter from list_letter_options, in the current layout. Required: templateId. Optional: none. set_layout: Switch the postal layout (page size, address window side). Elements are scaled to the new page. Required: layoutId. Optional: none. add_page: Add a blank page after afterPageIndex (default: after the last page), up to 20 pages. Later pages have no address window. Every sheet adds to the price. Required: nothing else. Optional: afterPageIndex. delete_page: Delete a page and everything on it. The first page (0) can't be deleted. Required: pageIndex. Optional: none. rename: Required: name. Optional: none. add_element: Add a text box, shape, QR code (text = the URL; the code is drawn with a white quiet zone, about 80% of the box) or built-in illustration (kind icon with iconId). Any style field can be set at creation. New text is regular weight (fontWeight 400); new shapes have no border and square corners. Text boxes don't grow: give long text enough heightMm. New elements go on top unless behindElementId is given. Required: kind, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). add_image: Place a photo or image: as a new image (target new, default), as the page background (target background), or replacing the picture of an image element (target = its id). Required: image, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). update_element: Change an element's text, position, size, rotation or style, or swap an illustration (iconId). Only the given fields change. Required: elementId. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). delete_element: Required: elementId. Optional: none. set_layer: Change stacking order on its side. Elements stay above the page background: back puts the element just above it. Required: elementId, direction. Optional: none. set_page_background: Set a page's background colour, or use an existing image on that page as its background (elementId). Give one. On page 0 the address window and postal zones stay white. Required: pageIndex. Optional: backgroundColor, elementId.",
"properties": {
"op": {
"description": "Operation: apply_template, set_layout, add_page, delete_page, rename, add_element, add_image, update_element, delete_element, set_layer, set_page_background.",
"type": "string"
},
"templateId": {
"type": "string",
"description": "Allowed values: \"blank\", \"businessLetter\", \"event\", \"invoice\", \"loveLetter\", \"nonprofit\", \"realEstate\", \"recipe\", \"thankYou\", \"travel\", \"welcome\", \"winback\"."
},
"layoutId": {
"type": "string",
"description": "Allowed values: \"pingen_a4_left\", \"pingen_a4_right\", \"pingen_fr_a4_right\", \"lob_us_letter\"."
},
"afterPageIndex": {
"minimum": 0,
"type": "integer"
},
"pageIndex": {
"description": "0-based letter page. Page 0 is the first page, with the address window and postal zones; add pages with add_page.",
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"name": {
"maxLength": 120,
"minLength": 1,
"type": "string"
},
"backgroundColor": {
"description": "Fill colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderColor": {
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderRadiusMm": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"borderWidthMm": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"color": {
"description": "Text colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"fontFamily": {
"description": "Font ID from list_letter_options (fonts), or legacy inter, mono, serif.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"italic\", \"normal\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"heightMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"curve": {
"description": "Text only: bend the text along an arc, -100 to 100. Positive arches up (like a rainbow), negative bows down (like a smile); 0 is straight. Curved text is one line (line breaks become spaces) centred in its box; make the box wide and tall enough for the arc. 30 to 60 is a gentle arch.",
"minimum": -100,
"maximum": 100,
"type": "number"
},
"letterSpacingPt": {
"description": "Extra space after each text grapheme in points (1 pt = 1/72 inch). Default 0. Does not change text or rich-text runs.",
"minimum": -2,
"maximum": 30,
"type": "number"
},
"lineHeight": {
"description": "Text baseline distance as a font-size multiplier. Default 1.35.",
"minimum": 0.5,
"maximum": 5,
"type": "number"
},
"imagePositionX": {
"description": "Horizontal cover crop anchor in percent: 0 left, 50 centre, 100 right. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imagePositionY": {
"description": "Vertical cover crop anchor in percent: 0 top, 50 centre, 100 bottom. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imageZoom": {
"description": "Cover crop zoom multiplier, 1 to 3. Ignored for contain.",
"minimum": 1,
"maximum": 3,
"type": "number"
},
"textRuns": {
"description": "Rich text runs. Concatenated run text must equal text (or the current text on update). Omitted styles inherit the element style; a run's fontFamily, fontSizePt and color override the element's (not on curved text, which uses the element's). An empty array clears rich formatting. Whole-element font style, weight and underline changes also update existing runs, and whole-element font, size and colour changes replace the runs' own, unless textRuns is supplied.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"normal\", \"italic\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"fontFamily": {
"description": "Font ID from list_letter_options (fonts) for this run.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"color": {
"description": "Run colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
}
}
}
},
"imageFit": {
"type": "string",
"description": "Allowed values: \"contain\", \"cover\"."
},
"opacity": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"rotation": {
"maximum": 360,
"minimum": -360,
"type": "number"
},
"shadow": {
"type": "string",
"description": "Allowed values: \"none\", \"soft\"."
},
"text": {
"description": "Text content, or the URL for a QR code. Personal fields such as {{first_name}} are filled in per recipient.",
"maxLength": 5000,
"type": "string"
},
"textAlign": {
"type": "string",
"description": "Allowed values: \"center\", \"left\", \"right\"."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"widthMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"xMm": {
"description": "Left edge in mm from the page's left edge.",
"type": "number"
},
"yMm": {
"description": "Top edge in mm from the page's top edge.",
"type": "number"
},
"behindElementId": {
"description": "Place the new element directly behind this element instead of on top. add_image: Place a new image directly behind this element instead of on top.",
"type": "string"
},
"iconId": {
"description": "Illustration from list_letter_options icons. Icons can't be recoloured. update_element: Swap the artwork of an illustration element. Allowed values: \"cardBabyBalloon\", \"cardBabyFox\", \"cardBabyFawn\", \"cardBabyMeadow\", \"cardBabyWhale\", \"cardBabyLamb\", \"cardBabyOwl\", \"cardBabyHedgehog\", \"cardBabySailboat\", \"cardBabyRainbow\", \"cardBabyWreath\", \"cardBabyBear\", \"cardBabyBow\", \"cardBabyBunny\", \"cardBabyElephant\", \"cardBabyFeetBw\", \"cardBabyMoon\", \"cardBabyRobin\", \"cardBabyStarry\", \"cardBabyStork\", \"cardBabyTree\", \"cardFuneralSea\", \"cardFuneralWillow\", \"cardWeddingCouple\", \"cardWeddingPressed\", \"cardWeddingVenue\", \"cardWeddingWreath\", \"cardWeddingSummer\", \"cardWeddingLemons\", \"cardWeddingDoves\", \"cardWeddingSeaside\", \"cardWeddingWinter\", \"cardWeddingBlossom\", \"cardWeddingTulips\", \"cardWeddingCanal\", \"cardWeddingWindmill\", \"cardWeddingDelft\", \"cardWeddingTandem\", \"cardWeddingLavender\", \"cardWeddingOlive\", \"cardWeddingVineyard\", \"cardWeddingPeonies\", \"cardWeddingRoses\", \"cardWeddingSunflowers\", \"cardWeddingAutumn\", \"cardWeddingForest\", \"cardWeddingMountains\", \"cardWeddingSwans\", \"cardWeddingChampagne\", \"cardWeddingArtdeco\", \"cardWeddingCelestial\", \"cardWeddingDisco\", \"cardWeddingRings\", \"cardWeddingCake\", \"cardWeddingShapes\", \"cardWeddingRainbow\", \"cardWeddingPampas\", \"cardWeddingDesert\", \"cardWeddingTropical\", \"cardWeddingCherries\", \"cardWeddingStrawberries\", \"cardWeddingGreenhouse\", \"cardWeddingCastle\", \"cardWeddingParis\", \"cardWeddingAmalfi\", \"cardWeddingSantorini\", \"cardWeddingCranes\", \"cardWeddingMarigold\", \"cardWeddingFestoon\", \"cardWeddingFestival\", \"cardWeddingCampervan\", \"cardWeddingSailing\", \"cardWeddingHearts\", \"cardWeddingSwallows\", \"cardWeddingButterflies\", \"cardWeddingBees\", \"cardWeddingMagnolia\", \"cardWeddingAnemones\", \"cardWeddingDahlias\", \"cardWeddingWheat\", \"cardWeddingAurora\", \"cardWeddingSkyline\", \"cardWeddingOneline\", \"checkmark\", \"loveLetterPhoto\", \"love\", \"pie\", \"recipeAccent\", \"recipeFlour\", \"recipeHeart\", \"recipeHeader\", \"typewriter\", \"weddingThankYouConfetti\", \"weddingThankYouDance\", \"weddingThankYouEmbrace\", \"weddingThankYouStrip\", \"weddingThankYouWalk\".",
"type": "string"
},
"id": {
"description": "Optional id for the new element, so later operations in this batch can refer to it. add_image: Optional id for the new image or background image.",
"pattern": "^[A-Za-z0-9_-]{1,40}$",
"type": "string"
},
"kind": {
"type": "string",
"description": "Allowed values: \"text\", \"shape\", \"qr\", \"icon\"."
},
"image": {
"additionalProperties": false,
"description": "A JPEG or PNG, max 5 MB: the assetId of an image uploaded with upload_asset (use this for photos the person shared, or to send base64), or a public HTTPS fileUrl. Give one.",
"properties": {
"assetId": {
"maxLength": 80,
"type": "string"
},
"fileUrl": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
},
"target": {
"description": "new (default): a new image; background: the page background image; or the id of an image element whose picture to replace.",
"type": "string"
},
"elementId": {
"description": "Element id from get_letter_design or an earlier operation.",
"type": "string"
},
"direction": {
"type": "string",
"description": "Allowed values: \"front\", \"forward\", \"backward\", \"back\"."
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 50,
"type": "array",
"minItems": 1
},
"previewPages": {
"description": "Pages to return as PNG previews (0-based, at most 4). Default: the first two pages on create and update; [] skips previews. Page 0 shows a grey sample address where the recipient's address is printed.",
"items": {
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"maxItems": 4,
"type": "array"
}
},
"required": [
"draftToken",
"baseVersion",
"operations"
],
"type": "object"
},
"name": "update_letter_design",
"title": "Update Letter Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
},
"securitySchemes": [
{
"type": "noauth"
}
],
"_meta": {
"securitySchemes": [
{
"type": "noauth"
}
]
}
}
]
}
\`\`\`
## Account MCP: OAuth client setup
PieterPost exposes a remote MCP server with OAuth authorization code, PKCE, dynamic client registration, short-lived bearer tokens, refresh tokens, and revocation.
\`\`\`json
{
"allowed_tools": [
"search",
"fetch",
"list_address_book_contacts",
"get_address_book_contact",
"create_address_book_contact",
"update_address_book_contact",
"delete_address_book_contact",
"quote_order",
"upload_asset",
"create_compose_link",
"create_payment_link",
"create_checkout_link",
"create_direct_order",
"get_wallet",
"get_order",
"get_topup",
"list_topups",
"create_credit_topup",
"list_api_keys",
"create_api_key",
"revoke_api_key"
],
"require_approval": {
"never": {
"read_only": true
}
},
"server_label": "pieterpost",
"server_url": "https://pieterpost.com/mcp/setup/",
"type": "mcp"
}
\`\`\`
## OAuth and metadata
- OAuth issuer: \`https://pieterpost.com/mcp/oauth\`
- Protected resource metadata: \`https://pieterpost.com/.well-known/oauth-protected-resource/mcp/setup/\`
- Protected resource convenience URL: \`https://pieterpost.com/mcp/setup/.well-known/oauth-protected-resource/\`
- Authorization server metadata: \`https://pieterpost.com/.well-known/oauth-authorization-server/mcp/oauth/\`
- Authorization server issuer-relative metadata: \`https://pieterpost.com/mcp/oauth/.well-known/oauth-authorization-server/\`
- Dynamic client registration: \`https://pieterpost.com/mcp/oauth/register/\`
- Token endpoint: \`https://pieterpost.com/mcp/oauth/token/\`
- Revocation endpoint: \`https://pieterpost.com/mcp/oauth/revoke/\`
- Bearer challenges use \`realm="PieterPost MCP"\` and point \`resource_metadata\` at the protected resource metadata URL.
- Supported scopes: \`api:read\`, \`api:send\`, \`api:keys\`, \`address-book:read\`, \`address-book:write\`.
- \`api:read\` permits \`search\`, \`fetch\`, \`get_wallet\`, and \`get_order\`.
- \`api:read\` also permits \`quote_order\`, \`get_topup\`, and \`list_topups\`.
- \`api:send\` permits uploads, compose links, payment links, checkout links, direct orders, and credit top-ups.
- \`api:keys\` permits listing, creating, and revoking public API keys.
- \`address-book:read\` permits listing, searching, and fetching saved Address Book contacts.
- \`address-book:write\` permits creating, updating, and deleting saved Address Book contacts.
## Account safety model
- Test mode is the default for writable tools unless \`mode: "live"\` is provided.
- Hosted payment and checkout links do not send mail until checkout is paid.
- Live \`create_direct_order\` sends real mail and spends wallet credits. Include \`confirmLiveSend: true\` plus \`maxAmountCents\` greater than or equal to the calculated total when the calling agent selects direct send.
- Pass the intended final letter or postcard text exactly, including line breaks and any template placeholders or recipient customFields.
- API key creation returns the secret once. Existing key secrets cannot be fetched later.
- Uploads accept \`fileBase64\` or a public HTTPS \`fileUrl\`; localhost, private network, and metadata host URLs are rejected.
- Tool annotations describe read and write effects so each host agent can apply its own approval policy.
- Use \`idempotencyKey\` on every create operation. This is especially important for live direct sends, checkout links, and wallet top-ups.
## Account mail payload parity
MCP order tools accept the same letter and postcard payloads as the public API, with \`idempotencyKey\` passed in the tool arguments instead of an HTTP header.
- Letters use \`requestType: "letter"\` and a \`letters\` array. Up to 25 letters are allowed per request.
- Each letter can include a \`message\`, up to 3 \`letter-attachment\` asset IDs, or both. In letter template mode, \`templateMessage\` can supply the shared message for each recipient.
- Letter template mode uses \`composeMode: "template"\`, \`templateMessage\`, optional \`variableKeys\`, and recipient \`customFields\`.
- Letters accept \`deliveryService: "standard"\` (default) or \`"registered"\` on preparation, quotes, full-payload checkout/payment links, and direct orders. Registered mail uses the supported destination service; US recipients use Certified Mail with return receipt. The server checks availability, page limits, and provider prices before creating an order. The choice applies to all recipients in the request and is returned with prepared letters and quotes. Postcards do not support registered delivery.
- Read postal progress with \`get_order\` using \`orderId\`. Its \`delivery\` object includes per-recipient statuses, tracking numbers/URLs when available, delivered dates, estimates, and a status-page URL. \`fulfilled\` means submission for printing and posting, not delivery. Delivery data stays available through the existing status-record retention after message content is removed. Bulk delivery results use \`deliveryOffset\`, \`deliveryLimit\` (1 to 25), and \`delivery.nextOffset\`. Test mode has no live tracking.
- Business accounts use the saved logo in the letter stamp design by default. Set \`useBusinessLogo: false\` to send without it. A \`stampImageAssetId\` from \`upload_asset\` always overrides the saved logo.
- Postcards use \`requestType: "postcard"\` and a \`postcard\` object with \`recipient\` or \`recipients\`. Up to 25 postcard recipients are allowed per request.
- Postcards can use the default front image or an uploaded custom one. Custom postcard fronts must be square, with a 1:1 aspect ratio. For a custom front, use \`upload_asset\` with \`kind: "postcard-image"\`, then pass the returned asset as \`postcard.frontImageAssetId\`.
- Hosted checkout tools default to \`paymentMethod: "auto"\`. For EUR letter or postcard payment links and EUR wallet top-ups, auto offers both card and iDEAL in Stripe Checkout. Pass \`paymentMethod: "card"\` or \`paymentMethod: "ideal"\` only when the user explicitly wants one method.
- Recipients can use \`addressLines\`, or structured address fields such as \`streetAddress\`, \`street\`, \`number\`, \`postalCode\`, \`city\`, \`state\`, and \`country\`. Free-form address parsing is not performed.
- US address review may return \`addressWarnings\` from \`quote_order\` or a create tool. The calling agent can correct the address or repeat with \`acceptUsAddressWarnings: true\` when it accepts the warning. Undeliverable addresses are blocked.
- Metadata accepts up to 20 string, number, or boolean values.
## Address Book contacts
- Use \`list_address_book_contacts\` with a query when the user names a saved contact, for example \`Eric\`.
- Use \`get_address_book_contact\` when you already have a contact id.
- Contact results include a \`recipient\` object that can be passed directly into \`quote_order\`, \`create_payment_link\`, \`create_checkout_link\`, \`create_direct_order\`, or \`create_compose_link\`.
- Use \`create_address_book_contact\`, \`update_address_book_contact\`, and \`delete_address_book_contact\` for contact CRUD. Address input must be structured; free-form address parsing is not performed.
- Example flow: if the user says, \`send a postcard to Bart\`, call \`list_address_book_contacts\` with \`query: "Bart"\`; if exactly one contact matches, use that contact's \`recipient\` object in \`quote_order\`, then continue with \`create_payment_link\`, \`create_compose_link\`, \`create_checkout_link\`, or \`create_direct_order\` according to the calling agent's policy. If multiple contacts match, resolve which Bart is intended before creating mail.
## Account live send flow
1. Do not call \`create_api_key\` unless the user explicitly asked for a public API key. MCP uses internal action keys automatically.
2. Call \`quote_order\` with the final letter or postcard payload.
3. Use the intended final text, including line breaks and any template variables or customFields.
4. Call \`create_payment_link\` with \`mode: "live"\` and a stable \`idempotencyKey\`. \`senderEmail\` is optional; Stripe Checkout collects the payer email when omitted. \`returnUrl\` is optional; PieterPost uses a hosted MCP return page when it is omitted, localized by \`locale\` and labeled as a letter or postcard.
5. Send the returned \`paymentLinkUrl\` to the user. Prefer \`paymentLinkUrl\`/\`publicCheckoutUrl\` over the raw Stripe \`checkoutUrl\` when both are present. PieterPost sends the mail only after Stripe confirms checkout payment.
6. Keep the API/credit path available when the calling agent selects API keys, wallet credits, top-ups, direct send, or an automated trusted workflow: \`get_wallet\`, \`quote_order\`, \`create_credit_topup\` if needed, then \`create_direct_order\`.
## Account tools summary
- \`search\`: Search PieterPost API docs and the authenticated API account summary, keys, wallets, orders, activity, and MCP connections.
- \`fetch\`: Fetch a PieterPost API document or account resource returned by the search tool.
- \`list_address_book_contacts\`: List or search saved Address Book contacts for the authenticated PieterPost user. Use query for name, email, or address searches. Each result includes a recipient object that can be passed into letter or postcard payloads.
- \`get_address_book_contact\`: Fetch one saved Address Book contact by id. The result includes a recipient object for letter or postcard payloads.
- \`create_address_book_contact\`: Create a saved Address Book contact for later letter or postcard sending. Requires structured address fields; free-form address parsing is not performed.
- \`update_address_book_contact\`: Update a saved Address Book contact. Provide contactId and only the fields to change; omitted fields keep their existing values.
- \`delete_address_book_contact\`: Delete one saved Address Book contact by id.
- \`create_compose_link\`: Create a PieterPost compose link for one prepared recipient and optional message. The user reviews, edits, and pays in PieterPost.
- \`prepare_letter\`: Validate, price, and persist an immutable prepared letter before payment. Set deliveryService=registered for registered mail or US Certified Mail; standard is the default. The result contains preparedOrderRef for create_payment_link and an exact native MPP endpoint/body for clients that support the complete MPP 402 flow.
- \`prepare_postcard\`: Validate, price, and persist an immutable prepared postcard before payment. The result contains preparedOrderRef for create_payment_link and an exact native MPP endpoint/body for clients that support the complete MPP 402 flow.
- \`quote_order\`: Validate and price a letter or postcard payload without creating an order. Provide exactly one of letters or postcard. Use this before live direct-send flows to confirm the amount, wallet balance gap, and next action.
- \`create_payment_link\`: Create a hosted payment link for one-off MCP letter or postcard sending without public API keys or wallet credits. Pass preparedOrderRef from prepare_letter or prepare_postcard with a new draft-scoped idempotencyKey, or retain the backward-compatible full payload form with exactly one of letters or postcard. Mail is sent only after checkout is paid. senderEmail and returnUrl remain optional for full-payload calls.
- \`create_checkout_link\`: Create a hosted checkout link for letters or postcards. This is the public-API-compatible name for create_payment_link. Provide exactly one of letters or postcard. Supports bulk letters, letter template mode, custom letter stamps, bulk postcard recipients up to 25 recipients, letter attachments, and optional square 1:1 custom postcard front images. Mail is sent only after checkout is paid. senderEmail is optional for MCP calls; Stripe Checkout collects the payer email when omitted. returnUrl is optional for MCP calls.
- \`create_direct_order\`: Create a direct-send order paid from wallet credits. Provide exactly one of letters or postcard. Supports bulk letters and postcards with the same payload shape as hosted checkout. Test mode simulates sending. Live mode sends real mail and requires confirmLiveSend=true plus maxAmountCents >= the calculated total.
- \`upload_asset\`: Upload a square 1:1 postcard front image, letter attachment, or custom letter stamp for later use in create_checkout_link or create_direct_order. Provide exactly one of fileBase64 or a public HTTPS fileUrl. Returns an assetId that can be passed as postcard.frontImageAssetId, stampImageAssetId, or in a letter attachments array.
- \`get_wallet\`: Read the API wallet balance and account capability flags for test or live mode.
- \`get_order\`: Fetch an API order by id, including payment/fulfillment state and postal delivery status. delivery contains per-recipient status, tracking number/link when available, delivered date, estimates, and a status-page link. fulfilled means submission for printing and posting, not delivery. Use deliveryOffset and deliveryLimit (1-25, default 25) for bulk orders.
- \`get_topup\`: Fetch a PieterPost wallet top-up by id, including payment status and checkout URL when still pending.
- \`list_topups\`: List recent PieterPost wallet top-ups for this account. Use mode and currency filters to inspect the active live or test funding history.
- \`create_credit_topup\`: Create a test credit top-up immediately, or create a live Stripe checkout URL for adding API credits used by direct-send orders. paymentMethod=auto is the default; for EUR top-ups it offers both card and iDEAL. Pass paymentMethod=card or paymentMethod=ideal only when the user wants to force one method.
- \`list_api_keys\`: List API key metadata for this PieterPost API account. Secrets are never returned.
- \`create_api_key\`: Create a new PieterPost public API key. The secret is returned once and cannot be recovered later.
- \`revoke_api_key\`: Revoke an existing PieterPost public API key by id.
- \`list_card_options\`: List what a PieterPost card can be: starter designs (templateId, name, occasion, format, sample text), material presets, formats and sizes (profileId), print techniques (standard print, foil, letterpress) with their papers, finishes and rules, letterpress inks, built-in illustrations (iconId) and fonts (search with fontQuery). Read-only; no login.
- \`create_card_design\`: Start a printed greeting card design without login: from a starter design (templateId) or blank, optionally with a material preset, size and a first batch of edits. Returns a private draftToken, an editorUrl where the person can adjust the card and order it from PieterPost, the version, every element with its id and style, technique issues and PNG previews. Give the editorUrl to the person; it gives edit access, so don't post it publicly. Drafts expire 30 days after their last change. Iterate with update_card_design. Call get_card_preview for each side to inspect the rendered card. Nothing is printed, paid or sent.
- \`get_card_design\`: Read the current card design, including edits the person made in the editor since your last call: version, every element with its id and style, layout rules, technique issues and optional PNG previews. Call it before editing when time has passed. Use get_card_preview to inspect the rendered card.
- \`get_card_preview\`: View one rendered card side as a PNG image. Call after creating or editing a card to inspect its actual appearance. Returns text and image content only, so ChatGPT can see the pixels. Read-only: does not change, order, pay for, print or send the card. Read design data and print warnings with get_card_design.
- \`update_card_design\`: Edit a card design: change texts, fonts, colours, positions, images, background, technique, paper or size with a batch of operations. Pass the version you last saw as baseVersion; if the person changed the design in the editor meanwhile, nothing is applied and the error returns the current design to edit instead. Returns the new version, elements, issues and PNG previews. The editorUrl stays the same. Call get_card_preview for each side after editing.
- \`list_letter_options\`: List what a designed PieterPost letter can be: starter letters (templateId, name, sample text), postal layouts (A4 with the address window left or right, A4 France, US Letter) with their page size, address window and postal zones in mm and the recipient countries each is printed for, personal fields, built-in illustrations (iconId) and fonts (search with fontQuery). Read-only; no login.
- \`create_letter_design\`: Start a designed letter without login: from a starter letter (templateId) or blank, in a postal layout, optionally with a first batch of edits. Returns a private draftToken, an editorUrl where the person can adjust the letter, add recipients and order it from PieterPost, the version, every element by page with its id and style, print issues and PNG previews. Give the editorUrl to the person; it gives edit access, so don't post it publicly. Drafts expire 30 days after their last change. Iterate with update_letter_design. Nothing is printed, paid or sent.
- \`get_letter_design\`: Read the current letter design, including edits the person made in the editor since your last call: version, layout and postal zones, every element by page with its id and style, print issues and optional PNG previews. Call it before editing when time has passed.
- \`update_letter_design\`: Edit a letter design: change texts, fonts, colours, positions, images, background, pages or postal layout with a batch of operations. Pass the version you last saw as baseVersion; if the person changed the design in the editor meanwhile, nothing is applied and the error returns the current design to edit instead. Returns the new version, elements, issues and PNG previews. The editorUrl stays the same.
## Account tool input schemas
The following JSON is the account endpoint tools/list schema. These tools require OAuth and are not part of the public connector.
The schema is intentionally flattened for Codex-style clients, so allowed values and constraints are described in text instead of unsupported JSON Schema keywords such as \`enum\`, \`format\`, or nested unions.
\`\`\`json
{
"tools": [
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Search PieterPost API docs and the authenticated API account summary, keys, wallets, orders, activity, and MCP connections.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"query": {
"description": "Search query.",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "search",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"title": "Search PieterPost"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Fetch a PieterPost API document or account resource returned by the search tool.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"id": {
"description": "Document id returned by search.",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"name": "fetch",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"title": "Fetch PieterPost Context"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "List or search saved Address Book contacts for the authenticated PieterPost user. Use query for name, email, or address searches. Each result includes a recipient object that can be passed into letter or postcard payloads.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"limit": {
"description": "Maximum number of contacts to return. Defaults to 25; maximum 100.",
"type": "number"
},
"query": {
"description": "Optional search query, such as a contact name, email, city, or street.",
"type": "string"
}
},
"type": "object"
},
"name": "list_address_book_contacts",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"title": "List Address Book Contacts"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Fetch one saved Address Book contact by id. The result includes a recipient object for letter or postcard payloads.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"contactId": {
"description": "Address Book contact id.",
"type": "string"
}
},
"required": [
"contactId"
],
"type": "object"
},
"name": "get_address_book_contact",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"title": "Get Address Book Contact"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Create a saved Address Book contact for later letter or postcard sending. Requires structured address fields; free-form address parsing is not performed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"birthday": {
"description": "Optional birthday in YYYY-MM-DD format.",
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"displayName": {
"description": "Saved contact display name.",
"type": "string"
},
"email": {
"description": "Optional contact email.",
"type": "string"
},
"extra": {
"description": "Optional address extra line, such as apartment, company, or care-of details.",
"type": "string"
},
"houseNumber": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"description": "State, province, region, or subdivision when applicable.",
"type": "string"
},
"street": {
"type": "string"
}
},
"required": [
"displayName",
"street",
"houseNumber",
"postalCode",
"city",
"country"
],
"type": "object"
},
"name": "create_address_book_contact",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"title": "Create Address Book Contact"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Update a saved Address Book contact. Provide contactId and only the fields to change; omitted fields keep their existing values.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"contactId": {
"description": "Address Book contact id.",
"type": "string"
},
"birthday": {
"description": "Optional birthday in YYYY-MM-DD format.",
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"displayName": {
"description": "Saved contact display name.",
"type": "string"
},
"email": {
"description": "Optional contact email.",
"type": "string"
},
"extra": {
"description": "Optional address extra line, such as apartment, company, or care-of details.",
"type": "string"
},
"houseNumber": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"description": "State, province, region, or subdivision when applicable.",
"type": "string"
},
"street": {
"type": "string"
}
},
"required": [
"contactId"
],
"type": "object"
},
"name": "update_address_book_contact",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"title": "Update Address Book Contact"
},
{
"annotations": {
"destructiveHint": true,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Delete one saved Address Book contact by id.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"contactId": {
"description": "Address Book contact id.",
"type": "string"
}
},
"required": [
"contactId"
],
"type": "object"
},
"name": "delete_address_book_contact",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"title": "Delete Address Book Contact"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Create a PieterPost compose link for one prepared recipient and optional message. The user reviews, edits, and pays in PieterPost.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"externalId": {
"description": "Your correlation id for the created order/link.",
"type": "string"
},
"idempotencyKey": {
"description": "Stable idempotency key for retries. Always include this for create operations, especially in live mode.",
"type": "string"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"message": {
"description": "Prepared message. Trimmed to 6,000 characters.",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Up to 20 string, number, or boolean values copied to the order/link.",
"type": "object"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient"
],
"type": "object"
},
"name": "create_compose_link",
"outputSchema": {
"additionalProperties": false,
"properties": {
"expiresAt": {
"type": "string"
},
"id": {
"type": "string"
},
"mode": {
"const": "compose_link",
"type": "string"
},
"testMode": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"expiresAt",
"id",
"mode",
"testMode",
"url"
],
"type": "object"
},
"title": "Create Review Link"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Validate, price, and persist an immutable prepared letter before payment. Set deliveryService=registered for registered mail or US Certified Mail; standard is the default. The result contains preparedOrderRef for create_payment_link and an exact native MPP endpoint/body for clients that support the complete MPP 402 flow.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"composeMode": {
"description": "Letter compose mode. Allowed values: \"personal\" or \"template\". personal uses each letter.message; template uses templateMessage and recipient customFields to generate each letter.",
"type": "string"
},
"deliveryService": {
"description": "Letter delivery service. Allowed values: \"standard\" or \"registered\". Defaults to standard. registered uses the destination service, or Certified Mail with return receipt for US recipients. The server checks availability and page limits and quotes the full price. Applies to all letters in a bulk request; unavailable services return an error. Not available for postcards.",
"type": "string"
},
"externalId": {
"description": "Your correlation id for the created order/link.",
"type": "string"
},
"idempotencyKey": {
"description": "Stable idempotency key for retries. Always include this for create operations, especially in live mode.",
"type": "string"
},
"letters": {
"description": "Bulk letters. Maximum 25.",
"items": {
"additionalProperties": false,
"description": "One letter for one recipient. In personal mode include a message, uploaded attachments, or both. In template mode, templateMessage can supply the message for every recipient. Destination page limits apply to the combined message and attachment pages.",
"properties": {
"attachments": {
"description": "Letter attachment asset IDs or upload_asset objects. Assets must be kind letter-attachment.",
"items": {
"description": "Attachment asset ID string or upload_asset-style object with assetId."
},
"type": "array"
},
"message": {
"description": "Letter body. Trimmed to 6,000 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient"
],
"type": "object"
},
"type": "array"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Up to 20 string, number, or boolean values copied to the order/link.",
"type": "object"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
},
"stampImage": {
"description": "Letter stamp image asset ID string or upload_asset-style object. Equivalent to stampImageAssetId."
},
"stampImageAssetId": {
"description": "Asset ID returned by upload_asset for a letter-stamp-image.",
"type": "string"
},
"templateMessage": {
"description": "Shared letter template used when composeMode is template. Supports {{name}}, {{first_name}}, {{address}}, {{street}}, {{city}}, {{postal_code}}, {{country}}, and recipient customFields. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"useBusinessLogo": {
"description": "For letter orders, use the saved PieterPost Business logo when no order-specific stamp image is supplied. Defaults to true when a saved logo exists. Set false to use the standard PieterPost stamp.",
"type": "boolean"
},
"variableKeys": {
"description": "Letter template variable keys used for recipient customFields.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"idempotencyKey",
"letters"
],
"type": "object"
},
"name": "prepare_letter",
"outputSchema": {
"additionalProperties": false,
"properties": {
"amountCents": {
"type": "number"
},
"contentPreview": {
"type": "string"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"deliveryService": {
"enum": [
"standard",
"registered"
],
"type": "string"
},
"expiresAt": {
"type": "string"
},
"fulfillmentStatus": {
"enum": [
"not_started",
"queued",
"fulfilled",
"failed"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"mppEndpoint": {
"type": "string"
},
"mppRequest": {
"additionalProperties": false,
"properties": {
"body": {
"additionalProperties": false,
"properties": {
"orderRef": {
"type": "string"
},
"payloadHash": {
"type": "string"
},
"preparedOrderId": {
"type": "string"
}
},
"required": [
"orderRef",
"payloadHash",
"preparedOrderId"
],
"type": "object"
},
"contentType": {
"const": "application/json",
"type": "string"
},
"method": {
"const": "POST",
"type": "string"
}
},
"required": [
"body",
"contentType",
"method"
],
"type": "object"
},
"nextActions": {
"items": {
"enum": [
"create_payment_link",
"pay_with_mpp",
"get_order_status"
],
"type": "string"
},
"type": "array"
},
"orderRef": {
"type": "string"
},
"payloadHash": {
"type": "string"
},
"paymentStatus": {
"enum": [
"unpaid",
"processing",
"paid",
"failed",
"expired"
],
"type": "string"
},
"preparedOrderId": {
"type": "string"
},
"preparedOrderRef": {
"type": "string"
},
"recipient": {
"additionalProperties": false,
"properties": {
"city": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"recipientCount": {
"type": "number"
}
},
"required": [
"city",
"country",
"name",
"recipientCount"
],
"type": "object"
},
"requestType": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"status": {
"enum": [
"draft",
"payment_processing",
"checkout_open",
"paid",
"queued",
"fulfilled",
"failed",
"cancelled",
"expired"
],
"type": "string"
},
"statusUrl": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"amountCents",
"contentPreview",
"currency",
"expiresAt",
"fulfillmentStatus",
"mode",
"mppEndpoint",
"mppRequest",
"nextActions",
"orderRef",
"payloadHash",
"paymentStatus",
"preparedOrderId",
"preparedOrderRef",
"recipient",
"requestType",
"status",
"statusUrl",
"updatedAt"
],
"type": "object"
},
"title": "Prepare Agent Letter"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Validate, price, and persist an immutable prepared postcard before payment. The result contains preparedOrderRef for create_payment_link and an exact native MPP endpoint/body for clients that support the complete MPP 402 flow.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"externalId": {
"description": "Your correlation id for the created order/link.",
"type": "string"
},
"idempotencyKey": {
"description": "Stable idempotency key for retries. Always include this for create operations, especially in live mode.",
"type": "string"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Up to 20 string, number, or boolean values copied to the order/link.",
"type": "object"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"postcard": {
"additionalProperties": false,
"description": "Postcard payload. Provide recipient for one card or recipients for bulk cards up to 25 recipients. Add frontImageAssetId or frontImage when you want a square 1:1 custom front instead of the default one.",
"properties": {
"composeMode": {
"description": "Compose mode. Allowed values: \"personal\" or \"template\". personal sends one message as written; template lets recipient customFields replace variables in supported templates.",
"type": "string"
},
"frontImage": {
"description": "Optional square 1:1 postcard image asset ID string or upload_asset-style object. Equivalent to frontImageAssetId."
},
"frontImageAssetId": {
"description": "Optional asset ID returned by upload_asset for a square 1:1 postcard-image.",
"type": "string"
},
"message": {
"description": "Postcard message. Trimmed to 1,200 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"recipients": {
"description": "Bulk postcard recipients. Maximum 25.",
"items": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"variableKeys": {
"description": "Template variable keys to use for postcard personalization.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
}
},
"required": [
"idempotencyKey",
"postcard"
],
"type": "object"
},
"name": "prepare_postcard",
"outputSchema": {
"additionalProperties": false,
"properties": {
"amountCents": {
"type": "number"
},
"contentPreview": {
"type": "string"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"deliveryService": {
"enum": [
"standard",
"registered"
],
"type": "string"
},
"expiresAt": {
"type": "string"
},
"fulfillmentStatus": {
"enum": [
"not_started",
"queued",
"fulfilled",
"failed"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"mppEndpoint": {
"type": "string"
},
"mppRequest": {
"additionalProperties": false,
"properties": {
"body": {
"additionalProperties": false,
"properties": {
"orderRef": {
"type": "string"
},
"payloadHash": {
"type": "string"
},
"preparedOrderId": {
"type": "string"
}
},
"required": [
"orderRef",
"payloadHash",
"preparedOrderId"
],
"type": "object"
},
"contentType": {
"const": "application/json",
"type": "string"
},
"method": {
"const": "POST",
"type": "string"
}
},
"required": [
"body",
"contentType",
"method"
],
"type": "object"
},
"nextActions": {
"items": {
"enum": [
"create_payment_link",
"pay_with_mpp",
"get_order_status"
],
"type": "string"
},
"type": "array"
},
"orderRef": {
"type": "string"
},
"payloadHash": {
"type": "string"
},
"paymentStatus": {
"enum": [
"unpaid",
"processing",
"paid",
"failed",
"expired"
],
"type": "string"
},
"preparedOrderId": {
"type": "string"
},
"preparedOrderRef": {
"type": "string"
},
"recipient": {
"additionalProperties": false,
"properties": {
"city": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"recipientCount": {
"type": "number"
}
},
"required": [
"city",
"country",
"name",
"recipientCount"
],
"type": "object"
},
"requestType": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"status": {
"enum": [
"draft",
"payment_processing",
"checkout_open",
"paid",
"queued",
"fulfilled",
"failed",
"cancelled",
"expired"
],
"type": "string"
},
"statusUrl": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"amountCents",
"contentPreview",
"currency",
"expiresAt",
"fulfillmentStatus",
"mode",
"mppEndpoint",
"mppRequest",
"nextActions",
"orderRef",
"payloadHash",
"paymentStatus",
"preparedOrderId",
"preparedOrderRef",
"recipient",
"requestType",
"status",
"statusUrl",
"updatedAt"
],
"type": "object"
},
"title": "Prepare Agent Postcard"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Validate and price a letter or postcard payload without creating an order. Provide exactly one of letters or postcard. Use this before live direct-send flows to confirm the amount, wallet balance gap, and next action.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"composeMode": {
"description": "Letter compose mode. Allowed values: \"personal\" or \"template\". personal uses each letter.message; template uses templateMessage and recipient customFields to generate each letter.",
"type": "string"
},
"deliveryService": {
"description": "Letter delivery service. Allowed values: \"standard\" or \"registered\". Defaults to standard. registered uses the destination service, or Certified Mail with return receipt for US recipients. The server checks availability and page limits and quotes the full price. Applies to all letters in a bulk request; unavailable services return an error. Not available for postcards.",
"type": "string"
},
"externalId": {
"description": "Your correlation id for the created order/link.",
"type": "string"
},
"idempotencyKey": {
"description": "Stable idempotency key for retries. Always include this for create operations, especially in live mode.",
"type": "string"
},
"letters": {
"description": "Bulk letters. Maximum 25.",
"items": {
"additionalProperties": false,
"description": "One letter for one recipient. In personal mode include a message, uploaded attachments, or both. In template mode, templateMessage can supply the message for every recipient. Destination page limits apply to the combined message and attachment pages.",
"properties": {
"attachments": {
"description": "Letter attachment asset IDs or upload_asset objects. Assets must be kind letter-attachment.",
"items": {
"description": "Attachment asset ID string or upload_asset-style object with assetId."
},
"type": "array"
},
"message": {
"description": "Letter body. Trimmed to 6,000 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient"
],
"type": "object"
},
"type": "array"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Up to 20 string, number, or boolean values copied to the order/link.",
"type": "object"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"postcard": {
"additionalProperties": false,
"description": "Postcard payload. Provide recipient for one card or recipients for bulk cards up to 25 recipients. Add frontImageAssetId or frontImage when you want a square 1:1 custom front instead of the default one.",
"properties": {
"composeMode": {
"description": "Compose mode. Allowed values: \"personal\" or \"template\". personal sends one message as written; template lets recipient customFields replace variables in supported templates.",
"type": "string"
},
"frontImage": {
"description": "Optional square 1:1 postcard image asset ID string or upload_asset-style object. Equivalent to frontImageAssetId."
},
"frontImageAssetId": {
"description": "Optional asset ID returned by upload_asset for a square 1:1 postcard-image.",
"type": "string"
},
"message": {
"description": "Postcard message. Trimmed to 1,200 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"recipients": {
"description": "Bulk postcard recipients. Maximum 25.",
"items": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"variableKeys": {
"description": "Template variable keys to use for postcard personalization.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
},
"senderEmail": {
"description": "Optional order contact email. Hosted Stripe Checkout collects the payer email when omitted.",
"type": "string"
},
"stampImage": {
"description": "Letter stamp image asset ID string or upload_asset-style object. Equivalent to stampImageAssetId."
},
"stampImageAssetId": {
"description": "Asset ID returned by upload_asset for a letter-stamp-image.",
"type": "string"
},
"templateMessage": {
"description": "Shared letter template used when composeMode is template. Supports {{name}}, {{first_name}}, {{address}}, {{street}}, {{city}}, {{postal_code}}, {{country}}, and recipient customFields. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"useBusinessLogo": {
"description": "For letter orders, use the saved PieterPost Business logo when no order-specific stamp image is supplied. Defaults to true when a saved logo exists. Set false to use the standard PieterPost stamp.",
"type": "boolean"
},
"variableKeys": {
"description": "Letter template variable keys used for recipient customFields.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"name": "quote_order",
"outputSchema": {
"additionalProperties": false,
"properties": {
"accountId": {
"type": "string"
},
"addressWarnings": {
"items": {
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"deliverable_incorrect_unit",
"deliverable_missing_unit"
],
"type": "string"
},
"message": {
"type": "string"
},
"recipientIndex": {
"type": "number"
},
"standardizedAddress": {
"additionalProperties": false,
"properties": {
"addressLine1": {
"type": "string"
},
"addressLine2": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"const": "US",
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"addressLine1",
"addressLine2",
"city",
"country",
"postalCode",
"state"
],
"type": "object"
}
},
"required": [
"code",
"message",
"recipientIndex",
"standardizedAddress"
],
"type": "object"
},
"type": "array"
},
"amountCents": {
"type": "number"
},
"approvalStatus": {
"enum": [
"pending",
"approved",
"rejected"
],
"type": "string"
},
"approvedForDirectSend": {
"type": "boolean"
},
"creditsEnabled": {
"type": "boolean"
},
"deliveryService": {
"enum": [
"standard",
"registered"
],
"type": "string"
},
"guidance": {
"additionalProperties": false,
"properties": {
"nextAction": {
"enum": [
"create_payment_link",
"create_checkout_link",
"create_credit_topup",
"create_direct_order"
],
"type": "string"
},
"recommendedMaxAmountCents": {
"type": "number"
},
"recommendedTopupAmountCents": {
"type": [
"number",
"null"
]
},
"requiresConfirmLiveSend": {
"type": "boolean"
},
"requiresIdempotencyKey": {
"type": "boolean"
},
"walletDirectSendAlternative": {
"additionalProperties": false,
"properties": {
"nextAction": {
"enum": [
"create_credit_topup",
"create_direct_order"
],
"type": "string"
},
"recommendedMaxAmountCents": {
"type": "number"
},
"recommendedTopupAmountCents": {
"type": [
"number",
"null"
]
},
"requiresConfirmLiveSend": {
"type": "boolean"
},
"requiresIdempotencyKey": {
"type": "boolean"
}
},
"required": [
"nextAction",
"recommendedMaxAmountCents",
"recommendedTopupAmountCents",
"requiresConfirmLiveSend",
"requiresIdempotencyKey"
],
"type": "object"
}
},
"required": [
"nextAction",
"recommendedMaxAmountCents",
"recommendedTopupAmountCents",
"requiresConfirmLiveSend",
"requiresIdempotencyKey",
"walletDirectSendAlternative"
],
"type": "object"
},
"liveEnabled": {
"type": "boolean"
},
"missingBalanceCents": {
"type": "number"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"recipientCount": {
"type": "number"
},
"requestType": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"requiresTopup": {
"type": "boolean"
},
"wallet": {
"additionalProperties": false,
"properties": {
"balanceCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"balanceCents",
"currency",
"mode",
"updatedAt"
],
"type": "object"
}
},
"required": [
"accountId",
"addressWarnings",
"amountCents",
"approvalStatus",
"approvedForDirectSend",
"creditsEnabled",
"guidance",
"liveEnabled",
"missingBalanceCents",
"mode",
"recipientCount",
"requestType",
"requiresTopup",
"wallet"
],
"type": "object"
},
"title": "Quote Mail Order"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Create a hosted payment link for one-off MCP letter or postcard sending without public API keys or wallet credits. Pass preparedOrderRef from prepare_letter or prepare_postcard with a new draft-scoped idempotencyKey, or retain the backward-compatible full payload form with exactly one of letters or postcard. Mail is sent only after checkout is paid. senderEmail and returnUrl remain optional for full-payload calls.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"composeMode": {
"description": "Letter compose mode. Allowed values: \"personal\" or \"template\". personal uses each letter.message; template uses templateMessage and recipient customFields to generate each letter.",
"type": "string"
},
"deliveryService": {
"description": "Letter delivery service. Allowed values: \"standard\" or \"registered\". Defaults to standard. registered uses the destination service, or Certified Mail with return receipt for US recipients. The server checks availability and page limits and quotes the full price. Applies to all letters in a bulk request; unavailable services return an error. Not available for postcards.",
"type": "string"
},
"externalId": {
"description": "Your correlation id for the created order/link.",
"type": "string"
},
"idempotencyKey": {
"description": "Stable idempotency key for retries. Always include this for create operations, especially in live mode.",
"type": "string"
},
"letters": {
"description": "Bulk letters. Maximum 25.",
"items": {
"additionalProperties": false,
"description": "One letter for one recipient. In personal mode include a message, uploaded attachments, or both. In template mode, templateMessage can supply the message for every recipient. Destination page limits apply to the combined message and attachment pages.",
"properties": {
"attachments": {
"description": "Letter attachment asset IDs or upload_asset objects. Assets must be kind letter-attachment.",
"items": {
"description": "Attachment asset ID string or upload_asset-style object with assetId."
},
"type": "array"
},
"message": {
"description": "Letter body. Trimmed to 6,000 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient"
],
"type": "object"
},
"type": "array"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Up to 20 string, number, or boolean values copied to the order/link.",
"type": "object"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"postcard": {
"additionalProperties": false,
"description": "Postcard payload. Provide recipient for one card or recipients for bulk cards up to 25 recipients. Add frontImageAssetId or frontImage when you want a square 1:1 custom front instead of the default one.",
"properties": {
"composeMode": {
"description": "Compose mode. Allowed values: \"personal\" or \"template\". personal sends one message as written; template lets recipient customFields replace variables in supported templates.",
"type": "string"
},
"frontImage": {
"description": "Optional square 1:1 postcard image asset ID string or upload_asset-style object. Equivalent to frontImageAssetId."
},
"frontImageAssetId": {
"description": "Optional asset ID returned by upload_asset for a square 1:1 postcard-image.",
"type": "string"
},
"message": {
"description": "Postcard message. Trimmed to 1,200 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"recipients": {
"description": "Bulk postcard recipients. Maximum 25.",
"items": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"variableKeys": {
"description": "Template variable keys to use for postcard personalization.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
},
"senderEmail": {
"description": "Optional order contact email. Hosted Stripe Checkout collects the payer email when omitted.",
"type": "string"
},
"stampImage": {
"description": "Letter stamp image asset ID string or upload_asset-style object. Equivalent to stampImageAssetId."
},
"stampImageAssetId": {
"description": "Asset ID returned by upload_asset for a letter-stamp-image.",
"type": "string"
},
"templateMessage": {
"description": "Shared letter template used when composeMode is template. Supports {{name}}, {{first_name}}, {{address}}, {{street}}, {{city}}, {{postal_code}}, {{country}}, and recipient customFields. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"useBusinessLogo": {
"description": "For letter orders, use the saved PieterPost Business logo when no order-specific stamp image is supplied. Defaults to true when a saved logo exists. Set false to use the standard PieterPost stamp.",
"type": "boolean"
},
"variableKeys": {
"description": "Letter template variable keys used for recipient customFields.",
"items": {
"type": "string"
},
"type": "array"
},
"paymentMethod": {
"description": "Stripe-hosted checkout payment method. Allowed values: \"auto\", \"card\", or \"ideal\". auto is the default and offers card plus iDEAL for EUR checkout. ideal is available for EUR letter and postcard checkout links and EUR wallet top-ups.",
"type": "string"
},
"preparedOrderRef": {
"description": "orderRef returned by prepare_letter or prepare_postcard. When provided, omit letters and postcard and pass a payment-operation idempotencyKey.",
"type": "string"
},
"returnUrl": {
"description": "Optional checkout success/cancel redirect. PieterPost appends checkout=success or checkout=cancelled. Defaults to a PieterPost-hosted MCP return page.",
"type": "string"
}
},
"type": "object"
},
"name": "create_payment_link",
"outputSchema": {
"additionalProperties": true,
"properties": {
"amountCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"orderRef": {
"type": "string"
},
"paymentLinkUrl": {
"type": "string"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"amountCents",
"currency",
"expiresAt",
"orderRef",
"paymentLinkUrl",
"status",
"updatedAt"
],
"type": "object"
},
"title": "Create Payment Link"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Create a hosted checkout link for letters or postcards. This is the public-API-compatible name for create_payment_link. Provide exactly one of letters or postcard. Supports bulk letters, letter template mode, custom letter stamps, bulk postcard recipients up to 25 recipients, letter attachments, and optional square 1:1 custom postcard front images. Mail is sent only after checkout is paid. senderEmail is optional for MCP calls; Stripe Checkout collects the payer email when omitted. returnUrl is optional for MCP calls.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"composeMode": {
"description": "Letter compose mode. Allowed values: \"personal\" or \"template\". personal uses each letter.message; template uses templateMessage and recipient customFields to generate each letter.",
"type": "string"
},
"deliveryService": {
"description": "Letter delivery service. Allowed values: \"standard\" or \"registered\". Defaults to standard. registered uses the destination service, or Certified Mail with return receipt for US recipients. The server checks availability and page limits and quotes the full price. Applies to all letters in a bulk request; unavailable services return an error. Not available for postcards.",
"type": "string"
},
"externalId": {
"description": "Your correlation id for the created order/link.",
"type": "string"
},
"idempotencyKey": {
"description": "Stable idempotency key for retries. Always include this for create operations, especially in live mode.",
"type": "string"
},
"letters": {
"description": "Bulk letters. Maximum 25.",
"items": {
"additionalProperties": false,
"description": "One letter for one recipient. In personal mode include a message, uploaded attachments, or both. In template mode, templateMessage can supply the message for every recipient. Destination page limits apply to the combined message and attachment pages.",
"properties": {
"attachments": {
"description": "Letter attachment asset IDs or upload_asset objects. Assets must be kind letter-attachment.",
"items": {
"description": "Attachment asset ID string or upload_asset-style object with assetId."
},
"type": "array"
},
"message": {
"description": "Letter body. Trimmed to 6,000 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient"
],
"type": "object"
},
"type": "array"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Up to 20 string, number, or boolean values copied to the order/link.",
"type": "object"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"postcard": {
"additionalProperties": false,
"description": "Postcard payload. Provide recipient for one card or recipients for bulk cards up to 25 recipients. Add frontImageAssetId or frontImage when you want a square 1:1 custom front instead of the default one.",
"properties": {
"composeMode": {
"description": "Compose mode. Allowed values: \"personal\" or \"template\". personal sends one message as written; template lets recipient customFields replace variables in supported templates.",
"type": "string"
},
"frontImage": {
"description": "Optional square 1:1 postcard image asset ID string or upload_asset-style object. Equivalent to frontImageAssetId."
},
"frontImageAssetId": {
"description": "Optional asset ID returned by upload_asset for a square 1:1 postcard-image.",
"type": "string"
},
"message": {
"description": "Postcard message. Trimmed to 1,200 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"recipients": {
"description": "Bulk postcard recipients. Maximum 25.",
"items": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"variableKeys": {
"description": "Template variable keys to use for postcard personalization.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
},
"senderEmail": {
"description": "Optional order contact email. Hosted Stripe Checkout collects the payer email when omitted.",
"type": "string"
},
"stampImage": {
"description": "Letter stamp image asset ID string or upload_asset-style object. Equivalent to stampImageAssetId."
},
"stampImageAssetId": {
"description": "Asset ID returned by upload_asset for a letter-stamp-image.",
"type": "string"
},
"templateMessage": {
"description": "Shared letter template used when composeMode is template. Supports {{name}}, {{first_name}}, {{address}}, {{street}}, {{city}}, {{postal_code}}, {{country}}, and recipient customFields. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"useBusinessLogo": {
"description": "For letter orders, use the saved PieterPost Business logo when no order-specific stamp image is supplied. Defaults to true when a saved logo exists. Set false to use the standard PieterPost stamp.",
"type": "boolean"
},
"variableKeys": {
"description": "Letter template variable keys used for recipient customFields.",
"items": {
"type": "string"
},
"type": "array"
},
"paymentMethod": {
"description": "Stripe-hosted checkout payment method. Allowed values: \"auto\", \"card\", or \"ideal\". auto is the default and offers card plus iDEAL for EUR checkout. ideal is available for EUR letter and postcard checkout links and EUR wallet top-ups.",
"type": "string"
},
"returnUrl": {
"description": "Optional checkout success/cancel redirect. PieterPost appends checkout=success or checkout=cancelled. Defaults to a PieterPost-hosted MCP return page.",
"type": "string"
}
},
"type": "object"
},
"name": "create_checkout_link",
"outputSchema": {
"additionalProperties": false,
"properties": {
"amountCents": {
"type": "number"
},
"billingMode": {
"enum": [
"credits",
"hosted_checkout",
"agent_payment"
],
"type": "string"
},
"checkoutUrl": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"delivery": {
"additionalProperties": false,
"properties": {
"availability": {
"enum": [
"available",
"pending",
"unavailable",
"test_mode"
],
"type": "string"
},
"items": {
"items": {
"additionalProperties": false,
"properties": {
"deliveredAt": {
"type": [
"string",
"null"
]
},
"deliveryService": {
"enum": [
"standard",
"registered"
],
"type": "string"
},
"estimatedDeliveryFrom": {
"type": "string"
},
"estimatedDeliveryTo": {
"type": "string"
},
"recipientIndex": {
"minimum": 0,
"type": "integer"
},
"status": {
"enum": [
"processing",
"in_production",
"printed",
"in_transit",
"pickup_available",
"delivered",
"returned_to_sender",
"undeliverable",
"needs_attention",
"unknown"
],
"type": "string"
},
"trackingNumber": {
"type": [
"string",
"null"
]
},
"trackingUrl": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"deliveredAt",
"deliveryService",
"estimatedDeliveryFrom",
"estimatedDeliveryTo",
"recipientIndex",
"status",
"trackingNumber",
"trackingUrl",
"updatedAt"
],
"type": "object"
},
"maxItems": 25,
"type": "array"
},
"nextOffset": {
"minimum": 0,
"type": [
"integer",
"null"
]
},
"recipientCount": {
"minimum": 0,
"type": "integer"
},
"statusPageUrl": {
"type": "string"
},
"total": {
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"availability",
"items",
"nextOffset",
"recipientCount",
"statusPageUrl",
"total"
],
"type": "object"
},
"error": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"externalId": {
"type": [
"string",
"null"
]
},
"fulfilledAt": {
"type": [
"string",
"null"
]
},
"metadata": {
"additionalProperties": true,
"type": "object"
},
"orderId": {
"type": "string"
},
"orderRef": {
"type": "string"
},
"paidAt": {
"type": [
"string",
"null"
]
},
"paymentReference": {
"type": [
"string",
"null"
]
},
"publicCheckoutUrl": {
"type": [
"string",
"null"
]
},
"recipientCount": {
"type": "number"
},
"requestType": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"senderEmail": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"draft",
"payment_processing",
"checkout_open",
"paid",
"queued",
"fulfilled",
"failed",
"cancelled",
"expired"
],
"type": "string"
},
"testMode": {
"type": "boolean"
},
"updatedAt": {
"type": "string"
},
"wallet": {
"additionalProperties": false,
"properties": {
"balanceCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"balanceCents",
"currency",
"mode",
"updatedAt"
],
"type": "object"
}
},
"required": [
"amountCents",
"billingMode",
"checkoutUrl",
"createdAt",
"currency",
"error",
"expiresAt",
"externalId",
"fulfilledAt",
"metadata",
"orderId",
"orderRef",
"paidAt",
"paymentReference",
"publicCheckoutUrl",
"recipientCount",
"requestType",
"senderEmail",
"status",
"testMode",
"updatedAt"
],
"type": "object"
},
"title": "Create Checkout Link"
},
{
"annotations": {
"destructiveHint": true,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Create a direct-send order paid from wallet credits. Provide exactly one of letters or postcard. Supports bulk letters and postcards with the same payload shape as hosted checkout. Test mode simulates sending. Live mode sends real mail and requires confirmLiveSend=true plus maxAmountCents >= the calculated total.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"acceptUsAddressWarnings": {
"description": "Set to true when the calling agent accepts missing or incorrect US unit warnings returned by quote_order or a prior create attempt.",
"type": "boolean"
},
"composeMode": {
"description": "Letter compose mode. Allowed values: \"personal\" or \"template\". personal uses each letter.message; template uses templateMessage and recipient customFields to generate each letter.",
"type": "string"
},
"deliveryService": {
"description": "Letter delivery service. Allowed values: \"standard\" or \"registered\". Defaults to standard. registered uses the destination service, or Certified Mail with return receipt for US recipients. The server checks availability and page limits and quotes the full price. Applies to all letters in a bulk request; unavailable services return an error. Not available for postcards.",
"type": "string"
},
"externalId": {
"description": "Your correlation id for the created order/link.",
"type": "string"
},
"idempotencyKey": {
"description": "Stable idempotency key for retries. Always include this for create operations, especially in live mode.",
"type": "string"
},
"letters": {
"description": "Bulk letters. Maximum 25.",
"items": {
"additionalProperties": false,
"description": "One letter for one recipient. In personal mode include a message, uploaded attachments, or both. In template mode, templateMessage can supply the message for every recipient. Destination page limits apply to the combined message and attachment pages.",
"properties": {
"attachments": {
"description": "Letter attachment asset IDs or upload_asset objects. Assets must be kind letter-attachment.",
"items": {
"description": "Attachment asset ID string or upload_asset-style object with assetId."
},
"type": "array"
},
"message": {
"description": "Letter body. Trimmed to 6,000 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
},
"required": [
"recipient"
],
"type": "object"
},
"type": "array"
},
"locale": {
"description": "Locale. Allowed values: \"de\", \"en\", \"es\", \"fr\", \"it\", \"nl\", \"pl\", or \"pt\".",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Up to 20 string, number, or boolean values copied to the order/link.",
"type": "object"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"postcard": {
"additionalProperties": false,
"description": "Postcard payload. Provide recipient for one card or recipients for bulk cards up to 25 recipients. Add frontImageAssetId or frontImage when you want a square 1:1 custom front instead of the default one.",
"properties": {
"composeMode": {
"description": "Compose mode. Allowed values: \"personal\" or \"template\". personal sends one message as written; template lets recipient customFields replace variables in supported templates.",
"type": "string"
},
"frontImage": {
"description": "Optional square 1:1 postcard image asset ID string or upload_asset-style object. Equivalent to frontImageAssetId."
},
"frontImageAssetId": {
"description": "Optional asset ID returned by upload_asset for a square 1:1 postcard-image.",
"type": "string"
},
"message": {
"description": "Postcard message. Trimmed to 1,200 characters. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"recipient": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"recipients": {
"description": "Bulk postcard recipients. Maximum 25.",
"items": {
"additionalProperties": true,
"description": "Recipient address. Provide name plus addressLines, or name with streetAddress or street plus number, postalCode, city, country, and state when required. Free-form address parsing is not performed.",
"properties": {
"addressType": {
"description": "Use \"postal\" for a complete ordered postal address, including German Großempfänger addresses without a street. Inferred for German addressLines without an explicit street. \"street\" retains street and house-number checks.",
"type": "string"
},
"addressLines": {
"description": "Preformatted address lines, excluding the recipient name.",
"items": {
"type": "string"
},
"type": "array"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"customFields": {
"description": "Template variables available when letter or postcard composeMode is template.",
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"extra": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"number": {
"type": "string"
},
"postalCode": {
"type": "string"
},
"state": {
"type": "string"
},
"street": {
"type": "string"
},
"streetAddress": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"variableKeys": {
"description": "Template variable keys to use for postcard personalization.",
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"requestType": {
"description": "Request type. Allowed values: \"letter\" or \"postcard\". Use letter with letters, or postcard with postcard. If omitted, postcard is inferred when postcard is present.",
"type": "string"
},
"senderEmail": {
"description": "Optional order contact email. Hosted Stripe Checkout collects the payer email when omitted.",
"type": "string"
},
"stampImage": {
"description": "Letter stamp image asset ID string or upload_asset-style object. Equivalent to stampImageAssetId."
},
"stampImageAssetId": {
"description": "Asset ID returned by upload_asset for a letter-stamp-image.",
"type": "string"
},
"templateMessage": {
"description": "Shared letter template used when composeMode is template. Supports {{name}}, {{first_name}}, {{address}}, {{street}}, {{city}}, {{postal_code}}, {{country}}, and recipient customFields. Use \\n for line breaks; line breaks are preserved.",
"type": "string"
},
"useBusinessLogo": {
"description": "For letter orders, use the saved PieterPost Business logo when no order-specific stamp image is supplied. Defaults to true when a saved logo exists. Set false to use the standard PieterPost stamp.",
"type": "boolean"
},
"variableKeys": {
"description": "Letter template variable keys used for recipient customFields.",
"items": {
"type": "string"
},
"type": "array"
},
"confirmLiveSend": {
"description": "Required true for live mode when the calling agent authorizes direct send.",
"type": "boolean"
},
"maxAmountCents": {
"description": "Required for live mode; caps the total spend.",
"type": "number"
}
},
"type": "object"
},
"name": "create_direct_order",
"outputSchema": {
"additionalProperties": false,
"properties": {
"amountCents": {
"type": "number"
},
"billingMode": {
"enum": [
"credits",
"hosted_checkout",
"agent_payment"
],
"type": "string"
},
"checkoutUrl": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"delivery": {
"additionalProperties": false,
"properties": {
"availability": {
"enum": [
"available",
"pending",
"unavailable",
"test_mode"
],
"type": "string"
},
"items": {
"items": {
"additionalProperties": false,
"properties": {
"deliveredAt": {
"type": [
"string",
"null"
]
},
"deliveryService": {
"enum": [
"standard",
"registered"
],
"type": "string"
},
"estimatedDeliveryFrom": {
"type": "string"
},
"estimatedDeliveryTo": {
"type": "string"
},
"recipientIndex": {
"minimum": 0,
"type": "integer"
},
"status": {
"enum": [
"processing",
"in_production",
"printed",
"in_transit",
"pickup_available",
"delivered",
"returned_to_sender",
"undeliverable",
"needs_attention",
"unknown"
],
"type": "string"
},
"trackingNumber": {
"type": [
"string",
"null"
]
},
"trackingUrl": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"deliveredAt",
"deliveryService",
"estimatedDeliveryFrom",
"estimatedDeliveryTo",
"recipientIndex",
"status",
"trackingNumber",
"trackingUrl",
"updatedAt"
],
"type": "object"
},
"maxItems": 25,
"type": "array"
},
"nextOffset": {
"minimum": 0,
"type": [
"integer",
"null"
]
},
"recipientCount": {
"minimum": 0,
"type": "integer"
},
"statusPageUrl": {
"type": "string"
},
"total": {
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"availability",
"items",
"nextOffset",
"recipientCount",
"statusPageUrl",
"total"
],
"type": "object"
},
"error": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"externalId": {
"type": [
"string",
"null"
]
},
"fulfilledAt": {
"type": [
"string",
"null"
]
},
"metadata": {
"additionalProperties": true,
"type": "object"
},
"orderId": {
"type": "string"
},
"orderRef": {
"type": "string"
},
"paidAt": {
"type": [
"string",
"null"
]
},
"paymentReference": {
"type": [
"string",
"null"
]
},
"publicCheckoutUrl": {
"type": [
"string",
"null"
]
},
"recipientCount": {
"type": "number"
},
"requestType": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"senderEmail": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"draft",
"payment_processing",
"checkout_open",
"paid",
"queued",
"fulfilled",
"failed",
"cancelled",
"expired"
],
"type": "string"
},
"testMode": {
"type": "boolean"
},
"updatedAt": {
"type": "string"
},
"wallet": {
"additionalProperties": false,
"properties": {
"balanceCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"balanceCents",
"currency",
"mode",
"updatedAt"
],
"type": "object"
}
},
"required": [
"amountCents",
"billingMode",
"checkoutUrl",
"createdAt",
"currency",
"error",
"expiresAt",
"externalId",
"fulfilledAt",
"metadata",
"orderId",
"orderRef",
"paidAt",
"paymentReference",
"publicCheckoutUrl",
"recipientCount",
"requestType",
"senderEmail",
"status",
"testMode",
"updatedAt"
],
"type": "object"
},
"title": "Create Direct Order"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Upload a square 1:1 postcard front image, letter attachment, or custom letter stamp for later use in create_checkout_link or create_direct_order. Provide exactly one of fileBase64 or a public HTTPS fileUrl. Returns an assetId that can be passed as postcard.frontImageAssetId, stampImageAssetId, or in a letter attachments array.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"contentType": {
"description": "Content type. Common values: \"application/pdf\" for letter attachments, or \"image/png\" / \"image/jpeg\" for images.",
"type": "string"
},
"fileBase64": {
"description": "Base64-encoded file contents.",
"type": "string"
},
"fileName": {
"description": "Original file name, used for extension validation.",
"type": "string"
},
"fileUrl": {
"description": "Public HTTPS URL to fetch. Private and localhost URLs are rejected.",
"type": "string"
},
"kind": {
"description": "Upload kind. Allowed values: \"letter-attachment\", \"letter-stamp-image\", or \"postcard-image\".",
"type": "string"
}
},
"required": [
"kind",
"fileName",
"contentType"
],
"type": "object"
},
"name": "upload_asset",
"outputSchema": {
"additionalProperties": true,
"type": "object"
},
"title": "Upload Mail Asset"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Read the API wallet balance and account capability flags for test or live mode.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"currency": {
"description": "Currency. Allowed values: \"eur\" or \"usd\".",
"type": "string"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
}
},
"type": "object"
},
"name": "get_wallet",
"outputSchema": {
"additionalProperties": false,
"properties": {
"accountId": {
"type": "string"
},
"approvalStatus": {
"enum": [
"pending",
"approved",
"rejected"
],
"type": "string"
},
"approvedForDirectSend": {
"type": "boolean"
},
"creditsEnabled": {
"type": "boolean"
},
"hostedApiEnabled": {
"type": "boolean"
},
"liveEnabled": {
"type": "boolean"
},
"wallet": {
"additionalProperties": false,
"properties": {
"balanceCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"balanceCents",
"currency",
"mode",
"updatedAt"
],
"type": "object"
}
},
"required": [
"accountId",
"approvalStatus",
"approvedForDirectSend",
"creditsEnabled",
"hostedApiEnabled",
"liveEnabled",
"wallet"
],
"type": "object"
},
"title": "Get Wallet Balance"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Fetch an API order by id, including payment/fulfillment state and postal delivery status. delivery contains per-recipient status, tracking number/link when available, delivered date, estimates, and a status-page link. fulfilled means submission for printing and posting, not delivery. Use deliveryOffset and deliveryLimit (1-25, default 25) for bulk orders.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"orderId": {
"type": "string"
},
"deliveryOffset": {
"description": "First delivery item, starting at 0.",
"type": "integer"
},
"deliveryLimit": {
"description": "Delivery items per page, 1 to 25. Defaults to 25.",
"type": "integer"
}
},
"required": [
"orderId"
],
"type": "object"
},
"name": "get_order",
"outputSchema": {
"additionalProperties": false,
"properties": {
"amountCents": {
"type": "number"
},
"billingMode": {
"enum": [
"credits",
"hosted_checkout",
"agent_payment"
],
"type": "string"
},
"checkoutUrl": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"delivery": {
"additionalProperties": false,
"properties": {
"availability": {
"enum": [
"available",
"pending",
"unavailable",
"test_mode"
],
"type": "string"
},
"items": {
"items": {
"additionalProperties": false,
"properties": {
"deliveredAt": {
"type": [
"string",
"null"
]
},
"deliveryService": {
"enum": [
"standard",
"registered"
],
"type": "string"
},
"estimatedDeliveryFrom": {
"type": "string"
},
"estimatedDeliveryTo": {
"type": "string"
},
"recipientIndex": {
"minimum": 0,
"type": "integer"
},
"status": {
"enum": [
"processing",
"in_production",
"printed",
"in_transit",
"pickup_available",
"delivered",
"returned_to_sender",
"undeliverable",
"needs_attention",
"unknown"
],
"type": "string"
},
"trackingNumber": {
"type": [
"string",
"null"
]
},
"trackingUrl": {
"type": [
"string",
"null"
]
},
"updatedAt": {
"type": "string"
}
},
"required": [
"deliveredAt",
"deliveryService",
"estimatedDeliveryFrom",
"estimatedDeliveryTo",
"recipientIndex",
"status",
"trackingNumber",
"trackingUrl",
"updatedAt"
],
"type": "object"
},
"maxItems": 25,
"type": "array"
},
"nextOffset": {
"minimum": 0,
"type": [
"integer",
"null"
]
},
"recipientCount": {
"minimum": 0,
"type": "integer"
},
"statusPageUrl": {
"type": "string"
},
"total": {
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"availability",
"items",
"nextOffset",
"recipientCount",
"statusPageUrl",
"total"
],
"type": "object"
},
"error": {
"type": [
"string",
"null"
]
},
"expiresAt": {
"type": [
"string",
"null"
]
},
"externalId": {
"type": [
"string",
"null"
]
},
"fulfilledAt": {
"type": [
"string",
"null"
]
},
"metadata": {
"additionalProperties": true,
"type": "object"
},
"orderId": {
"type": "string"
},
"orderRef": {
"type": "string"
},
"paidAt": {
"type": [
"string",
"null"
]
},
"paymentReference": {
"type": [
"string",
"null"
]
},
"publicCheckoutUrl": {
"type": [
"string",
"null"
]
},
"recipientCount": {
"type": "number"
},
"requestType": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"senderEmail": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"draft",
"payment_processing",
"checkout_open",
"paid",
"queued",
"fulfilled",
"failed",
"cancelled",
"expired"
],
"type": "string"
},
"testMode": {
"type": "boolean"
},
"updatedAt": {
"type": "string"
},
"wallet": {
"additionalProperties": false,
"properties": {
"balanceCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"balanceCents",
"currency",
"mode",
"updatedAt"
],
"type": "object"
}
},
"required": [
"amountCents",
"billingMode",
"checkoutUrl",
"createdAt",
"currency",
"error",
"expiresAt",
"externalId",
"fulfilledAt",
"metadata",
"orderId",
"orderRef",
"paidAt",
"paymentReference",
"publicCheckoutUrl",
"recipientCount",
"requestType",
"senderEmail",
"status",
"testMode",
"updatedAt"
],
"type": "object"
},
"title": "Get Order Status"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Fetch a PieterPost wallet top-up by id, including payment status and checkout URL when still pending.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"topupId": {
"type": "string"
}
},
"required": [
"topupId"
],
"type": "object"
},
"name": "get_topup",
"outputSchema": {
"additionalProperties": false,
"properties": {
"amountCents": {
"type": "number"
},
"checkoutUrl": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"paidAt": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"paid",
"cancelled",
"expired",
"failed"
],
"type": "string"
},
"testMode": {
"type": "boolean"
},
"topupId": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"wallet": {
"additionalProperties": false,
"properties": {
"balanceCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"balanceCents",
"currency",
"mode",
"updatedAt"
],
"type": "object"
}
},
"required": [
"amountCents",
"checkoutUrl",
"createdAt",
"currency",
"paidAt",
"status",
"testMode",
"topupId",
"updatedAt"
],
"type": "object"
},
"title": "Get Credit Top-Up"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "List recent PieterPost wallet top-ups for this account. Use mode and currency filters to inspect the active live or test funding history.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"currency": {
"description": "Currency. Allowed values: \"eur\" or \"usd\".",
"type": "string"
},
"limit": {
"description": "Maximum number of top-ups to return. Typical range is 1 to 20.",
"type": "number"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
}
},
"type": "object"
},
"name": "list_topups",
"outputSchema": {
"additionalProperties": false,
"properties": {
"topups": {
"items": {
"additionalProperties": false,
"properties": {
"amountCents": {
"type": "number"
},
"checkoutUrl": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"paidAt": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"paid",
"cancelled",
"expired",
"failed"
],
"type": "string"
},
"testMode": {
"type": "boolean"
},
"topupId": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"wallet": {
"additionalProperties": false,
"properties": {
"balanceCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"balanceCents",
"currency",
"mode",
"updatedAt"
],
"type": "object"
}
},
"required": [
"amountCents",
"checkoutUrl",
"createdAt",
"currency",
"paidAt",
"status",
"testMode",
"topupId",
"updatedAt"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"topups"
],
"type": "object"
},
"title": "List Credit Top-Ups"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Create a test credit top-up immediately, or create a live Stripe checkout URL for adding API credits used by direct-send orders. paymentMethod=auto is the default; for EUR top-ups it offers both card and iDEAL. Pass paymentMethod=card or paymentMethod=ideal only when the user wants to force one method.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"amountCents": {
"description": "Top-up amount in cents. Rounded up to whole euros.",
"type": "number"
},
"currency": {
"description": "Currency. Allowed values: \"eur\" or \"usd\".",
"type": "string"
},
"idempotencyKey": {
"description": "Stable idempotency key for retries. Always include this for create operations, especially in live mode.",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Up to 20 string, number, or boolean values copied to the order/link.",
"type": "object"
},
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"paymentMethod": {
"description": "Stripe-hosted checkout payment method. Allowed values: \"auto\", \"card\", or \"ideal\". auto is the default and offers card plus iDEAL for EUR checkout. ideal is available for EUR letter and postcard checkout links and EUR wallet top-ups.",
"type": "string"
},
"returnUrl": {
"description": "Used for live Stripe checkout success/cancel redirects.",
"type": "string"
}
},
"required": [
"amountCents"
],
"type": "object"
},
"name": "create_credit_topup",
"outputSchema": {
"additionalProperties": false,
"properties": {
"amountCents": {
"type": "number"
},
"checkoutUrl": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"paidAt": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"paid",
"cancelled",
"expired",
"failed"
],
"type": "string"
},
"testMode": {
"type": "boolean"
},
"topupId": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"wallet": {
"additionalProperties": false,
"properties": {
"balanceCents": {
"type": "number"
},
"currency": {
"enum": [
"eur",
"usd"
],
"type": "string"
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"updatedAt": {
"type": "string"
}
},
"required": [
"balanceCents",
"currency",
"mode",
"updatedAt"
],
"type": "object"
}
},
"required": [
"amountCents",
"checkoutUrl",
"createdAt",
"currency",
"paidAt",
"status",
"testMode",
"topupId",
"updatedAt"
],
"type": "object"
},
"title": "Create Credit Top-Up"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "List API key metadata for this PieterPost API account. Secrets are never returned.",
"inputSchema": {
"additionalProperties": false,
"properties": {},
"type": "object"
},
"name": "list_api_keys",
"outputSchema": {
"additionalProperties": false,
"properties": {
"keys": {
"items": {
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"id": {
"type": "string"
},
"lastUsedAt": {
"type": [
"string",
"null"
]
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"name": {
"type": "string"
},
"revokedAt": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"active",
"paused",
"revoked"
],
"type": "string"
},
"tokenLast4": {
"type": "string"
}
},
"required": [
"createdAt",
"id",
"lastUsedAt",
"mode",
"name",
"revokedAt",
"status",
"tokenLast4"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"keys"
],
"type": "object"
},
"title": "List API Keys"
},
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Create a new PieterPost public API key. The secret is returned once and cannot be recovered later.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"mode": {
"description": "Mode. Allowed values: \"test\" or \"live\". Defaults to test when omitted.",
"type": "string"
},
"name": {
"description": "Human-readable key name.",
"type": "string"
}
},
"type": "object"
},
"name": "create_api_key",
"outputSchema": {
"additionalProperties": false,
"properties": {
"key": {
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"id": {
"type": "string"
},
"lastUsedAt": {
"type": [
"string",
"null"
]
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"name": {
"type": "string"
},
"revokedAt": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"active",
"paused",
"revoked"
],
"type": "string"
},
"tokenLast4": {
"type": "string"
}
},
"required": [
"createdAt",
"id",
"lastUsedAt",
"mode",
"name",
"revokedAt",
"status",
"tokenLast4"
],
"type": "object"
},
"secret": {
"type": "string"
},
"warning": {
"type": "string"
}
},
"required": [
"key",
"secret",
"warning"
],
"type": "object"
},
"title": "Create API Key"
},
{
"annotations": {
"destructiveHint": true,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Revoke an existing PieterPost public API key by id.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"keyId": {
"type": "string"
}
},
"required": [
"keyId"
],
"type": "object"
},
"name": "revoke_api_key",
"outputSchema": {
"additionalProperties": false,
"properties": {
"key": {
"additionalProperties": false,
"properties": {
"createdAt": {
"type": "string"
},
"id": {
"type": "string"
},
"lastUsedAt": {
"type": [
"string",
"null"
]
},
"mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"name": {
"type": "string"
},
"revokedAt": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"active",
"paused",
"revoked"
],
"type": "string"
},
"tokenLast4": {
"type": "string"
}
},
"required": [
"createdAt",
"id",
"lastUsedAt",
"mode",
"name",
"revokedAt",
"status",
"tokenLast4"
],
"type": "object"
},
"revoked": {
"type": "boolean"
}
},
"required": [
"key",
"revoked"
],
"type": "object"
},
"title": "Revoke API Key"
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "List what a PieterPost card can be: starter designs (templateId, name, occasion, format, sample text), material presets, formats and sizes (profileId), print techniques (standard print, foil, letterpress) with their papers, finishes and rules, letterpress inks, built-in illustrations (iconId) and fonts (search with fontQuery). Read-only; no login.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"fontQuery": {
"description": "Search all fonts by family name; returns only fonts unless sections is given.",
"maxLength": 100,
"type": "string"
},
"sections": {
"description": "Which parts to return: templates, presets, formats, techniques, fonts, icons. Default all (only fonts with fontQuery).",
"items": {
"type": "string",
"description": "Allowed values: \"templates\", \"presets\", \"formats\", \"techniques\", \"fonts\", \"icons\"."
},
"type": "array"
}
},
"type": "object"
},
"name": "list_card_options",
"title": "List Card Options",
"outputSchema": {
"additionalProperties": true,
"type": "object"
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Start a printed greeting card design without login: from a starter design (templateId) or blank, optionally with a material preset, size and a first batch of edits. Returns a private draftToken, an editorUrl where the person can adjust the card and order it from PieterPost, the version, every element with its id and style, technique issues and PNG previews. Give the editorUrl to the person; it gives edit access, so don't post it publicly. Drafts expire 30 days after their last change. Iterate with update_card_design. Call get_card_preview for each side to inspect the rendered card. Nothing is printed, paid or sent.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"locale": {
"description": "Language of starter texts and the editor, e.g. en or nl.",
"maxLength": 10,
"type": "string"
},
"name": {
"description": "Name of the design, shown in the editor.",
"maxLength": 120,
"type": "string"
},
"operations": {
"description": "Edits applied in order, all or nothing (max 50). Element ids come from get_card_design or earlier results; add_element and add_image take an optional id so later operations in the same call can use it.",
"items": {
"additionalProperties": false,
"description": "One edit; send only the fields its op uses. apply_template: Replace the whole design with a starter design. Optional preset (classic, special, deluxe) picks its material; profileId keeps a size. Required: templateId. Optional: preset, profileId. set_card_options: Change technique, paper, format/size or corners. Elements adapt to a new size. Required: nothing else. Optional: corners, glued, glueFirst, paper, backPaper, profileId, technique. rename: Required: name. Optional: none. add_element: Add a text box, shape, QR code (text = the URL; the code is drawn with a white quiet zone, about 80% of the box) or built-in illustration (kind icon with iconId). Any style field can be set at creation. New text is regular weight (fontWeight 400); new shapes have no border and square corners. Text boxes don't grow: give long text enough heightMm. New elements go on top unless behindElementId is given. Required: kind, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). add_image: Place a photo or image: as a new image (target new, default), as the page background (target background), or replacing the picture of an image element (target = its id). Required: image, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). update_element: Change an element's text, position, size, rotation or style, or swap an illustration (iconId). Only the given fields change. Required: elementId. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). delete_element: Required: elementId. Optional: none. set_layer: Change stacking order on its side. Elements stay above the page background: back puts the element just above it. Required: elementId, direction. Optional: none. set_page_background: Set a page's background colour, or use an existing image on that page as its background (elementId). Give one. Required: pageIndex. Optional: backgroundColor, elementId.",
"properties": {
"op": {
"description": "Operation: apply_template, set_card_options, rename, add_element, add_image, update_element, delete_element, set_layer, set_page_background.",
"type": "string"
},
"preset": {
"type": "string",
"description": "Allowed values: \"classic\", \"special\", \"deluxe\"."
},
"profileId": {
"description": "Card size id from list_card_options. set_card_options: Card format and size id from list_card_options. Choose by the format's name, fold and sides (see formatNote there): a card is flat (front and back) unless the person asks for a folded or opening card.",
"type": "string"
},
"templateId": {
"type": "string",
"description": "Allowed values: \"blank\", \"baby_tree\", \"baby_stork\", \"baby_bunny\", \"baby_bw\", \"baby_moon\", \"baby_1\", \"baby_2\", \"baby_bow\", \"baby_elephant\", \"baby_starry\", \"baby_bear\", \"baby_balloon\", \"baby_robin\", \"baby_fox\", \"baby_fawn\", \"baby_meadow\", \"baby_whale\", \"baby_lamb\", \"baby_owl\", \"baby_hedgehog\", \"baby_sailboat\", \"baby_rainbow\", \"baby_wreath\", \"wedding_dunes\", \"wedding_wreath\", \"wedding_1\", \"wedding_pressed\", \"wedding_gold\", \"wedding_farmhouse\", \"wedding_save_date\", \"wedding_summer\", \"wedding_lemons\", \"wedding_doves\", \"wedding_seaside\", \"wedding_blossom\", \"wedding_winter\", \"wedding_tulips\", \"wedding_canal\", \"wedding_windmill\", \"wedding_delft\", \"wedding_tandem\", \"wedding_lavender\", \"wedding_olive\", \"wedding_vineyard\", \"wedding_peonies\", \"wedding_roses\", \"wedding_sunflowers\", \"wedding_autumn\", \"wedding_forest\", \"wedding_mountains\", \"wedding_swans\", \"wedding_champagne\", \"wedding_artdeco\", \"wedding_celestial\", \"wedding_disco\", \"wedding_rings\", \"wedding_cake\", \"wedding_shapes\", \"wedding_rainbow\", \"wedding_pampas\", \"wedding_desert\", \"wedding_tropical\", \"wedding_cherries\", \"wedding_strawberries\", \"wedding_greenhouse\", \"wedding_castle\", \"wedding_paris\", \"wedding_amalfi\", \"wedding_santorini\", \"wedding_cranes\", \"wedding_marigold\", \"wedding_festoon\", \"wedding_festival\", \"wedding_campervan\", \"wedding_sailing\", \"wedding_hearts\", \"wedding_swallows\", \"wedding_butterflies\", \"wedding_bees\", \"wedding_magnolia\", \"wedding_anemones\", \"wedding_dahlias\", \"wedding_wheat\", \"wedding_aurora\", \"wedding_skyline\", \"wedding_oneline\", \"funeral_sea\", \"funeral_willow\", \"funeral_1\", \"thank_you\"."
},
"corners": {
"description": "Corner shape of a rectangular card: square (sharp) or rounded. This is not the card's shape; a square card is a profileId. Allowed values: \"square\", \"rounded\".",
"type": "string"
},
"glued": {
"description": "Flat letterpress, papers under 600 g only: glue a second sheet of the same paper behind the card. By default it's glued after pressing, so no impression shows on the back and the back can be printed freely (at the offer's glued price, see list_card_options). The card gets thicker; its colour doesn't change.",
"type": "boolean"
},
"glueFirst": {
"description": "Glued cards only: glue the two sheets before pressing instead (no surcharge). The card presses like one 600 g sheet, so the impression may show on the back.",
"type": "boolean"
},
"paper": {
"description": "Paper id from list_card_options.",
"type": "string"
},
"backPaper": {
"description": "Glued cards only: the paper id of the sheet glued behind the card, for a card with another colour on the back (one of the technique's papers). The front's paper id or null means the same paper on both sides.",
"type": "string"
},
"technique": {
"type": "string",
"description": "Allowed values: \"digital\", \"letterpress\"."
},
"name": {
"maxLength": 120,
"minLength": 1,
"type": "string"
},
"backgroundColor": {
"description": "Fill colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderColor": {
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderRadiusMm": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"borderWidthMm": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"color": {
"description": "Text colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"finish": {
"description": "Cards only. Text and shapes: foil_* (a foil colour: foil_gold, foil_silver, foil_copper on the foil technique, where foil is a raised 3D layer on top of the print; letterpress offers the printer's foil colours pressed into the paper, also with blind or emboss; the two never mix on one card; colours per technique in list_card_options), print (letterpress, printed in its own colour but not pressed in; use it for text that doesn't need pressing), blind (letterpress, pressed in without colour; without a finish, text and shapes on a letterpress front are printed and pressed in; pressing needs 600 g paper) or emboss (letterpress, raised from the back; nothing may be printed behind it on the inside); none removes it. Images and icons can be blind or emboss only: their visible part is pressed and a transparent background stays flat, so use a transparent PNG with clean, hard edges (soft edges and shadows are pressed all or nothing). On a shape the whole fill becomes foil (there is no foil outline), so keep foil shapes small. Which finishes are allowed depends on the card's technique (list_card_options). Allowed values: \"none\", \"print\", \"foil_white_gold\", \"foil_gold\", \"foil_gold_matte\", \"foil_gold_holo\", \"foil_caramel_gold\", \"foil_caramel_glitter\", \"foil_rose_gold\", \"foil_copper\", \"foil_copper_matte\", \"foil_bronze\", \"foil_brown\", \"foil_white\", \"foil_pearl\", \"foil_silver\", \"foil_silver_holo\", \"foil_light_pink\", \"foil_holo_pink\", \"foil_magenta\", \"foil_cherry_red\", \"foil_lilac\", \"foil_purple\", \"foil_ice_blue_matte\", \"foil_silver_blue\", \"foil_blue\", \"foil_dark_blue_gloss\", \"foil_ocean\", \"foil_spring_green_matte\", \"foil_green\", \"foil_grass_green_gloss\", \"foil_petrol\", \"blind\", \"emboss\".",
"type": "string"
},
"fontFamily": {
"description": "Font ID from list_card_options (fonts), or legacy inter, mono, serif.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"italic\", \"normal\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"heightMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"curve": {
"description": "Text only: bend the text along an arc, -100 to 100. Positive arches up (like a rainbow), negative bows down (like a smile); 0 is straight. Curved text is one line (line breaks become spaces) centred in its box; make the box wide and tall enough for the arc. 30 to 60 is a gentle arch.",
"minimum": -100,
"maximum": 100,
"type": "number"
},
"letterSpacingPt": {
"description": "Extra space after each text grapheme in points (1 pt = 1/72 inch). Default 0. Does not change text or rich-text runs.",
"minimum": -2,
"maximum": 30,
"type": "number"
},
"lineHeight": {
"description": "Text baseline distance as a font-size multiplier. Default 1.35.",
"minimum": 0.5,
"maximum": 5,
"type": "number"
},
"imagePositionX": {
"description": "Horizontal cover crop anchor in percent: 0 left, 50 centre, 100 right. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imagePositionY": {
"description": "Vertical cover crop anchor in percent: 0 top, 50 centre, 100 bottom. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imageZoom": {
"description": "Cover crop zoom multiplier, 1 to 3. Ignored for contain.",
"minimum": 1,
"maximum": 3,
"type": "number"
},
"textRuns": {
"description": "Rich text runs. Concatenated run text must equal text (or the current text on update). Omitted styles inherit the element style; a run's fontFamily, fontSizePt and color override the element's (not on curved text, which uses the element's). An empty array clears rich formatting. Whole-element font style, weight and underline changes also update existing runs, and whole-element font, size and colour changes replace the runs' own, unless textRuns is supplied.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"normal\", \"italic\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"fontFamily": {
"description": "Font ID from list_card_options (fonts) for this run.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"color": {
"description": "Run colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
}
}
}
},
"imageFit": {
"type": "string",
"description": "Allowed values: \"contain\", \"cover\"."
},
"opacity": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"rotation": {
"maximum": 360,
"minimum": -360,
"type": "number"
},
"shadow": {
"type": "string",
"description": "Allowed values: \"none\", \"soft\"."
},
"text": {
"description": "Text content, or the URL for a QR code. On letters, supports tags such as {{first_name}}; cards have no personal fields (every card in an order is the same).",
"maxLength": 5000,
"type": "string"
},
"textAlign": {
"type": "string",
"description": "Allowed values: \"center\", \"left\", \"right\"."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"widthMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"xMm": {
"description": "Left edge in mm from the page's left edge.",
"type": "number"
},
"yMm": {
"description": "Top edge in mm from the page's top edge.",
"type": "number"
},
"behindElementId": {
"description": "Place the new element directly behind this element instead of on top. add_image: Place a new image directly behind this element instead of on top.",
"type": "string"
},
"iconId": {
"description": "Illustration from list_card_options icons. Icons can't be recoloured. update_element: Swap the artwork of an illustration element. Allowed values: \"cardBabyBalloon\", \"cardBabyFox\", \"cardBabyFawn\", \"cardBabyMeadow\", \"cardBabyWhale\", \"cardBabyLamb\", \"cardBabyOwl\", \"cardBabyHedgehog\", \"cardBabySailboat\", \"cardBabyRainbow\", \"cardBabyWreath\", \"cardBabyBear\", \"cardBabyBow\", \"cardBabyBunny\", \"cardBabyElephant\", \"cardBabyFeetBw\", \"cardBabyMoon\", \"cardBabyRobin\", \"cardBabyStarry\", \"cardBabyStork\", \"cardBabyTree\", \"cardFuneralSea\", \"cardFuneralWillow\", \"cardWeddingCouple\", \"cardWeddingPressed\", \"cardWeddingVenue\", \"cardWeddingWreath\", \"cardWeddingSummer\", \"cardWeddingLemons\", \"cardWeddingDoves\", \"cardWeddingSeaside\", \"cardWeddingWinter\", \"cardWeddingBlossom\", \"cardWeddingTulips\", \"cardWeddingCanal\", \"cardWeddingWindmill\", \"cardWeddingDelft\", \"cardWeddingTandem\", \"cardWeddingLavender\", \"cardWeddingOlive\", \"cardWeddingVineyard\", \"cardWeddingPeonies\", \"cardWeddingRoses\", \"cardWeddingSunflowers\", \"cardWeddingAutumn\", \"cardWeddingForest\", \"cardWeddingMountains\", \"cardWeddingSwans\", \"cardWeddingChampagne\", \"cardWeddingArtdeco\", \"cardWeddingCelestial\", \"cardWeddingDisco\", \"cardWeddingRings\", \"cardWeddingCake\", \"cardWeddingShapes\", \"cardWeddingRainbow\", \"cardWeddingPampas\", \"cardWeddingDesert\", \"cardWeddingTropical\", \"cardWeddingCherries\", \"cardWeddingStrawberries\", \"cardWeddingGreenhouse\", \"cardWeddingCastle\", \"cardWeddingParis\", \"cardWeddingAmalfi\", \"cardWeddingSantorini\", \"cardWeddingCranes\", \"cardWeddingMarigold\", \"cardWeddingFestoon\", \"cardWeddingFestival\", \"cardWeddingCampervan\", \"cardWeddingSailing\", \"cardWeddingHearts\", \"cardWeddingSwallows\", \"cardWeddingButterflies\", \"cardWeddingBees\", \"cardWeddingMagnolia\", \"cardWeddingAnemones\", \"cardWeddingDahlias\", \"cardWeddingWheat\", \"cardWeddingAurora\", \"cardWeddingSkyline\", \"cardWeddingOneline\", \"recipeHeart\", \"weddingThankYouConfetti\", \"weddingThankYouDance\", \"weddingThankYouEmbrace\", \"weddingThankYouStrip\", \"weddingThankYouWalk\".",
"type": "string"
},
"id": {
"description": "Optional id for the new element, so later operations in this batch can refer to it. add_image: Optional id for the new image or background image.",
"pattern": "^[A-Za-z0-9_-]{1,40}$",
"type": "string"
},
"kind": {
"type": "string",
"description": "Allowed values: \"text\", \"shape\", \"qr\", \"icon\"."
},
"pageIndex": {
"description": "Flat card: 0 = front, 1 = back. Folded card: each page is the whole open sheet, 0 = outside (front, back and door panels), 1 = inside; design.pages[].panels gives each panel's rectangle.",
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"image": {
"additionalProperties": false,
"description": "A JPEG or PNG, max 5 MB: the assetId of an image uploaded with upload_asset (use this for photos the person shared, or to send base64), or a public HTTPS fileUrl. Give one.",
"properties": {
"assetId": {
"maxLength": 80,
"type": "string"
},
"fileUrl": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
},
"target": {
"description": "new (default): a new image; background: the page background image; or the id of an image element whose picture to replace.",
"type": "string"
},
"elementId": {
"description": "Element id from get_card_design or an earlier operation.",
"type": "string"
},
"direction": {
"type": "string",
"description": "Allowed values: \"front\", \"forward\", \"backward\", \"back\"."
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 50,
"type": "array"
},
"preset": {
"description": "classic, special or deluxe material. Allowed values: \"classic\", \"special\", \"deluxe\".",
"type": "string"
},
"previewPages": {
"description": "Sides to return as PNG previews: 0 = front/outside, 1 = back/inside. Default [0, 1] on create and update; [] skips previews.",
"items": {
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"maxItems": 2,
"type": "array"
},
"profileId": {
"description": "Card size id from list_card_options.",
"type": "string"
},
"templateId": {
"description": "Starter design from list_card_options; blank by default. Allowed values: \"blank\", \"baby_tree\", \"baby_stork\", \"baby_bunny\", \"baby_bw\", \"baby_moon\", \"baby_1\", \"baby_2\", \"baby_bow\", \"baby_elephant\", \"baby_starry\", \"baby_bear\", \"baby_balloon\", \"baby_robin\", \"baby_fox\", \"baby_fawn\", \"baby_meadow\", \"baby_whale\", \"baby_lamb\", \"baby_owl\", \"baby_hedgehog\", \"baby_sailboat\", \"baby_rainbow\", \"baby_wreath\", \"wedding_dunes\", \"wedding_wreath\", \"wedding_1\", \"wedding_pressed\", \"wedding_gold\", \"wedding_farmhouse\", \"wedding_save_date\", \"wedding_summer\", \"wedding_lemons\", \"wedding_doves\", \"wedding_seaside\", \"wedding_blossom\", \"wedding_winter\", \"wedding_tulips\", \"wedding_canal\", \"wedding_windmill\", \"wedding_delft\", \"wedding_tandem\", \"wedding_lavender\", \"wedding_olive\", \"wedding_vineyard\", \"wedding_peonies\", \"wedding_roses\", \"wedding_sunflowers\", \"wedding_autumn\", \"wedding_forest\", \"wedding_mountains\", \"wedding_swans\", \"wedding_champagne\", \"wedding_artdeco\", \"wedding_celestial\", \"wedding_disco\", \"wedding_rings\", \"wedding_cake\", \"wedding_shapes\", \"wedding_rainbow\", \"wedding_pampas\", \"wedding_desert\", \"wedding_tropical\", \"wedding_cherries\", \"wedding_strawberries\", \"wedding_greenhouse\", \"wedding_castle\", \"wedding_paris\", \"wedding_amalfi\", \"wedding_santorini\", \"wedding_cranes\", \"wedding_marigold\", \"wedding_festoon\", \"wedding_festival\", \"wedding_campervan\", \"wedding_sailing\", \"wedding_hearts\", \"wedding_swallows\", \"wedding_butterflies\", \"wedding_bees\", \"wedding_magnolia\", \"wedding_anemones\", \"wedding_dahlias\", \"wedding_wheat\", \"wedding_aurora\", \"wedding_skyline\", \"wedding_oneline\", \"funeral_sea\", \"funeral_willow\", \"funeral_1\", \"thank_you\".",
"type": "string"
}
},
"type": "object"
},
"name": "create_card_design",
"title": "Create Card Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Read the current card design, including edits the person made in the editor since your last call: version, every element with its id and style, layout rules, technique issues and optional PNG previews. Call it before editing when time has passed. Use get_card_preview to inspect the rendered card.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draftToken": {
"description": "draftToken returned by create_card_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"previewPages": {
"description": "Sides to preview; none by default.",
"items": {
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"maxItems": 2,
"type": "array"
}
},
"required": [
"draftToken"
],
"type": "object"
},
"name": "get_card_design",
"title": "Read Card Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "View one rendered card side as a PNG image. Call after creating or editing a card to inspect its actual appearance. Returns text and image content only, so ChatGPT can see the pixels. Read-only: does not change, order, pay for, print or send the card. Read design data and print warnings with get_card_design.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draftToken": {
"description": "draftToken returned by create_card_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"pageIndex": {
"description": "Card side: 0 = front/outside, 1 = back/inside.",
"maximum": 1,
"minimum": 0,
"type": "integer"
}
},
"required": [
"draftToken",
"pageIndex"
],
"type": "object"
},
"name": "get_card_preview",
"title": "View Card Preview"
},
{
"annotations": {
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Edit a card design: change texts, fonts, colours, positions, images, background, technique, paper or size with a batch of operations. Pass the version you last saw as baseVersion; if the person changed the design in the editor meanwhile, nothing is applied and the error returns the current design to edit instead. Returns the new version, elements, issues and PNG previews. The editorUrl stays the same. Call get_card_preview for each side after editing.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"baseVersion": {
"description": "version from the latest create, get or update result.",
"minimum": 1,
"type": "integer"
},
"draftToken": {
"description": "draftToken returned by create_card_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"operations": {
"description": "Edits applied in order, all or nothing (max 50). Element ids come from get_card_design or earlier results; add_element and add_image take an optional id so later operations in the same call can use it.",
"items": {
"additionalProperties": false,
"description": "One edit; send only the fields its op uses. apply_template: Replace the whole design with a starter design. Optional preset (classic, special, deluxe) picks its material; profileId keeps a size. Required: templateId. Optional: preset, profileId. set_card_options: Change technique, paper, format/size or corners. Elements adapt to a new size. Required: nothing else. Optional: corners, glued, glueFirst, paper, backPaper, profileId, technique. rename: Required: name. Optional: none. add_element: Add a text box, shape, QR code (text = the URL; the code is drawn with a white quiet zone, about 80% of the box) or built-in illustration (kind icon with iconId). Any style field can be set at creation. New text is regular weight (fontWeight 400); new shapes have no border and square corners. Text boxes don't grow: give long text enough heightMm. New elements go on top unless behindElementId is given. Required: kind, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). add_image: Place a photo or image: as a new image (target new, default), as the page background (target background), or replacing the picture of an image element (target = its id). Required: image, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). update_element: Change an element's text, position, size, rotation or style, or swap an illustration (iconId). Only the given fields change. Required: elementId. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). delete_element: Required: elementId. Optional: none. set_layer: Change stacking order on its side. Elements stay above the page background: back puts the element just above it. Required: elementId, direction. Optional: none. set_page_background: Set a page's background colour, or use an existing image on that page as its background (elementId). Give one. Required: pageIndex. Optional: backgroundColor, elementId.",
"properties": {
"op": {
"description": "Operation: apply_template, set_card_options, rename, add_element, add_image, update_element, delete_element, set_layer, set_page_background.",
"type": "string"
},
"preset": {
"type": "string",
"description": "Allowed values: \"classic\", \"special\", \"deluxe\"."
},
"profileId": {
"description": "Card size id from list_card_options. set_card_options: Card format and size id from list_card_options. Choose by the format's name, fold and sides (see formatNote there): a card is flat (front and back) unless the person asks for a folded or opening card.",
"type": "string"
},
"templateId": {
"type": "string",
"description": "Allowed values: \"blank\", \"baby_tree\", \"baby_stork\", \"baby_bunny\", \"baby_bw\", \"baby_moon\", \"baby_1\", \"baby_2\", \"baby_bow\", \"baby_elephant\", \"baby_starry\", \"baby_bear\", \"baby_balloon\", \"baby_robin\", \"baby_fox\", \"baby_fawn\", \"baby_meadow\", \"baby_whale\", \"baby_lamb\", \"baby_owl\", \"baby_hedgehog\", \"baby_sailboat\", \"baby_rainbow\", \"baby_wreath\", \"wedding_dunes\", \"wedding_wreath\", \"wedding_1\", \"wedding_pressed\", \"wedding_gold\", \"wedding_farmhouse\", \"wedding_save_date\", \"wedding_summer\", \"wedding_lemons\", \"wedding_doves\", \"wedding_seaside\", \"wedding_blossom\", \"wedding_winter\", \"wedding_tulips\", \"wedding_canal\", \"wedding_windmill\", \"wedding_delft\", \"wedding_tandem\", \"wedding_lavender\", \"wedding_olive\", \"wedding_vineyard\", \"wedding_peonies\", \"wedding_roses\", \"wedding_sunflowers\", \"wedding_autumn\", \"wedding_forest\", \"wedding_mountains\", \"wedding_swans\", \"wedding_champagne\", \"wedding_artdeco\", \"wedding_celestial\", \"wedding_disco\", \"wedding_rings\", \"wedding_cake\", \"wedding_shapes\", \"wedding_rainbow\", \"wedding_pampas\", \"wedding_desert\", \"wedding_tropical\", \"wedding_cherries\", \"wedding_strawberries\", \"wedding_greenhouse\", \"wedding_castle\", \"wedding_paris\", \"wedding_amalfi\", \"wedding_santorini\", \"wedding_cranes\", \"wedding_marigold\", \"wedding_festoon\", \"wedding_festival\", \"wedding_campervan\", \"wedding_sailing\", \"wedding_hearts\", \"wedding_swallows\", \"wedding_butterflies\", \"wedding_bees\", \"wedding_magnolia\", \"wedding_anemones\", \"wedding_dahlias\", \"wedding_wheat\", \"wedding_aurora\", \"wedding_skyline\", \"wedding_oneline\", \"funeral_sea\", \"funeral_willow\", \"funeral_1\", \"thank_you\"."
},
"corners": {
"description": "Corner shape of a rectangular card: square (sharp) or rounded. This is not the card's shape; a square card is a profileId. Allowed values: \"square\", \"rounded\".",
"type": "string"
},
"glued": {
"description": "Flat letterpress, papers under 600 g only: glue a second sheet of the same paper behind the card. By default it's glued after pressing, so no impression shows on the back and the back can be printed freely (at the offer's glued price, see list_card_options). The card gets thicker; its colour doesn't change.",
"type": "boolean"
},
"glueFirst": {
"description": "Glued cards only: glue the two sheets before pressing instead (no surcharge). The card presses like one 600 g sheet, so the impression may show on the back.",
"type": "boolean"
},
"paper": {
"description": "Paper id from list_card_options.",
"type": "string"
},
"backPaper": {
"description": "Glued cards only: the paper id of the sheet glued behind the card, for a card with another colour on the back (one of the technique's papers). The front's paper id or null means the same paper on both sides.",
"type": "string"
},
"technique": {
"type": "string",
"description": "Allowed values: \"digital\", \"letterpress\"."
},
"name": {
"maxLength": 120,
"minLength": 1,
"type": "string"
},
"backgroundColor": {
"description": "Fill colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderColor": {
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderRadiusMm": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"borderWidthMm": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"color": {
"description": "Text colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"finish": {
"description": "Cards only. Text and shapes: foil_* (a foil colour: foil_gold, foil_silver, foil_copper on the foil technique, where foil is a raised 3D layer on top of the print; letterpress offers the printer's foil colours pressed into the paper, also with blind or emboss; the two never mix on one card; colours per technique in list_card_options), print (letterpress, printed in its own colour but not pressed in; use it for text that doesn't need pressing), blind (letterpress, pressed in without colour; without a finish, text and shapes on a letterpress front are printed and pressed in; pressing needs 600 g paper) or emboss (letterpress, raised from the back; nothing may be printed behind it on the inside); none removes it. Images and icons can be blind or emboss only: their visible part is pressed and a transparent background stays flat, so use a transparent PNG with clean, hard edges (soft edges and shadows are pressed all or nothing). On a shape the whole fill becomes foil (there is no foil outline), so keep foil shapes small. Which finishes are allowed depends on the card's technique (list_card_options). Allowed values: \"none\", \"print\", \"foil_white_gold\", \"foil_gold\", \"foil_gold_matte\", \"foil_gold_holo\", \"foil_caramel_gold\", \"foil_caramel_glitter\", \"foil_rose_gold\", \"foil_copper\", \"foil_copper_matte\", \"foil_bronze\", \"foil_brown\", \"foil_white\", \"foil_pearl\", \"foil_silver\", \"foil_silver_holo\", \"foil_light_pink\", \"foil_holo_pink\", \"foil_magenta\", \"foil_cherry_red\", \"foil_lilac\", \"foil_purple\", \"foil_ice_blue_matte\", \"foil_silver_blue\", \"foil_blue\", \"foil_dark_blue_gloss\", \"foil_ocean\", \"foil_spring_green_matte\", \"foil_green\", \"foil_grass_green_gloss\", \"foil_petrol\", \"blind\", \"emboss\".",
"type": "string"
},
"fontFamily": {
"description": "Font ID from list_card_options (fonts), or legacy inter, mono, serif.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"italic\", \"normal\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"heightMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"curve": {
"description": "Text only: bend the text along an arc, -100 to 100. Positive arches up (like a rainbow), negative bows down (like a smile); 0 is straight. Curved text is one line (line breaks become spaces) centred in its box; make the box wide and tall enough for the arc. 30 to 60 is a gentle arch.",
"minimum": -100,
"maximum": 100,
"type": "number"
},
"letterSpacingPt": {
"description": "Extra space after each text grapheme in points (1 pt = 1/72 inch). Default 0. Does not change text or rich-text runs.",
"minimum": -2,
"maximum": 30,
"type": "number"
},
"lineHeight": {
"description": "Text baseline distance as a font-size multiplier. Default 1.35.",
"minimum": 0.5,
"maximum": 5,
"type": "number"
},
"imagePositionX": {
"description": "Horizontal cover crop anchor in percent: 0 left, 50 centre, 100 right. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imagePositionY": {
"description": "Vertical cover crop anchor in percent: 0 top, 50 centre, 100 bottom. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imageZoom": {
"description": "Cover crop zoom multiplier, 1 to 3. Ignored for contain.",
"minimum": 1,
"maximum": 3,
"type": "number"
},
"textRuns": {
"description": "Rich text runs. Concatenated run text must equal text (or the current text on update). Omitted styles inherit the element style; a run's fontFamily, fontSizePt and color override the element's (not on curved text, which uses the element's). An empty array clears rich formatting. Whole-element font style, weight and underline changes also update existing runs, and whole-element font, size and colour changes replace the runs' own, unless textRuns is supplied.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"normal\", \"italic\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"fontFamily": {
"description": "Font ID from list_card_options (fonts) for this run.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"color": {
"description": "Run colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
}
}
}
},
"imageFit": {
"type": "string",
"description": "Allowed values: \"contain\", \"cover\"."
},
"opacity": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"rotation": {
"maximum": 360,
"minimum": -360,
"type": "number"
},
"shadow": {
"type": "string",
"description": "Allowed values: \"none\", \"soft\"."
},
"text": {
"description": "Text content, or the URL for a QR code. On letters, supports tags such as {{first_name}}; cards have no personal fields (every card in an order is the same).",
"maxLength": 5000,
"type": "string"
},
"textAlign": {
"type": "string",
"description": "Allowed values: \"center\", \"left\", \"right\"."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"widthMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"xMm": {
"description": "Left edge in mm from the page's left edge.",
"type": "number"
},
"yMm": {
"description": "Top edge in mm from the page's top edge.",
"type": "number"
},
"behindElementId": {
"description": "Place the new element directly behind this element instead of on top. add_image: Place a new image directly behind this element instead of on top.",
"type": "string"
},
"iconId": {
"description": "Illustration from list_card_options icons. Icons can't be recoloured. update_element: Swap the artwork of an illustration element. Allowed values: \"cardBabyBalloon\", \"cardBabyFox\", \"cardBabyFawn\", \"cardBabyMeadow\", \"cardBabyWhale\", \"cardBabyLamb\", \"cardBabyOwl\", \"cardBabyHedgehog\", \"cardBabySailboat\", \"cardBabyRainbow\", \"cardBabyWreath\", \"cardBabyBear\", \"cardBabyBow\", \"cardBabyBunny\", \"cardBabyElephant\", \"cardBabyFeetBw\", \"cardBabyMoon\", \"cardBabyRobin\", \"cardBabyStarry\", \"cardBabyStork\", \"cardBabyTree\", \"cardFuneralSea\", \"cardFuneralWillow\", \"cardWeddingCouple\", \"cardWeddingPressed\", \"cardWeddingVenue\", \"cardWeddingWreath\", \"cardWeddingSummer\", \"cardWeddingLemons\", \"cardWeddingDoves\", \"cardWeddingSeaside\", \"cardWeddingWinter\", \"cardWeddingBlossom\", \"cardWeddingTulips\", \"cardWeddingCanal\", \"cardWeddingWindmill\", \"cardWeddingDelft\", \"cardWeddingTandem\", \"cardWeddingLavender\", \"cardWeddingOlive\", \"cardWeddingVineyard\", \"cardWeddingPeonies\", \"cardWeddingRoses\", \"cardWeddingSunflowers\", \"cardWeddingAutumn\", \"cardWeddingForest\", \"cardWeddingMountains\", \"cardWeddingSwans\", \"cardWeddingChampagne\", \"cardWeddingArtdeco\", \"cardWeddingCelestial\", \"cardWeddingDisco\", \"cardWeddingRings\", \"cardWeddingCake\", \"cardWeddingShapes\", \"cardWeddingRainbow\", \"cardWeddingPampas\", \"cardWeddingDesert\", \"cardWeddingTropical\", \"cardWeddingCherries\", \"cardWeddingStrawberries\", \"cardWeddingGreenhouse\", \"cardWeddingCastle\", \"cardWeddingParis\", \"cardWeddingAmalfi\", \"cardWeddingSantorini\", \"cardWeddingCranes\", \"cardWeddingMarigold\", \"cardWeddingFestoon\", \"cardWeddingFestival\", \"cardWeddingCampervan\", \"cardWeddingSailing\", \"cardWeddingHearts\", \"cardWeddingSwallows\", \"cardWeddingButterflies\", \"cardWeddingBees\", \"cardWeddingMagnolia\", \"cardWeddingAnemones\", \"cardWeddingDahlias\", \"cardWeddingWheat\", \"cardWeddingAurora\", \"cardWeddingSkyline\", \"cardWeddingOneline\", \"recipeHeart\", \"weddingThankYouConfetti\", \"weddingThankYouDance\", \"weddingThankYouEmbrace\", \"weddingThankYouStrip\", \"weddingThankYouWalk\".",
"type": "string"
},
"id": {
"description": "Optional id for the new element, so later operations in this batch can refer to it. add_image: Optional id for the new image or background image.",
"pattern": "^[A-Za-z0-9_-]{1,40}$",
"type": "string"
},
"kind": {
"type": "string",
"description": "Allowed values: \"text\", \"shape\", \"qr\", \"icon\"."
},
"pageIndex": {
"description": "Flat card: 0 = front, 1 = back. Folded card: each page is the whole open sheet, 0 = outside (front, back and door panels), 1 = inside; design.pages[].panels gives each panel's rectangle.",
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"image": {
"additionalProperties": false,
"description": "A JPEG or PNG, max 5 MB: the assetId of an image uploaded with upload_asset (use this for photos the person shared, or to send base64), or a public HTTPS fileUrl. Give one.",
"properties": {
"assetId": {
"maxLength": 80,
"type": "string"
},
"fileUrl": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
},
"target": {
"description": "new (default): a new image; background: the page background image; or the id of an image element whose picture to replace.",
"type": "string"
},
"elementId": {
"description": "Element id from get_card_design or an earlier operation.",
"type": "string"
},
"direction": {
"type": "string",
"description": "Allowed values: \"front\", \"forward\", \"backward\", \"back\"."
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 50,
"type": "array",
"minItems": 1
},
"previewPages": {
"description": "Sides to return as PNG previews: 0 = front/outside, 1 = back/inside. Default [0, 1] on create and update; [] skips previews.",
"items": {
"maximum": 1,
"minimum": 0,
"type": "integer"
},
"maxItems": 2,
"type": "array"
}
},
"required": [
"draftToken",
"baseVersion",
"operations"
],
"type": "object"
},
"name": "update_card_design",
"title": "Update Card Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "List what a designed PieterPost letter can be: starter letters (templateId, name, sample text), postal layouts (A4 with the address window left or right, A4 France, US Letter) with their page size, address window and postal zones in mm and the recipient countries each is printed for, personal fields, built-in illustrations (iconId) and fonts (search with fontQuery). Read-only; no login.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"fontQuery": {
"description": "Search all fonts by family name; returns only fonts unless sections is given.",
"maxLength": 100,
"type": "string"
},
"sections": {
"description": "Which parts to return: templates, layouts, fonts, icons. Default all (only fonts with fontQuery).",
"items": {
"type": "string",
"description": "Allowed values: \"templates\", \"layouts\", \"fonts\", \"icons\"."
},
"type": "array"
}
},
"type": "object"
},
"name": "list_letter_options",
"title": "List Letter Options",
"outputSchema": {
"additionalProperties": true,
"type": "object"
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Start a designed letter without login: from a starter letter (templateId) or blank, in a postal layout, optionally with a first batch of edits. Returns a private draftToken, an editorUrl where the person can adjust the letter, add recipients and order it from PieterPost, the version, every element by page with its id and style, print issues and PNG previews. Give the editorUrl to the person; it gives edit access, so don't post it publicly. Drafts expire 30 days after their last change. Iterate with update_letter_design. Nothing is printed, paid or sent.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"layoutId": {
"description": "Postal layout from list_letter_options; pingen_a4_left (A4, address window left) by default. Pick the one printed for the recipient's country. Allowed values: \"pingen_a4_left\", \"pingen_a4_right\", \"pingen_fr_a4_right\", \"lob_us_letter\".",
"type": "string"
},
"locale": {
"description": "Language of the editor, e.g. en or nl.",
"maxLength": 10,
"type": "string"
},
"name": {
"description": "Name of the design, shown in the editor.",
"maxLength": 120,
"type": "string"
},
"operations": {
"description": "Edits applied in order, all or nothing (max 50). Element ids come from get_letter_design or earlier results; add_element and add_image take an optional id so later operations in the same call can use it.",
"items": {
"additionalProperties": false,
"description": "One edit; send only the fields its op uses. apply_template: Replace the whole letter with a starter letter from list_letter_options, in the current layout. Required: templateId. Optional: none. set_layout: Switch the postal layout (page size, address window side). Elements are scaled to the new page. Required: layoutId. Optional: none. add_page: Add a blank page after afterPageIndex (default: after the last page), up to 20 pages. Later pages have no address window. Every sheet adds to the price. Required: nothing else. Optional: afterPageIndex. delete_page: Delete a page and everything on it. The first page (0) can't be deleted. Required: pageIndex. Optional: none. rename: Required: name. Optional: none. add_element: Add a text box, shape, QR code (text = the URL; the code is drawn with a white quiet zone, about 80% of the box) or built-in illustration (kind icon with iconId). Any style field can be set at creation. New text is regular weight (fontWeight 400); new shapes have no border and square corners. Text boxes don't grow: give long text enough heightMm. New elements go on top unless behindElementId is given. Required: kind, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). add_image: Place a photo or image: as a new image (target new, default), as the page background (target background), or replacing the picture of an image element (target = its id). Required: image, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). update_element: Change an element's text, position, size, rotation or style, or swap an illustration (iconId). Only the given fields change. Required: elementId. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). delete_element: Required: elementId. Optional: none. set_layer: Change stacking order on its side. Elements stay above the page background: back puts the element just above it. Required: elementId, direction. Optional: none. set_page_background: Set a page's background colour, or use an existing image on that page as its background (elementId). Give one. On page 0 the address window and postal zones stay white. Required: pageIndex. Optional: backgroundColor, elementId.",
"properties": {
"op": {
"description": "Operation: apply_template, set_layout, add_page, delete_page, rename, add_element, add_image, update_element, delete_element, set_layer, set_page_background.",
"type": "string"
},
"templateId": {
"type": "string",
"description": "Allowed values: \"blank\", \"businessLetter\", \"event\", \"invoice\", \"loveLetter\", \"nonprofit\", \"realEstate\", \"recipe\", \"thankYou\", \"travel\", \"welcome\", \"winback\"."
},
"layoutId": {
"type": "string",
"description": "Allowed values: \"pingen_a4_left\", \"pingen_a4_right\", \"pingen_fr_a4_right\", \"lob_us_letter\"."
},
"afterPageIndex": {
"minimum": 0,
"type": "integer"
},
"pageIndex": {
"description": "0-based letter page. Page 0 is the first page, with the address window and postal zones; add pages with add_page.",
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"name": {
"maxLength": 120,
"minLength": 1,
"type": "string"
},
"backgroundColor": {
"description": "Fill colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderColor": {
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderRadiusMm": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"borderWidthMm": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"color": {
"description": "Text colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"fontFamily": {
"description": "Font ID from list_letter_options (fonts), or legacy inter, mono, serif.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"italic\", \"normal\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"heightMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"curve": {
"description": "Text only: bend the text along an arc, -100 to 100. Positive arches up (like a rainbow), negative bows down (like a smile); 0 is straight. Curved text is one line (line breaks become spaces) centred in its box; make the box wide and tall enough for the arc. 30 to 60 is a gentle arch.",
"minimum": -100,
"maximum": 100,
"type": "number"
},
"letterSpacingPt": {
"description": "Extra space after each text grapheme in points (1 pt = 1/72 inch). Default 0. Does not change text or rich-text runs.",
"minimum": -2,
"maximum": 30,
"type": "number"
},
"lineHeight": {
"description": "Text baseline distance as a font-size multiplier. Default 1.35.",
"minimum": 0.5,
"maximum": 5,
"type": "number"
},
"imagePositionX": {
"description": "Horizontal cover crop anchor in percent: 0 left, 50 centre, 100 right. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imagePositionY": {
"description": "Vertical cover crop anchor in percent: 0 top, 50 centre, 100 bottom. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imageZoom": {
"description": "Cover crop zoom multiplier, 1 to 3. Ignored for contain.",
"minimum": 1,
"maximum": 3,
"type": "number"
},
"textRuns": {
"description": "Rich text runs. Concatenated run text must equal text (or the current text on update). Omitted styles inherit the element style; a run's fontFamily, fontSizePt and color override the element's (not on curved text, which uses the element's). An empty array clears rich formatting. Whole-element font style, weight and underline changes also update existing runs, and whole-element font, size and colour changes replace the runs' own, unless textRuns is supplied.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"normal\", \"italic\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"fontFamily": {
"description": "Font ID from list_letter_options (fonts) for this run.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"color": {
"description": "Run colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
}
}
}
},
"imageFit": {
"type": "string",
"description": "Allowed values: \"contain\", \"cover\"."
},
"opacity": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"rotation": {
"maximum": 360,
"minimum": -360,
"type": "number"
},
"shadow": {
"type": "string",
"description": "Allowed values: \"none\", \"soft\"."
},
"text": {
"description": "Text content, or the URL for a QR code. Personal fields such as {{first_name}} are filled in per recipient.",
"maxLength": 5000,
"type": "string"
},
"textAlign": {
"type": "string",
"description": "Allowed values: \"center\", \"left\", \"right\"."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"widthMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"xMm": {
"description": "Left edge in mm from the page's left edge.",
"type": "number"
},
"yMm": {
"description": "Top edge in mm from the page's top edge.",
"type": "number"
},
"behindElementId": {
"description": "Place the new element directly behind this element instead of on top. add_image: Place a new image directly behind this element instead of on top.",
"type": "string"
},
"iconId": {
"description": "Illustration from list_letter_options icons. Icons can't be recoloured. update_element: Swap the artwork of an illustration element. Allowed values: \"cardBabyBalloon\", \"cardBabyFox\", \"cardBabyFawn\", \"cardBabyMeadow\", \"cardBabyWhale\", \"cardBabyLamb\", \"cardBabyOwl\", \"cardBabyHedgehog\", \"cardBabySailboat\", \"cardBabyRainbow\", \"cardBabyWreath\", \"cardBabyBear\", \"cardBabyBow\", \"cardBabyBunny\", \"cardBabyElephant\", \"cardBabyFeetBw\", \"cardBabyMoon\", \"cardBabyRobin\", \"cardBabyStarry\", \"cardBabyStork\", \"cardBabyTree\", \"cardFuneralSea\", \"cardFuneralWillow\", \"cardWeddingCouple\", \"cardWeddingPressed\", \"cardWeddingVenue\", \"cardWeddingWreath\", \"cardWeddingSummer\", \"cardWeddingLemons\", \"cardWeddingDoves\", \"cardWeddingSeaside\", \"cardWeddingWinter\", \"cardWeddingBlossom\", \"cardWeddingTulips\", \"cardWeddingCanal\", \"cardWeddingWindmill\", \"cardWeddingDelft\", \"cardWeddingTandem\", \"cardWeddingLavender\", \"cardWeddingOlive\", \"cardWeddingVineyard\", \"cardWeddingPeonies\", \"cardWeddingRoses\", \"cardWeddingSunflowers\", \"cardWeddingAutumn\", \"cardWeddingForest\", \"cardWeddingMountains\", \"cardWeddingSwans\", \"cardWeddingChampagne\", \"cardWeddingArtdeco\", \"cardWeddingCelestial\", \"cardWeddingDisco\", \"cardWeddingRings\", \"cardWeddingCake\", \"cardWeddingShapes\", \"cardWeddingRainbow\", \"cardWeddingPampas\", \"cardWeddingDesert\", \"cardWeddingTropical\", \"cardWeddingCherries\", \"cardWeddingStrawberries\", \"cardWeddingGreenhouse\", \"cardWeddingCastle\", \"cardWeddingParis\", \"cardWeddingAmalfi\", \"cardWeddingSantorini\", \"cardWeddingCranes\", \"cardWeddingMarigold\", \"cardWeddingFestoon\", \"cardWeddingFestival\", \"cardWeddingCampervan\", \"cardWeddingSailing\", \"cardWeddingHearts\", \"cardWeddingSwallows\", \"cardWeddingButterflies\", \"cardWeddingBees\", \"cardWeddingMagnolia\", \"cardWeddingAnemones\", \"cardWeddingDahlias\", \"cardWeddingWheat\", \"cardWeddingAurora\", \"cardWeddingSkyline\", \"cardWeddingOneline\", \"checkmark\", \"loveLetterPhoto\", \"love\", \"pie\", \"recipeAccent\", \"recipeFlour\", \"recipeHeart\", \"recipeHeader\", \"typewriter\", \"weddingThankYouConfetti\", \"weddingThankYouDance\", \"weddingThankYouEmbrace\", \"weddingThankYouStrip\", \"weddingThankYouWalk\".",
"type": "string"
},
"id": {
"description": "Optional id for the new element, so later operations in this batch can refer to it. add_image: Optional id for the new image or background image.",
"pattern": "^[A-Za-z0-9_-]{1,40}$",
"type": "string"
},
"kind": {
"type": "string",
"description": "Allowed values: \"text\", \"shape\", \"qr\", \"icon\"."
},
"image": {
"additionalProperties": false,
"description": "A JPEG or PNG, max 5 MB: the assetId of an image uploaded with upload_asset (use this for photos the person shared, or to send base64), or a public HTTPS fileUrl. Give one.",
"properties": {
"assetId": {
"maxLength": 80,
"type": "string"
},
"fileUrl": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
},
"target": {
"description": "new (default): a new image; background: the page background image; or the id of an image element whose picture to replace.",
"type": "string"
},
"elementId": {
"description": "Element id from get_letter_design or an earlier operation.",
"type": "string"
},
"direction": {
"type": "string",
"description": "Allowed values: \"front\", \"forward\", \"backward\", \"back\"."
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 50,
"type": "array"
},
"previewPages": {
"description": "Pages to return as PNG previews (0-based, at most 4). Default: the first two pages on create and update; [] skips previews. Page 0 shows a grey sample address where the recipient's address is printed.",
"items": {
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"maxItems": 4,
"type": "array"
},
"templateId": {
"description": "Starter letter from list_letter_options; blank by default. Allowed values: \"blank\", \"businessLetter\", \"event\", \"invoice\", \"loveLetter\", \"nonprofit\", \"realEstate\", \"recipe\", \"thankYou\", \"travel\", \"welcome\", \"winback\".",
"type": "string"
}
},
"type": "object"
},
"name": "create_letter_design",
"title": "Create Letter Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
}
},
{
"annotations": {
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false,
"readOnlyHint": true
},
"description": "Read the current letter design, including edits the person made in the editor since your last call: version, layout and postal zones, every element by page with its id and style, print issues and optional PNG previews. Call it before editing when time has passed.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"draftToken": {
"description": "draftToken returned by create_letter_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"previewPages": {
"description": "Pages to preview (0-based); none by default.",
"items": {
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"maxItems": 4,
"type": "array"
}
},
"required": [
"draftToken"
],
"type": "object"
},
"name": "get_letter_design",
"title": "Read Letter Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
}
},
{
"annotations": {
"destructiveHint": true,
"idempotentHint": false,
"openWorldHint": true,
"readOnlyHint": false
},
"description": "Edit a letter design: change texts, fonts, colours, positions, images, background, pages or postal layout with a batch of operations. Pass the version you last saw as baseVersion; if the person changed the design in the editor meanwhile, nothing is applied and the error returns the current design to edit instead. Returns the new version, elements, issues and PNG previews. The editorUrl stays the same.",
"inputSchema": {
"additionalProperties": false,
"properties": {
"baseVersion": {
"description": "version from the latest create, get or update result.",
"minimum": 1,
"type": "integer"
},
"draftToken": {
"description": "draftToken returned by create_letter_design: the key to the design (also inside editorUrl).",
"maxLength": 32,
"minLength": 32,
"type": "string"
},
"operations": {
"description": "Edits applied in order, all or nothing (max 50). Element ids come from get_letter_design or earlier results; add_element and add_image take an optional id so later operations in the same call can use it.",
"items": {
"additionalProperties": false,
"description": "One edit; send only the fields its op uses. apply_template: Replace the whole letter with a starter letter from list_letter_options, in the current layout. Required: templateId. Optional: none. set_layout: Switch the postal layout (page size, address window side). Elements are scaled to the new page. Required: layoutId. Optional: none. add_page: Add a blank page after afterPageIndex (default: after the last page), up to 20 pages. Later pages have no address window. Every sheet adds to the price. Required: nothing else. Optional: afterPageIndex. delete_page: Delete a page and everything on it. The first page (0) can't be deleted. Required: pageIndex. Optional: none. rename: Required: name. Optional: none. add_element: Add a text box, shape, QR code (text = the URL; the code is drawn with a white quiet zone, about 80% of the box) or built-in illustration (kind icon with iconId). Any style field can be set at creation. New text is regular weight (fontWeight 400); new shapes have no border and square corners. Text boxes don't grow: give long text enough heightMm. New elements go on top unless behindElementId is given. Required: kind, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). add_image: Place a photo or image: as a new image (target new, default), as the page background (target background), or replacing the picture of an image element (target = its id). Required: image, pageIndex. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). update_element: Change an element's text, position, size, rotation or style, or swap an illustration (iconId). Only the given fields change. Required: elementId. Optional: any style field (xMm, yMm, widthMm, heightMm, text, fontFamily, fontSizePt, color, …). delete_element: Required: elementId. Optional: none. set_layer: Change stacking order on its side. Elements stay above the page background: back puts the element just above it. Required: elementId, direction. Optional: none. set_page_background: Set a page's background colour, or use an existing image on that page as its background (elementId). Give one. On page 0 the address window and postal zones stay white. Required: pageIndex. Optional: backgroundColor, elementId.",
"properties": {
"op": {
"description": "Operation: apply_template, set_layout, add_page, delete_page, rename, add_element, add_image, update_element, delete_element, set_layer, set_page_background.",
"type": "string"
},
"templateId": {
"type": "string",
"description": "Allowed values: \"blank\", \"businessLetter\", \"event\", \"invoice\", \"loveLetter\", \"nonprofit\", \"realEstate\", \"recipe\", \"thankYou\", \"travel\", \"welcome\", \"winback\"."
},
"layoutId": {
"type": "string",
"description": "Allowed values: \"pingen_a4_left\", \"pingen_a4_right\", \"pingen_fr_a4_right\", \"lob_us_letter\"."
},
"afterPageIndex": {
"minimum": 0,
"type": "integer"
},
"pageIndex": {
"description": "0-based letter page. Page 0 is the first page, with the address window and postal zones; add pages with add_page.",
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"name": {
"maxLength": 120,
"minLength": 1,
"type": "string"
},
"backgroundColor": {
"description": "Fill colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderColor": {
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"borderRadiusMm": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"borderWidthMm": {
"maximum": 5,
"minimum": 0,
"type": "number"
},
"color": {
"description": "Text colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
},
"fontFamily": {
"description": "Font ID from list_letter_options (fonts), or legacy inter, mono, serif.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"italic\", \"normal\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"heightMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"curve": {
"description": "Text only: bend the text along an arc, -100 to 100. Positive arches up (like a rainbow), negative bows down (like a smile); 0 is straight. Curved text is one line (line breaks become spaces) centred in its box; make the box wide and tall enough for the arc. 30 to 60 is a gentle arch.",
"minimum": -100,
"maximum": 100,
"type": "number"
},
"letterSpacingPt": {
"description": "Extra space after each text grapheme in points (1 pt = 1/72 inch). Default 0. Does not change text or rich-text runs.",
"minimum": -2,
"maximum": 30,
"type": "number"
},
"lineHeight": {
"description": "Text baseline distance as a font-size multiplier. Default 1.35.",
"minimum": 0.5,
"maximum": 5,
"type": "number"
},
"imagePositionX": {
"description": "Horizontal cover crop anchor in percent: 0 left, 50 centre, 100 right. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imagePositionY": {
"description": "Vertical cover crop anchor in percent: 0 top, 50 centre, 100 bottom. Ignored for contain.",
"minimum": 0,
"maximum": 100,
"type": "number"
},
"imageZoom": {
"description": "Cover crop zoom multiplier, 1 to 3. Ignored for contain.",
"minimum": 1,
"maximum": 3,
"type": "number"
},
"textRuns": {
"description": "Rich text runs. Concatenated run text must equal text (or the current text on update). Omitted styles inherit the element style; a run's fontFamily, fontSizePt and color override the element's (not on curved text, which uses the element's). An empty array clears rich formatting. Whole-element font style, weight and underline changes also update existing runs, and whole-element font, size and colour changes replace the runs' own, unless textRuns is supplied.",
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 5000
},
"fontStyle": {
"type": "string",
"description": "Allowed values: \"normal\", \"italic\"."
},
"fontWeight": {
"type": "integer",
"description": "Allowed values: 400, 500, 600, 700."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"fontFamily": {
"description": "Font ID from list_letter_options (fonts) for this run.",
"type": "string"
},
"fontSizePt": {
"maximum": 500,
"minimum": 4,
"type": "number"
},
"color": {
"description": "Run colour as #RRGGBB.",
"pattern": "^#[0-9a-fA-F]{6}$",
"type": "string"
}
}
}
},
"imageFit": {
"type": "string",
"description": "Allowed values: \"contain\", \"cover\"."
},
"opacity": {
"maximum": 1,
"minimum": 0,
"type": "number"
},
"rotation": {
"maximum": 360,
"minimum": -360,
"type": "number"
},
"shadow": {
"type": "string",
"description": "Allowed values: \"none\", \"soft\"."
},
"text": {
"description": "Text content, or the URL for a QR code. Personal fields such as {{first_name}} are filled in per recipient.",
"maxLength": 5000,
"type": "string"
},
"textAlign": {
"type": "string",
"description": "Allowed values: \"center\", \"left\", \"right\"."
},
"textDecoration": {
"type": "string",
"description": "Allowed values: \"none\", \"underline\"."
},
"widthMm": {
"maximum": 1000,
"minimum": 0.2,
"type": "number"
},
"xMm": {
"description": "Left edge in mm from the page's left edge.",
"type": "number"
},
"yMm": {
"description": "Top edge in mm from the page's top edge.",
"type": "number"
},
"behindElementId": {
"description": "Place the new element directly behind this element instead of on top. add_image: Place a new image directly behind this element instead of on top.",
"type": "string"
},
"iconId": {
"description": "Illustration from list_letter_options icons. Icons can't be recoloured. update_element: Swap the artwork of an illustration element. Allowed values: \"cardBabyBalloon\", \"cardBabyFox\", \"cardBabyFawn\", \"cardBabyMeadow\", \"cardBabyWhale\", \"cardBabyLamb\", \"cardBabyOwl\", \"cardBabyHedgehog\", \"cardBabySailboat\", \"cardBabyRainbow\", \"cardBabyWreath\", \"cardBabyBear\", \"cardBabyBow\", \"cardBabyBunny\", \"cardBabyElephant\", \"cardBabyFeetBw\", \"cardBabyMoon\", \"cardBabyRobin\", \"cardBabyStarry\", \"cardBabyStork\", \"cardBabyTree\", \"cardFuneralSea\", \"cardFuneralWillow\", \"cardWeddingCouple\", \"cardWeddingPressed\", \"cardWeddingVenue\", \"cardWeddingWreath\", \"cardWeddingSummer\", \"cardWeddingLemons\", \"cardWeddingDoves\", \"cardWeddingSeaside\", \"cardWeddingWinter\", \"cardWeddingBlossom\", \"cardWeddingTulips\", \"cardWeddingCanal\", \"cardWeddingWindmill\", \"cardWeddingDelft\", \"cardWeddingTandem\", \"cardWeddingLavender\", \"cardWeddingOlive\", \"cardWeddingVineyard\", \"cardWeddingPeonies\", \"cardWeddingRoses\", \"cardWeddingSunflowers\", \"cardWeddingAutumn\", \"cardWeddingForest\", \"cardWeddingMountains\", \"cardWeddingSwans\", \"cardWeddingChampagne\", \"cardWeddingArtdeco\", \"cardWeddingCelestial\", \"cardWeddingDisco\", \"cardWeddingRings\", \"cardWeddingCake\", \"cardWeddingShapes\", \"cardWeddingRainbow\", \"cardWeddingPampas\", \"cardWeddingDesert\", \"cardWeddingTropical\", \"cardWeddingCherries\", \"cardWeddingStrawberries\", \"cardWeddingGreenhouse\", \"cardWeddingCastle\", \"cardWeddingParis\", \"cardWeddingAmalfi\", \"cardWeddingSantorini\", \"cardWeddingCranes\", \"cardWeddingMarigold\", \"cardWeddingFestoon\", \"cardWeddingFestival\", \"cardWeddingCampervan\", \"cardWeddingSailing\", \"cardWeddingHearts\", \"cardWeddingSwallows\", \"cardWeddingButterflies\", \"cardWeddingBees\", \"cardWeddingMagnolia\", \"cardWeddingAnemones\", \"cardWeddingDahlias\", \"cardWeddingWheat\", \"cardWeddingAurora\", \"cardWeddingSkyline\", \"cardWeddingOneline\", \"checkmark\", \"loveLetterPhoto\", \"love\", \"pie\", \"recipeAccent\", \"recipeFlour\", \"recipeHeart\", \"recipeHeader\", \"typewriter\", \"weddingThankYouConfetti\", \"weddingThankYouDance\", \"weddingThankYouEmbrace\", \"weddingThankYouStrip\", \"weddingThankYouWalk\".",
"type": "string"
},
"id": {
"description": "Optional id for the new element, so later operations in this batch can refer to it. add_image: Optional id for the new image or background image.",
"pattern": "^[A-Za-z0-9_-]{1,40}$",
"type": "string"
},
"kind": {
"type": "string",
"description": "Allowed values: \"text\", \"shape\", \"qr\", \"icon\"."
},
"image": {
"additionalProperties": false,
"description": "A JPEG or PNG, max 5 MB: the assetId of an image uploaded with upload_asset (use this for photos the person shared, or to send base64), or a public HTTPS fileUrl. Give one.",
"properties": {
"assetId": {
"maxLength": 80,
"type": "string"
},
"fileUrl": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
},
"target": {
"description": "new (default): a new image; background: the page background image; or the id of an image element whose picture to replace.",
"type": "string"
},
"elementId": {
"description": "Element id from get_letter_design or an earlier operation.",
"type": "string"
},
"direction": {
"type": "string",
"description": "Allowed values: \"front\", \"forward\", \"backward\", \"back\"."
}
},
"required": [
"op"
],
"type": "object"
},
"maxItems": 50,
"type": "array",
"minItems": 1
},
"previewPages": {
"description": "Pages to return as PNG previews (0-based, at most 4). Default: the first two pages on create and update; [] skips previews. Page 0 shows a grey sample address where the recipient's address is printed.",
"items": {
"maximum": 19,
"minimum": 0,
"type": "integer"
},
"maxItems": 4,
"type": "array"
}
},
"required": [
"draftToken",
"baseVersion",
"operations"
],
"type": "object"
},
"name": "update_letter_design",
"title": "Update Letter Design",
"outputSchema": {
"additionalProperties": true,
"properties": {
"design": {
"description": "Name, size or postal layout, card technique and issues, layout rules and every element by side or page.",
"type": "object"
},
"draftToken": {
"type": "string"
},
"editorUrl": {
"description": "Link for the person: adjust the design and order it.",
"type": "string"
},
"expiresAt": {
"type": "string"
},
"characterIssues": {
"description": "checked, fallback: characters printed in a fallback font (warning), missing: characters that can't be printed (blocks card orders; left out of letters).",
"type": "object"
},
"printIssues": {
"description": "Cards: fold, safe zone, bleed and low-dpi warnings of every side. Letters: edge, postal zone and QR size issues of every page (they block ordering).",
"items": {
"type": "object"
},
"type": "array"
},
"previewError": {
"type": "string"
},
"previews": {
"items": {
"properties": {
"pageIndex": {
"type": "integer"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"results": {
"type": "array"
},
"version": {
"type": "integer"
}
},
"type": "object"
}
}
]
}
\`\`\`
## Account example tool arguments
### list_address_book_contacts before sending to a saved contact
\`\`\`json
{
"limit": 5,
"query": "Bart"
}
\`\`\`
### quote_order for a postcard to an Address Book contact
\`\`\`json
{
"idempotencyKey": "postcard_bart_2026_05_01_quote",
"mode": "live",
"postcard": {
"message": "Hi Bart,\nA postcard from PieterPost MCP.",
"recipient": {
"addressLines": [
"Keizersgracht 1",
"1012 AB Amsterdam",
"Netherlands"
],
"city": "Amsterdam",
"country": "NL",
"id": "contact_bart_123",
"name": "Bart",
"postalCode": "1012 AB",
"streetAddress": "Keizersgracht 1"
}
},
"requestType": "postcard"
}
\`\`\`
### upload_asset for a postcard image
\`\`\`json
{
"contentType": "image/jpeg",
"fileName": "front.jpg",
"fileUrl": "https://example.com/front.jpg",
"kind": "postcard-image"
}
\`\`\`
### quote_order before a live direct-send postcard
\`\`\`json
{
"idempotencyKey": "quote_live_postcard_123",
"locale": "en",
"mode": "live",
"postcard": {
"frontImageAssetId": "asset_postcard_front_123",
"message": "Bart,\nA postcard from PieterPost MCP.",
"recipient": {
"city": "Amsterdam",
"country": "NL",
"customFields": {
"gift_code": "SPRING-10"
},
"name": "Pieter Example",
"postalCode": "1012 AB",
"streetAddress": "Damrak 1"
}
},
"requestType": "postcard"
}
\`\`\`
### upload_asset for a letter attachment
\`\`\`json
{
"contentType": "application/pdf",
"fileBase64": "JVBERi0xLjQK...",
"fileName": "receipt.pdf",
"kind": "letter-attachment"
}
\`\`\`
### upload_asset for a letter stamp image
\`\`\`json
{
"contentType": "image/png",
"fileBase64": "iVBORw0KGgo...",
"fileName": "stamp.png",
"kind": "letter-stamp-image"
}
\`\`\`
### create_payment_link for a letter with attachment
\`\`\`json
{
"externalId": "invoice_123",
"idempotencyKey": "invoice_123_checkout",
"letters": [
{
"attachments": [
"asset_letter_pdf_123"
],
"message": "Thanks for your order. The receipt PDF is enclosed.",
"recipient": {
"city": "Amsterdam",
"country": "NL",
"customFields": {
"gift_code": "SPRING-10"
},
"name": "Pieter Example",
"postalCode": "1012 AB",
"streetAddress": "Damrak 1"
}
}
],
"locale": "en",
"metadata": {
"customerId": "cus_123"
},
"mode": "test",
"requestType": "letter"
}
\`\`\`
### create_payment_link for bulk template letters
\`\`\`json
{
"composeMode": "template",
"externalId": "spring_campaign_123",
"idempotencyKey": "spring_campaign_123_checkout",
"letters": [
{
"recipient": {
"city": "Amsterdam",
"country": "NL",
"customFields": {
"gift_code": "SPRING-10"
},
"name": "Pieter Example",
"postalCode": "1012 AB",
"streetAddress": "Damrak 1"
}
},
{
"recipient": {
"city": "Amsterdam",
"country": "NL",
"customFields": {
"gift_code": "SPRING-20"
},
"name": "Sam Example",
"postalCode": "1012 AB",
"streetAddress": "Damrak 1"
}
}
],
"locale": "en",
"mode": "test",
"requestType": "letter",
"stampImageAssetId": "asset_stamp_123",
"templateMessage": "Hi {{first_name}},\nYour spring code is {{gift_code}}.",
"useBusinessLogo": true,
"variableKeys": [
"gift_code"
]
}
\`\`\`
### create_payment_link for a postcard
\`\`\`json
{
"idempotencyKey": "postcard_123_checkout",
"locale": "en",
"mode": "test",
"paymentMethod": "ideal",
"postcard": {
"frontImageAssetId": "asset_postcard_front_123",
"message": "A small card from PieterPost.",
"recipients": [
{
"city": "Amsterdam",
"country": "NL",
"customFields": {
"gift_code": "SPRING-10"
},
"name": "Pieter Example",
"postalCode": "1012 AB",
"streetAddress": "Damrak 1"
}
]
},
"requestType": "postcard"
}
\`\`\`
### create_direct_order for live wallet-funded mail
\`\`\`json
{
"composeMode": "template",
"externalId": "spring_campaign_123",
"idempotencyKey": "spring_campaign_123_live_send",
"letters": [
{
"recipient": {
"city": "Amsterdam",
"country": "NL",
"customFields": {
"gift_code": "SPRING-10"
},
"name": "Pieter Example",
"postalCode": "1012 AB",
"streetAddress": "Damrak 1"
}
},
{
"recipient": {
"city": "Amsterdam",
"country": "NL",
"customFields": {
"gift_code": "SPRING-20"
},
"name": "Sam Example",
"postalCode": "1012 AB",
"streetAddress": "Damrak 1"
}
}
],
"locale": "en",
"mode": "live",
"requestType": "letter",
"stampImageAssetId": "asset_stamp_123",
"templateMessage": "Hi {{first_name}},\nYour spring code is {{gift_code}}.",
"useBusinessLogo": true,
"variableKeys": [
"gift_code"
],
"confirmLiveSend": true,
"maxAmountCents": 2000
}
\`\`\`
### create_credit_topup
\`\`\`json
{
"amountCents": 2500,
"currency": "eur",
"idempotencyKey": "credits_2026_04",
"metadata": {
"source": "mcp"
},
"mode": "live",
"paymentMethod": "ideal",
"returnUrl": "https://example.com/topups/return"
}
\`\`\`
### get_topup
\`\`\`json
{
"mode": "live",
"topupId": "topup_123"
}
\`\`\`
### list_topups
\`\`\`json
{
"currency": "eur",
"limit": 5,
"mode": "live"
}
\`\`\`
## Account operational guidance for agents
- Start with \`search\` or \`fetch\` when the user asks how PieterPost works or you need account context.
- When the user refers to a saved contact by name, call \`list_address_book_contacts\` and confirm the selected recipient if the search returns ambiguous matches.
- For requests like \`send this message to Bart\`, do not ask for Bart's address first. Search Address Book for Bart, use the selected \`recipient\`, then review the final message and continue through the normal quote/send flow.
- Use \`quote_order\` before the first live letter or postcard so you can confirm the amount, recipient count, and next action.
- For ordinary requests like \`send a letter to ...\`, default to one-off sending with \`create_payment_link\`, not wallet credits or public API keys.
- Before any send or hosted checkout handoff, read back and verify the final message text you are placing on the letter or postcard.
- Use \`upload_asset\` before any order requiring postcard fronts, letter attachments, or custom letter stamps. For postcards, only use square 1:1 custom front images.
- Prefer \`create_payment_link\` when a payer should review and pay in hosted checkout without API keys or wallet credits. \`create_checkout_link\` remains available as the API-compatible alias.
- Prefer \`create_compose_link\` when the user should review or edit a single recipient message in PieterPost.
- Use \`get_topup\` or \`list_topups\` to confirm whether a live wallet top-up is still pending or already paid.
- Use \`create_direct_order\` when the calling agent selects wallet-funded/API-credit sending. For live sends, provide a maximum spend cap.
- Use \`idempotencyKey\` for every create operation that may be retried.