Library API Guide

The Library API lets you discover, share, and copy reusable resources — email templates, text templates, automations, and smart lists — across teams. Teams can browse an official catalog, submit their own items for publication, bookmark favorites, and leave reviews on items they've copied.

Overview

A library item wraps one of four resource types:

`itemType`	Underlying record
`email_template`	`EmailTemplate`
`text_template`	`TextTemplate`
`automation`	`Automation`
`smart_list`	`SmartList`

Each library item carries a visibility and a status that together decide who can see it:

`visibility`	Who can see it
`private`	Only the owning team
`shared`	The owning team plus teams listed in `sharedWithTeamIds`
`public`	Every team (after admin approval)

`status`	Meaning
`pending`	Submitted to the public marketplace, awaiting admin review
`approved`	Live and browsable
`rejected`	Turned down by an admin
`archived`	Retired, no longer listed
`outdated`	Superseded by a newer version (official items only)

Items can be either community (submitted by any team) or official (curated). The isOfficial flag on the response distinguishes them.

Browsing Items

Endpoint: GET /api/partner/library

curl "https://api.suresend.ai/api/partner/library?itemType=email_template&sort=trending&limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query parameters

Parameter	Description
`itemType`	Filter by type: `email_template`, `text_template`, `automation`, `smart_list`
`category`	Filter by category name
`search`	Full-text search across name and description
`tag`	Filter by a single tag
`featured`	Set to `true` to return only featured items
`source`	`official`, `community`, or `my_team`
`includeOutdated`	Set to `true` to include officially-outdated items in results
`favorites`	Set to `true` to return only items the current user has favorited
`sort`	`trending`, `copyCount`, `createdAt`, `publishedAt`, `averageRating`, `favoriteCount`, or `name`
`direction`	`asc` or `desc` (defaults to `desc`)
`page`	Page number (defaults to `1`)
`limit` / `perPage`	Items per page (default `20`, max `100`)

Item response shape

{
  "libraryItems": [
    {
      "id": "item-uuid",
      "name": "New Lead Welcome",
      "description": "A 5-email nurture sequence for new leads",
      "itemType": "automation",
      "category": "Onboarding",
      "tags": ["nurture", "welcome"],
      "status": "approved",
      "isOfficial": true,
      "isFeatured": false,
      "isCommunity": false,
      "isOwnTeam": false,
      "visibility": "public",
      "sharedWithTeamIds": [],
      "version": 3,
      "copyCount": 142,
      "favoriteCount": 27,
      "reviewCount": 8,
      "averageRating": 4.6,
      "contributorName": "Sure Send",
      "contributorTeamName": "Sure Send",
      "sourceType": null,
      "sourceId": null,
      "outdatedReason": null,
      "canGoPublic": false,
      "hasCopied": true,
      "copiedVersion": 2,
      "lastCopiedAt": "2026-03-15T14:22:00Z",
      "teamCopyCount": 1,
      "updateAvailable": true,
      "publishedAt": "2026-01-10T00:00:00Z",
      "createdAt": "2026-01-10T00:00:00Z",
      "updatedAt": "2026-04-01T12:00:00Z"
    }
  ],
  "meta": {
    "total_count": 58,
    "current_page": 1,
    "total_pages": 3,
    "per_page": 20
  }
}

updateAvailable is true when your team has copied the item and the library's version is higher than your copiedVersion — i.e. a new revision is available to pull.

Showing a single item

Endpoint: GET /api/partner/library/:id

Returns the full item response plus these additional fields:

Field	Description
`templateData`	The actual payload used by the copy flow (JSON structure depends on `itemType`)
`isFavorited`	`true` if the current user has favorited this item
`hasReviewed`	`true` if the current user has posted a review
`userReview`	Your review (`id`, `rating`, `reviewText`) if one exists

curl https://api.suresend.ai/api/partner/library/ITEM_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Copying an Item

One-click copy into your team. For smart_list items, any custom fields referenced by the saved filters are auto-created on your team if they don't already exist.

Endpoint: POST /api/partner/library/:id/copy

curl -X POST https://api.suresend.ai/api/partner/library/ITEM_ID/copy \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "message": "Successfully copied to your team",
  "recordType": "automation",
  "recordId": "new-record-uuid",
  "warnings": []
}

