{
  "service": "stannp",
  "displayName": "Stannp",
  "categories": [
    "Marketing"
  ],
  "authTypes": [
    "api_key"
  ],
  "auth": [
    {
      "type": "api_key",
      "label": "API Key",
      "placeholder": "STANNP_API_KEY",
      "description": "Stannp API key used as the Basic Auth username with an empty password. Find it at the bottom of your Stannp account settings page: https://www.stannp.com/us/direct-mail-api/guide.",
      "extraFields": [
        {
          "key": "region",
          "label": "Region",
          "inputType": "text",
          "required": true,
          "secret": false,
          "placeholder": "eu",
          "description": "Stannp API region for this account. Use eu for EU/UK accounts or us for US/CA accounts."
        }
      ]
    }
  ],
  "homepageUrl": "https://www.stannp.com",
  "actions": [
    {
      "id": "stannp.add_recipients_to_group",
      "service": "stannp",
      "name": "add_recipients_to_group",
      "description": "Add one or more existing Stannp recipients to a recipient group.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "groupId": {
            "type": "integer",
            "minimum": 1,
            "description": "ID of the Stannp group to update."
          },
          "recipientIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1,
              "description": "A Stannp recipient ID."
            },
            "description": "Stannp recipient IDs to add to the group.",
            "minItems": 1
          }
        },
        "additionalProperties": false,
        "required": [
          "groupId",
          "recipientIds"
        ],
        "description": "Input for adding recipients to a Stannp group."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "addedCount": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Number of recipients Stannp reported as added."
              },
              {
                "type": "null"
              }
            ]
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "addedCount",
          "raw"
        ],
        "description": "Stannp group recipient-add output."
      }
    },
    {
      "id": "stannp.create_group",
      "service": "stannp",
      "name": "create_group",
      "description": "Create an empty Stannp recipient group.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Name of the new Stannp recipient group."
          }
        },
        "additionalProperties": false,
        "required": [
          "name"
        ],
        "description": "Input for creating a Stannp recipient group."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "groupId": {
            "type": "string",
            "description": "Created group ID as returned by Stannp."
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "groupId",
          "raw"
        ],
        "description": "Stannp group creation output."
      }
    },
    {
      "id": "stannp.create_recipient",
      "service": "stannp",
      "name": "create_recipient",
      "description": "Create a Stannp recipient and optionally add it to a group.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "groupId": {
            "type": "integer",
            "minimum": 1,
            "description": "Optional group ID to add the new recipient to."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient title, such as Mr, Mrs, or Dr."
          },
          "firstname": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient first name."
          },
          "lastname": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient last name."
          },
          "company": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient company name."
          },
          "jobTitle": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient job title."
          },
          "address1": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient address line 1."
          },
          "address2": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient address line 2."
          },
          "address3": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient address line 3."
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient city."
          },
          "county": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient county, province, or state."
          },
          "postcode": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient postal code or ZIP code."
          },
          "country": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient ISO 3166-1 alpha-2 country code."
          },
          "email": {
            "type": "string",
            "description": "Recipient email address.",
            "format": "email"
          },
          "phoneNumber": {
            "type": "string",
            "minLength": 1,
            "description": "Recipient phone number."
          },
          "refId": {
            "type": "string",
            "minLength": 1,
            "description": "External reference ID for matching a recipient across systems."
          },
          "onDuplicate": {
            "type": "string",
            "enum": [
              "update",
              "ignore",
              "duplicate"
            ],
            "description": "Duplicate handling mode when Stannp finds an existing recipient."
          },
          "testLevel": {
            "type": "string",
            "enum": [
              "email",
              "fullname",
              "initial",
              "ref_id"
            ],
            "description": "Duplicate detection strategy used by Stannp."
          },
          "customFields": {
            "type": "object",
            "additionalProperties": {
              "description": "A custom recipient field value."
            },
            "description": "Custom Stannp recipient fields to send as top-level recipient parameters."
          }
        },
        "additionalProperties": false,
        "description": "Input for creating a Stannp recipient."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "recipientId": {
            "type": "string",
            "description": "Created recipient ID as returned by Stannp."
          },
          "valid": {
            "anyOf": [
              {
                "type": "boolean",
                "description": "Whether Stannp marked the recipient as valid."
              },
              {
                "type": "null"
              }
            ]
          },
          "created": {
            "anyOf": [
              {
                "type": "string",
                "description": "Creation timestamp returned by Stannp."
              },
              {
                "type": "null"
              }
            ]
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "recipientId",
          "valid",
          "created",
          "raw"
        ],
        "description": "Stannp recipient creation output."
      }
    },
    {
      "id": "stannp.delete_group",
      "service": "stannp",
      "name": "delete_group",
      "description": "Delete a Stannp recipient group, optionally deleting its recipients.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "groupId": {
            "type": "integer",
            "minimum": 1,
            "description": "ID of the Stannp recipient group to delete."
          },
          "deleteRecipients": {
            "type": "boolean",
            "description": "Whether Stannp should completely delete recipients in the group."
          }
        },
        "additionalProperties": false,
        "required": [
          "groupId"
        ],
        "description": "Input for deleting a Stannp recipient group."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "boolean",
            "description": "Whether Stannp reported the group deletion as successful."
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "deleted",
          "raw"
        ],
        "description": "Stannp group deletion output."
      }
    },
    {
      "id": "stannp.delete_recipient",
      "service": "stannp",
      "name": "delete_recipient",
      "description": "Permanently delete a Stannp recipient by ID.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "recipientId": {
            "type": "integer",
            "minimum": 1,
            "description": "ID of the Stannp recipient to delete."
          }
        },
        "additionalProperties": false,
        "required": [
          "recipientId"
        ],
        "description": "Input for deleting a Stannp recipient."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "boolean",
            "description": "Whether Stannp reported the recipient deletion as successful."
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "deleted",
          "raw"
        ],
        "description": "Stannp recipient deletion output."
      }
    },
    {
      "id": "stannp.get_account_balance",
      "service": "stannp",
      "name": "get_account_balance",
      "description": "Retrieve the Stannp account balance for the connected regional account.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false,
        "description": "No input is required for this Stannp action."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "balance": {
            "type": "string",
            "description": "Current account balance as returned by Stannp."
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "balance",
          "raw"
        ],
        "description": "Stannp account balance output."
      }
    },
    {
      "id": "stannp.get_recipient",
      "service": "stannp",
      "name": "get_recipient",
      "description": "Retrieve a single Stannp recipient by ID.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "recipientId": {
            "type": "integer",
            "minimum": 1,
            "description": "ID of the Stannp recipient to retrieve."
          }
        },
        "additionalProperties": false,
        "required": [
          "recipientId"
        ],
        "description": "Input for retrieving one Stannp recipient."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "recipient": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Stannp recipient ID."
              },
              "account_id": {
                "type": "string",
                "description": "Stannp account ID that owns the recipient."
              },
              "title": {
                "type": "string",
                "description": "Recipient title."
              },
              "firstname": {
                "type": "string",
                "description": "Recipient first name."
              },
              "lastname": {
                "type": "string",
                "description": "Recipient last name."
              },
              "company": {
                "type": "string",
                "description": "Recipient company name."
              },
              "job_title": {
                "type": "string",
                "description": "Recipient job title."
              },
              "address1": {
                "type": "string",
                "description": "Recipient address line 1."
              },
              "address2": {
                "type": "string",
                "description": "Recipient address line 2."
              },
              "address3": {
                "type": "string",
                "description": "Recipient address line 3."
              },
              "city": {
                "type": "string",
                "description": "Recipient city or town."
              },
              "county": {
                "type": "string",
                "description": "Recipient county, province, or state."
              },
              "country": {
                "type": "string",
                "description": "Recipient ISO 3166-1 alpha-2 country code."
              },
              "postcode": {
                "type": "string",
                "description": "Recipient postal code or ZIP code."
              },
              "dps": {
                "type": "string",
                "description": "Recipient delivery point suffix when returned by Stannp."
              },
              "email": {
                "type": "string",
                "description": "Recipient email address."
              },
              "phone_number": {
                "type": "string",
                "description": "Recipient phone number."
              },
              "ref_id": {
                "type": "string",
                "description": "External reference ID for matching the recipient."
              },
              "blacklist": {
                "anyOf": [
                  {
                    "type": "boolean",
                    "description": "Recipient block-list flag as a boolean."
                  },
                  {
                    "type": "string",
                    "description": "Recipient block-list flag as returned by Stannp."
                  }
                ],
                "description": "Whether the recipient has been block listed."
              },
              "created": {
                "type": "string",
                "description": "Timestamp when the recipient was created."
              },
              "updated": {
                "type": "string",
                "description": "Timestamp when the recipient was last updated."
              }
            },
            "additionalProperties": true,
            "description": "A Stannp recipient record."
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "recipient",
          "raw"
        ],
        "description": "Stannp recipient output."
      }
    },
    {
      "id": "stannp.list_groups",
      "service": "stannp",
      "name": "list_groups",
      "description": "List Stannp recipient groups with optional offset and limit pagination.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "offset": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of records to skip before returning results."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum number of records to return."
          }
        },
        "additionalProperties": false,
        "description": "Input for listing Stannp recipient groups."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Stannp group ID."
                },
                "account_id": {
                  "type": "string",
                  "description": "Stannp account ID that owns the group."
                },
                "name": {
                  "type": "string",
                  "description": "Group name."
                },
                "created": {
                  "type": "string",
                  "description": "Timestamp when the group was created."
                },
                "recipients": {
                  "type": "string",
                  "description": "Number of recipients in the group as returned by Stannp."
                },
                "valid": {
                  "type": "string",
                  "description": "Number of valid recipients in the group as returned by Stannp."
                },
                "international": {
                  "type": "string",
                  "description": "Number of international recipients in the group."
                },
                "skipped": {
                  "type": "string",
                  "description": "Number of skipped recipients in the group."
                },
                "status": {
                  "type": "string",
                  "description": "Group calculation or import status."
                },
                "import_progress": {
                  "type": "string",
                  "description": "Group import progress as returned by Stannp."
                },
                "is_seeds": {
                  "type": "string",
                  "description": "Whether this group is a seed group as returned by Stannp."
                }
              },
              "additionalProperties": true,
              "description": "A Stannp recipient group record."
            },
            "description": "Recipient groups returned by Stannp."
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "groups",
          "raw"
        ],
        "description": "Stannp group list output."
      }
    },
    {
      "id": "stannp.list_recipients",
      "service": "stannp",
      "name": "list_recipients",
      "description": "List Stannp recipients, optionally filtered by group and paginated.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "groupId": {
            "type": "integer",
            "minimum": 1,
            "description": "Optional group ID to filter recipients."
          },
          "offset": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of records to skip before returning results."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "description": "Maximum number of records to return."
          }
        },
        "additionalProperties": false,
        "description": "Input for listing Stannp recipients."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "recipients": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Stannp recipient ID."
                },
                "account_id": {
                  "type": "string",
                  "description": "Stannp account ID that owns the recipient."
                },
                "title": {
                  "type": "string",
                  "description": "Recipient title."
                },
                "firstname": {
                  "type": "string",
                  "description": "Recipient first name."
                },
                "lastname": {
                  "type": "string",
                  "description": "Recipient last name."
                },
                "company": {
                  "type": "string",
                  "description": "Recipient company name."
                },
                "job_title": {
                  "type": "string",
                  "description": "Recipient job title."
                },
                "address1": {
                  "type": "string",
                  "description": "Recipient address line 1."
                },
                "address2": {
                  "type": "string",
                  "description": "Recipient address line 2."
                },
                "address3": {
                  "type": "string",
                  "description": "Recipient address line 3."
                },
                "city": {
                  "type": "string",
                  "description": "Recipient city or town."
                },
                "county": {
                  "type": "string",
                  "description": "Recipient county, province, or state."
                },
                "country": {
                  "type": "string",
                  "description": "Recipient ISO 3166-1 alpha-2 country code."
                },
                "postcode": {
                  "type": "string",
                  "description": "Recipient postal code or ZIP code."
                },
                "dps": {
                  "type": "string",
                  "description": "Recipient delivery point suffix when returned by Stannp."
                },
                "email": {
                  "type": "string",
                  "description": "Recipient email address."
                },
                "phone_number": {
                  "type": "string",
                  "description": "Recipient phone number."
                },
                "ref_id": {
                  "type": "string",
                  "description": "External reference ID for matching the recipient."
                },
                "blacklist": {
                  "anyOf": [
                    {
                      "type": "boolean",
                      "description": "Recipient block-list flag as a boolean."
                    },
                    {
                      "type": "string",
                      "description": "Recipient block-list flag as returned by Stannp."
                    }
                  ],
                  "description": "Whether the recipient has been block listed."
                },
                "created": {
                  "type": "string",
                  "description": "Timestamp when the recipient was created."
                },
                "updated": {
                  "type": "string",
                  "description": "Timestamp when the recipient was last updated."
                }
              },
              "additionalProperties": true,
              "description": "A Stannp recipient record."
            },
            "description": "Recipients returned by Stannp."
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "recipients",
          "raw"
        ],
        "description": "Stannp recipient list output."
      }
    },
    {
      "id": "stannp.remove_recipients_from_group",
      "service": "stannp",
      "name": "remove_recipients_from_group",
      "description": "Remove one or more existing Stannp recipients from a recipient group.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "groupId": {
            "type": "integer",
            "minimum": 1,
            "description": "ID of the Stannp group to update."
          },
          "recipientIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 1,
              "description": "A Stannp recipient ID."
            },
            "description": "Stannp recipient IDs to remove from the group.",
            "minItems": 1
          }
        },
        "additionalProperties": false,
        "required": [
          "groupId",
          "recipientIds"
        ],
        "description": "Input for removing recipients from a Stannp group."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "removedCount": {
            "anyOf": [
              {
                "type": "integer",
                "description": "Number of recipients Stannp reported as removed."
              },
              {
                "type": "null"
              }
            ]
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "removedCount",
          "raw"
        ],
        "description": "Stannp group recipient-remove output."
      }
    },
    {
      "id": "stannp.validate_address",
      "service": "stannp",
      "name": "validate_address",
      "description": "Validate and normalize a UK, US, or Canadian postal address with Stannp.",
      "requiredScopes": [],
      "providerPermissions": [],
      "inputSchema": {
        "type": "object",
        "properties": {
          "company": {
            "type": "string",
            "minLength": 1,
            "description": "Company name."
          },
          "address1": {
            "type": "string",
            "minLength": 1,
            "description": "Address line 1."
          },
          "address2": {
            "type": "string",
            "minLength": 1,
            "description": "Address line 2."
          },
          "address3": {
            "type": "string",
            "minLength": 1,
            "description": "Address line 3."
          },
          "city": {
            "type": "string",
            "minLength": 1,
            "description": "Address city."
          },
          "postcode": {
            "type": "string",
            "minLength": 1,
            "description": "Address postal code. Recommended for accurate validation."
          },
          "country": {
            "type": "string",
            "minLength": 1,
            "description": "ISO 3166-1 alpha-2 country code. Recommended for accurate validation."
          },
          "state": {
            "type": "string",
            "minLength": 1,
            "description": "Two-letter US state abbreviation."
          },
          "province": {
            "type": "string",
            "minLength": 1,
            "description": "Two-letter Canadian province abbreviation."
          },
          "zipcode": {
            "type": "string",
            "minLength": 1,
            "description": "US or Canadian ZIP/postal code. Required by Stannp if city is absent."
          }
        },
        "additionalProperties": false,
        "required": [
          "address1"
        ],
        "description": "Input for validating a postal address with Stannp."
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "isValid": {
            "type": "boolean",
            "description": "Whether Stannp considers the address valid."
          },
          "address": {
            "type": "object",
            "properties": {
              "company": {
                "type": "string",
                "description": "Company name."
              },
              "address1": {
                "type": "string",
                "description": "Address line 1."
              },
              "address2": {
                "type": "string",
                "description": "Address line 2."
              },
              "address3": {
                "type": "string",
                "description": "Address line 3."
              },
              "city": {
                "type": "string",
                "description": "City or town."
              },
              "county": {
                "type": "string",
                "description": "County, province, or state."
              },
              "postcode": {
                "type": "string",
                "description": "Postal code or ZIP code."
              },
              "country": {
                "type": "string",
                "description": "ISO 3166-1 alpha-2 country code."
              },
              "reference_id": {
                "anyOf": [
                  {
                    "type": "string",
                    "description": "Stannp address reference ID as a string."
                  },
                  {
                    "type": "integer",
                    "description": "Stannp address reference ID as a number."
                  }
                ],
                "description": "Stannp address reference ID."
              },
              "dps": {
                "type": "string",
                "description": "Delivery point suffix when returned by Stannp."
              },
              "udprn": {
                "type": "string",
                "description": "Unique delivery point reference number when returned by Stannp."
              },
              "is_valid": {
                "type": "boolean",
                "description": "Whether Stannp considers the address valid."
              }
            },
            "additionalProperties": true,
            "description": "A normalized postal address returned by Stannp."
          },
          "raw": {
            "description": "Raw Stannp response data."
          }
        },
        "additionalProperties": false,
        "required": [
          "isValid",
          "address",
          "raw"
        ],
        "description": "Stannp address validation output."
      }
    }
  ]
}