Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Echtpost MCP connector

OAuth 2.1/DCR CommunicationAutomation

Connect to Echtpost MCP. Send physical postcards and letters programmatically via the Echtpost API.

Echtpost MCP connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “Set your credentials”

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Authorize and make your first call

    Section titled “Authorize and make your first call”
    quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENV_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'echtpostmcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Echtpost MCP:', link)
    process.stdout.write('Press Enter after authorizing...')
    await new Promise(r => process.stdin.once('data', r))
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'echtpostmcp_get_me',
      toolInput: {},
    })
    console.log(result)

What you can do

Section titled “What you can do”

Connect this agent connector to let your agent:

  • Update group, contact — Update a contact group
  • Fit preview — Check if a message fits on a postcard with the given font settings
  • List templates, motives, groups — List available card templates for the account
  • Get template, motive, me — Get details of a specific template by ID
  • Delete group, contact — Delete a contact group
  • Create group, contact, card from template — Create a new contact group

Tool list

Section titled “Tool list”

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

echtpostmcp_cancel_card # Cancel a scheduled postcard. Only cards where "cancelable" is true can be cancelled. Cancellation is asynchronous and may take a few minutes. 1 param

Cancel a scheduled postcard. Only cards where "cancelable" is true can be cancelled. Cancellation is asynchronous and may take a few minutes.

Name Type Required Description
id string required UUID of the card to cancel.
echtpostmcp_create_card # Create a postcard with custom message and font. Validates that text fits on the card. Use preview_fit first to check if your message fits. Specify recipients via existing contact IDs, group IDs, or inline recipient objects (combinable). For simpler creation from a saved template, use create_card_from_template instead. 15 params

Create a postcard with custom message and font. Validates that text fits on the card. Use preview_fit first to check if your message fits. Specify recipients via existing contact IDs, group IDs, or inline recipient objects (combinable). For simpler creation from a saved template, use create_card_from_template instead.

Name Type Required Description
content string required Main message text to print on the postcard.
deliver_at string required Delivery date. Accepted values: today, tomorrow, YYYY-MM-DD, or N-days-from-now.
motive_id integer required Numeric ID of the motive (front image design) to use on the card.
content_ps string optional Optional postscript line printed after the main message (P.S.).
content_vertical string optional Optional text printed in the vertical side panel of the card.
font_color string optional Font color for the card text. Accepted values: black, blue.
font_family string optional Font family for the card text. Accepted values: architects_daughter, reenie_beanie, special_elite.
font_size integer optional Font size in pt. Allowed ranges: architects_daughter 12–14, reenie_beanie 15–17, special_elite 11–13.
group_ids array optional Array of contact group IDs. All members of each group receive the card.
notification_email string optional Email address to receive delivery notifications.
notification_send_on string optional Date to send the notification (ISO 8601, YYYY-MM-DD). Defaults to the delivery date.
notification_type string optional When to send a delivery notification. Accepted values: before_send, after_sent.
qr_code_url string optional URL to encode as a QR code printed on the card.
recipient_ids array optional Array of existing contact IDs to send the card to.
recipients array optional Array of inline recipient objects. Each requires last_name, street, zip, city, and country_code.
echtpostmcp_create_card_from_template # Create a postcard from an existing template. The template provides the message, font, and motive. Specify recipients via existing contact IDs, group IDs, or inline recipient objects (combinable). Use list_templates to find templates. 5 params

Create a postcard from an existing template. The template provides the message, font, and motive. Specify recipients via existing contact IDs, group IDs, or inline recipient objects (combinable). Use list_templates to find templates.

Name Type Required Description
deliver_at string required Delivery date. Accepted values: today, tomorrow, YYYY-MM-DD, or N-days-from-now.
template_id integer required Numeric ID of the template to use for this card.
group_ids array optional Array of contact group IDs. All members of each group receive the card.
recipient_ids array optional Array of existing contact IDs to send the card to.
recipients array optional Array of inline recipient objects. Each requires last_name, street, zip, city, and country_code.
echtpostmcp_create_contact # Create a new contact for the account. At minimum, provide last_name and a postal address (street, zip, city, country_code). Optionally assign to groups via group_ids or group_names (group_names auto-creates groups if they do not exist). 17 params