recordId is the ID of the newly-created resource in your team (an EmailTemplate, TextTemplate, Automation, or SmartList). warnings may contain non-fatal notes such as automation dependencies that couldn't be resolved.

Bulk copy

Endpoint: POST /api/partner/library/bulkCopy

Copy up to 100 items in a single call. IDs beyond the first 100 are silently dropped.

curl -X POST https://api.suresend.ai/api/partner/library/bulkCopy \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "itemIds": ["id-1", "id-2", "id-3"] }'

Response:

{
  "results": [
    { "item_id": "id-1", "item_name": "...", "item_type": "email_template",
      "status": "success", "record_id": "new-uuid", "warnings": [] },
    { "item_id": "id-2", "item_name": "...", "item_type": "automation",
      "status": "skipped", "reason": "Own team item" },
    { "item_id": "id-3", "item_name": "...", "item_type": "smart_list",
      "status": "failed", "error": "..." }
  ],
  "summary": {
    "total": 3,
    "succeeded": 1,
    "failed": 1,
    "skipped": 1,
    "warnings_count": 0
  }
}

Submitting an Item

There are two flows for getting your own content into the Library.

1. Create a private item

POST /api/partner/library creates an item that immediately has status: "approved" and visibility: "private" — only your team can see it. Use this to curate an internal library.

curl -X POST https://api.suresend.ai/api/partner/library \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Our Standard Welcome",
    "description": "The email we send to every new lead",
    "itemType": "email_template",
    "category": "Onboarding",
    "tags": ["welcome"],
    "sourceType": "EmailTemplate",
    "sourceId": "email-template-uuid",
    "templateData": { /* snapshot of the template */ }
  }'

2. Submit for the public marketplace

POST /api/partner/library/submit creates the item with status: "pending" and notifies admins. Once approved, the item becomes publicly browsable.

curl -X POST https://api.suresend.ai/api/partner/library/submit \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Lead Welcome",
    "description": "A proven 5-email nurture",
    "itemType": "automation",
    "category": "Onboarding",
    "tags": ["nurture", "welcome"],
    "sourceType": "Automation",
    "sourceId": "automation-uuid",
    "templateData": { /* automation config */ }
  }'

Accepted fields

Field	Required	Description
`name`	✓	Display name
`description`		Long description
`itemType`	✓	One of the four types above
`category`		Category name (see `/libraryCategories`)
`tags`		Array of short tag strings
`contributorName`		Defaults to the submitting user's full name
`sourceType`		`EmailTemplate`, `TextTemplate`, `Automation`, or `SmartList` — links the library item back to the local record it was built from
`sourceId`		ID of that source record
`templateData`	✓	The JSON payload used by the copy flow

Finding a submission from a local record

Use this to check whether one of your team's resources has already been submitted to the library (e.g. to show "Already in Library" in your UI).

Endpoint: GET /api/partner/library/findBySource?sourceType=Automation&sourceId=uuid

Returns either the full item show response or { "exists": false }.

Editing a pending submission

While status is still pending, the submitter can edit or withdraw.

# Edit
curl -X PATCH https://api.suresend.ai/api/partner/library/ITEM_ID/updateSubmission \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Updated name", "tags": ["nurture"] }'

# Withdraw (deletes the pending submission)
curl -X DELETE https://api.suresend.ai/api/partner/library/ITEM_ID/withdraw \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Listing your submissions

Endpoint: GET /api/partner/library/mySubmissions

Returns every community item submitted by the current user, including rejectionReason and reviewedAt when applicable.

Updating & Versioning

Update a library item you own:

Endpoint: PATCH /api/partner/library/:id

curl -X PATCH https://api.suresend.ai/api/partner/library/ITEM_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "templateData": { /* new content */ } }'

Allowed fields: name, description, category, tags, templateData.

Versioning behavior: when name, description, or templateData changes, the server automatically bumps version by 1. Teams that have already copied the item will see updateAvailable: true until they re-copy. If the item was public, it is automatically demoted to private and must be re-submitted for review.

Sharing & Visibility

Items default to private. Owners can expand visibility without admin approval in two ways:

Share with specific teams

Endpoint: PATCH /api/partner/library/:id/updateSharing

