create_embedded_sending
Generate embedded sending links to manage, edit, or send signing invites for documents and document groups with configurable redirects and expiration settings.
Instructions
Create embedded sending for managing, editing, or sending invites for a document or document group
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | ID of the document or document group | |
| entity_type | No | Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. | |
| link_expiration | No | Optional link expiration in days (14-45) | |
| redirect_target | No | Optional redirect target: 'self' (default), 'blank' | |
| redirect_uri | No | Optional redirect URI after completion | |
| type | No | Type of sending step: 'manage', 'edit', or 'send-invite' | manage |
Input Schema (JSON Schema)
{
"properties": {
"entity_id": {
"description": "ID of the document or document group",
"title": "Entity Id",
"type": "string"
},
"entity_type": {
"anyOf": [
{
"enum": [
"document",
"document_group"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type.",
"title": "Entity Type"
},
"link_expiration": {
"anyOf": [
{
"maximum": 45,
"minimum": 14,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional link expiration in days (14-45)",
"title": "Link Expiration"
},
"redirect_target": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional redirect target: 'self' (default), 'blank'",
"title": "Redirect Target"
},
"redirect_uri": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional redirect URI after completion",
"title": "Redirect Uri"
},
"type": {
"anyOf": [
{
"enum": [
"manage",
"edit",
"send-invite"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "manage",
"description": "Type of sending step: 'manage', 'edit', or 'send-invite'",
"title": "Type"
}
},
"required": [
"entity_id"
],
"type": "object"
}
Implementation Reference
- MCP tool handler and registration for 'create_embedded_sending'. This function handles the tool execution, authenticates, initializes the client, and delegates to the core _create_embedded_sending helper.@mcp.tool( name="create_embedded_sending", description="Create embedded sending for managing, editing, or sending invites for a document or document group", tags=["edit", "document", "document_group", "send_invite", "embedded", "workflow"], ) def create_embedded_sending( ctx: Context, entity_id: Annotated[str, Field(description="ID of the document or document group")], entity_type: Annotated[ Literal["document", "document_group"] | None, Field(description="Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type."), ] = None, redirect_uri: Annotated[str | None, Field(description="Optional redirect URI after completion")] = None, redirect_target: Annotated[str | None, Field(description="Optional redirect target: 'self' (default), 'blank'")] = None, link_expiration: Annotated[int | None, Field(ge=14, le=45, description="Optional link expiration in days (14-45)")] = None, type: Annotated[Literal["manage", "edit", "send-invite"] | None, Field(description="Type of sending step: 'manage', 'edit', or 'send-invite'")] = "manage", ) -> CreateEmbeddedSendingResponse: """Create embedded sending for managing, editing, or sending invites for a document or document group. This tool is ONLY for documents and document groups. If you have template or template group, you have to convert it to document or document group first, using create_from_template tool Args: entity_id: ID of the document or document group entity_type: Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. redirect_uri: Optional redirect URI for the sending link redirect_target: Optional redirect target for the sending link link_expiration: Optional number of days for the sending link to expire (14-45) type: Specifies the sending step: 'manage' (default), 'edit', 'send-invite' Returns: CreateEmbeddedSendingResponse with entity type, and URL """ headers = get_http_headers() token = token_provider.get_access_token(headers) if not token: raise ValueError("No access token available") # Initialize client and use the imported function from embedded_sending module client = SignNowAPIClient(token_provider.signnow_config) return _create_embedded_sending(entity_id, entity_type, redirect_uri, redirect_target, link_expiration, type, token, client)
- Core implementation logic for creating embedded sending. Determines entity type automatically if needed, then calls specific client methods for document or document group.def _create_embedded_sending( entity_id: str, entity_type: Literal["document", "document_group"] | None, redirect_uri: str | None, redirect_target: str | None, link_expiration: int | None, sending_type: str | None, token: str, client: SignNowAPIClient, ) -> CreateEmbeddedSendingResponse: """Private function to create embedded sending for managing, editing, or sending invites for a document or document group. Args: entity_id: ID of the document or document group entity_type: Type of entity: 'document' or 'document_group' (optional). If you're passing it, make sure you know what type you have. If it's not found, try using a different type. redirect_uri: Optional redirect URI for the sending link redirect_target: Optional redirect target for the sending link link_expiration: Optional number of days for the sending link to expire (14-45) sending_type: Specifies the sending step: 'manage' (default), 'edit', 'send-invite' token: Access token for SignNow API client: SignNow API client instance Returns: CreateEmbeddedSendingResponse with entity type and URL """ # Determine entity type if not provided document_group = None # Store document group if found during auto-detection if not entity_type: # Try to determine entity type by attempting to get document group first (higher priority) try: document_group = client.get_document_group(token, entity_id) entity_type = "document_group" except Exception: # If document group not found, try document try: client.get_document(token, entity_id) entity_type = "document" except Exception: raise ValueError(f"Entity with ID {entity_id} not found as either document group or document") from None if entity_type == "document_group": # Create document group embedded sending # Get the document group if we don't have it yet if not document_group: document_group = client.get_document_group(token, entity_id) return _create_document_group_embedded_sending(client, token, entity_id, redirect_uri, redirect_target, link_expiration, sending_type) else: # Create document embedded sending return _create_document_embedded_sending(client, token, entity_id, redirect_uri, redirect_target, link_expiration, sending_type)
- Pydantic response schema returned by the tool handler.class CreateEmbeddedSendingResponse(BaseModel): """Response model for creating embedded sending.""" sending_entity: str = Field(..., description="Type of sending entity: 'document', 'document_group', or 'invite'") sending_url: str = Field(..., description="URL for the embedded sending")
- Pydantic request schema defining input parameters for the embedded sending tool (used implicitly via function annotations).class CreateEmbeddedSendingRequest(BaseModel): """Request model for creating embedded sending.""" entity_id: str = Field(..., description="ID of the document or document group") entity_type: str | None = Field(None, description="Type of entity: 'document' or 'document_group'. If not provided, will be auto-detected") redirect_uri: str | None = Field(None, description="URL to redirect to after sending is complete") redirect_target: str | None = Field("self", description="Redirect target: 'self' for same tab, 'blank' for new tab") link_expiration: int | None = Field(None, ge=14, le=45, description="Link expiration time in days (14-45)") type: str | None = Field("manage", description="Specifies the sending step: 'manage' (default), 'edit', 'send-invite'") def model_dump(self, **kwargs: Any) -> dict[str, Any]: """Override model_dump to exclude redirect_target if redirect_uri is not provided.""" data = super().model_dump(**kwargs) if (not self.redirect_uri or not self.redirect_uri.strip()) and "redirect_target" in data: del data["redirect_target"] return data