Create a new contact for the account. At minimum, provide last_name and a postal address (street, zip, city, country_code). Optionally assign to groups via group_ids or group_names (group_names auto-creates groups if they do not exist).

Name Type Required Description
city string required City for the recipient's postal address.
country_code string required ISO 3166-1 alpha-2 country code (e.g. DE for Germany).
last_name string required Recipient's last name.
street string required Street name and house number.
zip string required Postal code for the recipient's address.
birthdate string optional Contact's birthdate in ISO 8601 format (YYYY-MM-DD).
company_name string optional Company name for the recipient.
custom_salutation string optional Custom greeting line. Use when greeting_style is set to custom.
department string optional Department within the company.
external_id string optional Your own reference ID for this record.
first_name string optional Recipient's first name.
gender string optional Gender identifier. Accepted values: male_user, female_user, diverse_user.
greeting_style string optional Greeting style for the card. Accepted values: formal, informal, custom.
group_ids array optional Array of contact group IDs. All members of each group receive the card.
group_names array optional Array of group names. Groups are created automatically if they do not exist.
state_code string optional State or province code (e.g. BY for Bavaria).
title string optional Academic or professional title (e.g. Dr., Prof.).
echtpostmcp_create_group # Create a new contact group. Provide a name; optionally an external_id for your own reference. 2 params

Create a new contact group. Provide a name; optionally an external_id for your own reference.

Name Type Required Description
name string required Group name.
external_id string optional Your own reference ID for this record.
echtpostmcp_delete_contact # Delete a contact by ID. This is permanent and cannot be undone. 1 param

Delete a contact by ID. This is permanent and cannot be undone.

Name Type Required Description
id integer required Numeric ID of the contact to delete.
echtpostmcp_delete_group # Delete a contact group. Fails if the group has attached workflows. 1 param

Delete a contact group. Fails if the group has attached workflows.

Name Type Required Description
id integer required Numeric ID of the group to delete.
echtpostmcp_get_card # Get details of a specific postcard by its ID. Returns status, content, font, delivery date, and whether the card is cancelable. 1 param

Get details of a specific postcard by its ID. Returns status, content, font, delivery date, and whether the card is cancelable.

Name Type Required Description
id string required UUID of the card to retrieve.
echtpostmcp_get_contact # Get details of a specific contact by their ID. Returns all fields including first_name, last_name, greeting, address, and group_ids. 1 param

Get details of a specific contact by their ID. Returns all fields including first_name, last_name, greeting, address, and group_ids.

Name Type Required Description
id integer required Numeric ID of the contact to retrieve.
echtpostmcp_get_group # Get details of a specific contact group by ID. Returns name, external_id, and recipient count. 1 param

Get details of a specific contact group by ID. Returns name, external_id, and recipient count.

Name Type Required Description
id integer required Numeric ID of the group to retrieve.
echtpostmcp_get_me # Get account info, user email, API key metadata, and current credit balance. Use this to verify the connection and check available credits. 0 params

Get account info, user email, API key metadata, and current credit balance. Use this to verify the connection and check available credits.

echtpostmcp_get_motive # Get details of a specific motive (postcard design) by its ID. 1 param

Get details of a specific motive (postcard design) by its ID.

Name Type Required Description
id integer required Numeric ID of the motive (postcard design) to retrieve.
echtpostmcp_get_template # Get details of a specific template by ID. Returns content, font, motive, and QR code URL. 1 param

Get details of a specific template by ID. Returns content, font, motive, and QR code URL.

Name Type Required Description
id integer required Numeric ID of the template to retrieve.
echtpostmcp_list_cards # List postcards for the account. Returns id, status (pending/scheduled/sent/canceled), content, font, delivery date, and whether the card is cancelable. Supports status filter. 3 params

List postcards for the account. Returns id, status (pending/scheduled/sent/canceled), content, font, delivery date, and whether the card is cancelable. Supports status filter.

Name Type Required Description
page integer optional Page number for paginated results. Defaults to 1.
per_page integer optional Number of results per page. Defaults to 50, maximum 100.
status string optional Filter cards by status. Accepted values: pending, scheduled, sent, canceled.
echtpostmcp_list_contacts # List contacts for the account. Returns id, first_name, last_name, address, greeting, and other fields. Supports search and pagination (50 per page). 3 params