curl -X PATCH https://api.suresend.ai/api/partner/library/ITEM_ID/updateSharing \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visibility": "shared",
    "sharedWithTeamIds": ["team-uuid-1", "team-uuid-2"]
  }'

Response: { "visibility": "shared", "sharedWithTeamIds": [...] }

Use /api/partner/library/validateTeams?teamIds[]=id1&teamIds[]=id2 to confirm team IDs before writing them (max 20 IDs per call):

{
  "teams": [
    { "id": "team-uuid-1", "valid": true, "name": "Acme Co." },
    { "id": "team-uuid-2", "valid": false, "name": null }
  ]
}

Request public listing

Setting visibility to public directly is rejected with a 403 — it requires admin approval. Use the dedicated endpoint instead:

Endpoint: POST /api/partner/library/:id/requestPublish

curl -X POST https://api.suresend.ai/api/partner/library/ITEM_ID/requestPublish \
  -H "Authorization: Bearer YOUR_API_TOKEN"

This routes the item to admin review. The item's canGoPublic field indicates whether the owner currently has permission to initiate this request.

Reviews

Ratings are 1–5 stars. An optional review body up to 2000 characters can accompany the rating.

Important: you can only review an item you have actually copied into your team. Reviews on items you haven't copied are rejected.

Create or update a review

Endpoint: POST /api/partner/library/:id/review

Posting a review is idempotent — if you already have one, it's updated in place.

curl -X POST https://api.suresend.ai/api/partner/library/ITEM_ID/review \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "rating": 5, "reviewText": "Worked great for our team." }'

Response:

{
  "id": "review-uuid",
  "rating": 5,
  "reviewText": "Worked great for our team.",
  "userName": "Jane Doe",
  "createdAt": "2026-04-20T12:00:00Z",
  "updatedAt": "2026-04-20T12:00:00Z"
}

Delete your review

Endpoint: DELETE /api/partner/library/:id/review

Returns 204 No Content.

List reviews

Endpoint: GET /api/partner/library/:id/reviews?page=1&limit=10

Default limit is 10, max 100. Reviews hidden by moderators are excluded.

{
  "reviews": [
    {
      "id": "review-uuid",
      "rating": 5,
      "reviewText": "Worked great for our team.",
      "userName": "Jane Doe",
      "createdAt": "2026-04-20T12:00:00Z",
      "updatedAt": "2026-04-20T12:00:00Z"
    }
  ],
  "meta": {
    "total_count": 8,
    "current_page": 1,
    "total_pages": 1,
    "per_page": 10
  }
}

Favorites

Favoriting bookmarks an item for the current user. The library item's favoriteCount reflects favorites across all users.

# Favorite
curl -X POST https://api.suresend.ai/api/partner/library/ITEM_ID/favorite \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Unfavorite
curl -X DELETE https://api.suresend.ai/api/partner/library/ITEM_ID/favorite \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Both return:

{ "favorited": true, "favoriteCount": 28 }

Discovery helpers

Related items

Endpoint: GET /api/partner/library/:id/related

Returns up to 6 items of the same type and category, ordered by copyCount. If fewer than 6 same-category items exist, results are backfilled with other popular items of the same type.

Response: { "libraryItems": [ ... ] }

Popular tags

Endpoint: GET /api/partner/library/popularTags

Returns the 20 most-used tags across items visible to your team.

[
  { "tag": "welcome", "count": 42 },
  { "tag": "follow-up", "count": 31 }
]

Activity feed

Endpoint: GET /api/partner/library/:id/activity?page=1&limit=20

An append-only log of copies, submissions, and reviews for an item. Available to the owning team only.

{
  "events": [
    { "eventType": "copied", "teamName": "Acme Co.", "copiedVersion": 3, "occurredAt": "..." },
    { "eventType": "reviewed", "userName": "Jane Doe", "rating": 5, "occurredAt": "..." },
    { "eventType": "submitted", "userName": "...", "occurredAt": "..." }
  ],
  "meta": { "total_count": 40, "current_page": 1, "total_pages": 2, "per_page": 20 }
}

Collections

Collections are curated groups of library items, useful for themed bundles ("Recruiting starter pack", "Q1 campaigns", etc.). Like items, collections have a visibility and a status, but the status vocabulary is different:

`visibility`	Values
`private`, `shared`, `public`	Same meaning as items

`status`	Meaning
`draft`	Being built; not yet submitted
`pending_approval`	Submitted for public listing
`approved`	Live
`rejected`	Turned down

Listing collections

Endpoint: GET /api/partner/libraryCollections?search=...&page=1&limit=20

Returns collections your team can see (own drafts, shared, and public).

Showing a collection

Endpoint: GET /api/partner/libraryCollections/:id

{
  "id": "collection-uuid",
  "name": "Recruiting starter pack",
  "description": "Everything a new recruiter needs",
  "visibility": "public",
  "status": "approved",
  "sharedWithTeamIds": [],
  "itemsCount": 8,
  "position": 0,
  "rejectionReason": null,
  "submittedAt": "...",
  "reviewedAt": "...",
  "createdAt": "...",
  "updatedAt": "...",
  "createdBy": { "id": "user-uuid", "name": "Jane Doe" },
  "team":      { "id": "team-uuid", "name": "Acme Co." },
  "isOwner": true,
  "canEdit": true,
  "canAddItems": true,
  "items": [
    { "position": 0, "id": "item-uuid", "name": "...", "itemType": "automation", "..." : "..." }
  ]
}

When you view a collection belonging to another team, items is automatically filtered to only those you're allowed to see.

Creating, updating, and deleting

# Create
curl -X POST https://api.suresend.ai/api/partner/libraryCollections \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Recruiting starter pack", "description": "..." }'

# Update (name, description, visibility, position, sharedWithTeamIds)
curl -X PATCH https://api.suresend.ai/api/partner/libraryCollections/COLLECTION_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "New name", "visibility": "shared", "sharedWithTeamIds": ["team-uuid"] }'

# Delete
curl -X DELETE https://api.suresend.ai/api/partner/libraryCollections/COLLECTION_ID \
  -H "Authorization: Bearer YOUR_API_TOKEN"

As with items, you cannot set visibility: "public" directly — use submitForApproval (see below). Only the collection's creator, team admin, or team owner can update or delete it.

Managing items in a collection

# Add one of your team's library items
curl -X POST https://api.suresend.ai/api/partner/libraryCollections/COLLECTION_ID/addItem \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "libraryItemId": "item-uuid" }'

# Remove an item
curl -X DELETE https://api.suresend.ai/api/partner/libraryCollections/COLLECTION_ID/removeItem \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "libraryItemId": "item-uuid" }'

# Reorder items (pass the desired final order)
curl -X PATCH https://api.suresend.ai/api/partner/libraryCollections/COLLECTION_ID/reorderItems \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "itemIds": ["item-a", "item-b", "item-c"] }'

Only items owned by your team can be added to a collection.

Submitting a collection for public listing

Endpoint: PATCH /api/partner/libraryCollections/:id/submitForApproval

Moves the collection into status: "pending_approval" and notifies admins.

curl -X PATCH https://api.suresend.ai/api/partner/libraryCollections/COLLECTION_ID/submitForApproval \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Errors

All library endpoints return standard HTTP status codes. Error bodies follow this shape:

{ "errorMessage": "Human-readable description" }

Common codes:

Code	Meaning
`400`	Missing required parameter (e.g. `sourceType`/`sourceId` on `findBySource`, empty `itemIds` on `bulkCopy`)
`401`	Missing or invalid API token
`403`	Action not permitted (e.g. setting `visibility: "public"` directly, editing a non-pending submission, managing another team's collection)
`404`	Item not found or not visible to your team
`422`	Validation failed — see `errorMessage` for details

Common patterns

"Already in the library?" — before showing a "Submit" button, call GET /library/findBySource?sourceType=...&sourceId=.... If the item exists, you can show its current status and link to it instead.

"Update available" — when listing your own copies, the updateAvailable flag on each library item tells you whether a newer version exists upstream. Hit POST /library/:id/copy again to re-copy.

"Team-wide sharing" — to share an item with a specific set of partner teams, first validate their IDs via GET /library/validateTeams, then call PATCH /library/:id/updateSharing with visibility: "shared" and sharedWithTeamIds.

Building a marketplace UI — combine GET /library?sort=trending, GET /library/popularTags, and GET /libraryCategories for a discovery surface; use GET /libraryCollections for curated bundles.