List contacts for the account. Returns id, first_name, last_name, address, greeting, and other fields. Supports search and pagination (50 per page).

Name Type Required Description
page integer optional Page number for paginated results. Defaults to 1.
per_page integer optional Number of results per page. Defaults to 50, maximum 100.
search string optional Search term to filter results by name or company.
echtpostmcp_list_credits # Show the current credit balance, how many local/foreign postcards can be sent, and the price per card in EUR. 0 params

Show the current credit balance, how many local/foreign postcards can be sent, and the price per card in EUR.

echtpostmcp_list_groups # List contact groups for the account. Groups can be used as recipients when creating cards. 2 params

List contact groups for the account. Groups can be used as recipients when creating cards.

Name Type Required Description
page integer optional Page number for paginated results. Defaults to 1.
per_page integer optional Number of results per page. Defaults to 50, maximum 100.
echtpostmcp_list_motives # List available postcard motives (designs). Returns id, name, orientation, and feature flags. Supports search by name/description. Use the motive id when creating cards. 3 params

List available postcard motives (designs). Returns id, name, orientation, and feature flags. Supports search by name/description. Use the motive id when creating cards.

Name Type Required Description
page integer optional Page number for paginated results. Defaults to 1.
per_page integer optional Number of results per page. Defaults to 50, maximum 100.
search string optional Search term to filter results by name or company.
echtpostmcp_list_templates # List available card templates for the account. Templates contain pre-configured message, font, and motive — use create_card_from_template to send one. 2 params

List available card templates for the account. Templates contain pre-configured message, font, and motive — use create_card_from_template to send one.

Name Type Required Description
page integer optional Page number for paginated results. Defaults to 1.
per_page integer optional Number of results per page. Defaults to 50, maximum 100.
echtpostmcp_preview_fit # Check if a message fits on a postcard with the given font settings. Returns fits (true/false), lines used, max lines, and a suggested smaller font size if it overflows. Use this before create_card to iterate on message length. 4 params

Check if a message fits on a postcard with the given font settings. Returns fits (true/false), lines used, max lines, and a suggested smaller font size if it overflows. Use this before create_card to iterate on message length.

Name Type Required Description
content string required Message text to check for fit on the postcard.
font_family string optional Font family for the card text. Accepted values: architects_daughter, reenie_beanie, special_elite.
font_size integer optional Font size in pt. Allowed ranges: architects_daughter 12–14, reenie_beanie 15–17, special_elite 11–13.
sample_greeting string optional Sample greeting string used to expand the {anrede} placeholder when checking fit.
echtpostmcp_update_contact # Update one or more fields on an existing contact. Optional fields not provided are left unchanged. To clear an optional field, pass an empty string. group_ids replaces all memberships; group_names additively assigns groups (auto-creating). 18 params

Update one or more fields on an existing contact. Optional fields not provided are left unchanged. To clear an optional field, pass an empty string. group_ids replaces all memberships; group_names additively assigns groups (auto-creating).

Name Type Required Description
id integer required Numeric ID of the contact to update.
birthdate string optional Contact's birthdate in ISO 8601 format (YYYY-MM-DD).
city string optional City for the recipient's postal address.
company_name string optional Company name for the recipient.
country_code string optional ISO 3166-1 alpha-2 country code (e.g. DE for Germany).
custom_salutation string optional Custom greeting line. Use when greeting_style is set to custom.
department string optional Department within the company.
external_id string optional Your own reference ID for this record.
first_name string optional Recipient's first name.
gender string optional Gender identifier. Accepted values: male_user, female_user, diverse_user.
greeting_style string optional Greeting style for the card. Accepted values: formal, informal, custom.
group_ids array optional Array of contact group IDs. All members of each group receive the card.
group_names array optional Array of group names. Groups are created automatically if they do not exist.
last_name string optional Recipient's last name.
state_code string optional State or province code (e.g. BY for Bavaria).
street string optional Street name and house number.
title string optional Academic or professional title (e.g. Dr., Prof.).
zip string optional Postal code for the recipient's address.
echtpostmcp_update_group # Update a contact group. Only provided fields are changed. 3 params

Update a contact group. Only provided fields are changed.

Name Type Required Description
id integer required Numeric ID of the group to update.
external_id string optional Your own reference ID for this record.
name string optional Group name.