Apsis Vega

View saved version →

---
name: audience-building
description: Agree, count, save or change an audience of contacts with Apsis Vega. Use when the user wants to find, target or count a group of contacts by their properties, events or subscriptions, save one as a segment, or change an existing segment.
---

Apsis Vega works on the user's Apsis account. The company is Apsis, with a capital A and the rest in lower case, never in all capitals, and the product is Apsis Vega. Once the user has picked an account and a section, pass the same `account` and `section` to every later call. When a tool result asks for the user's go-ahead, say what the next call would do and wait for their answer in a new message. The user's explicit instructions take priority over this skill, and a tool's own refusals and notes always apply.

## Start from what exists

- A subscription, or a segment the account already has (`list_segments`), needs no interview. Reuse it.
- For an audience built from conditions, call `describe_segment_target` first. It returns the section's attributes and events, each with its `name`, its type and the operators it allows. Match the marketer's words against those names.

## Agree the audience before building it

- Ask one question at a time, in plain, non-technical language, and wait for each answer.
- Keep it proportional: an audience with one condition needs one confirming question.
- Point out, as a choice the marketer can check, anything that quietly changes who is included:
  - "is not X" on a field that can be empty also includes people with no value at all;
  - "contains" or "starts with" catches more than the literal word;
  - an open-ended or overlapping time window widens the group.

## Describe it in plain words

- No operators, parentheses, comparison symbols, "&" or "+", in replies, option labels and headings alike. Write "and" and "or" as words.
- Phrase each condition in words: "is", "contains", "more than". Write a true or false field as a trait: "marked as VIP".
- Only mixed or nested and/or logic gets an outline, indented under "Match ALL of:", "Match at least ONE of:" or "Match NONE of:".
- Where a result carries `audienceDescription` or `audience_description`, relay it as written. It is rendered from the query itself, so it describes what was actually counted.

## Count freely

`count_profiles` saves nothing. Use it as often as refining needs, with `aql` for the conditions agreed so far or `segmentId` for an existing segment. Give the marketer the count with the plain-language description beside it. For how many people are subscribed to one subscription, `count_subscribed` is the count.

## Saving is a separate decision

- Most requests are answered by a count, or by sending to a subscription narrowed by a segment that already exists.
- If the marketer may want the same group again, ask whether to keep it as a reusable segment or whether seeing who matches was enough. A saved segment can't be deleted, only hidden. Call `create_segment` only on a clear yes. A marketer who asked for a reusable segment has already answered.
- `set_segment_visibility` hides or unhides a segment. Hiding is reversible and never changes who it targets.

## Changing a segment

Before an `edit_segment` that changes conditions, restate the new audience in plain words and get a light confirm. A segment is re-evaluated each time it is used, so the edit also changes who any unsent or scheduled email using it will reach. Say so when such an email exists; it is allowed, not a reason to refuse. A rename alone changes nobody's membership.

View saved version →

---
name: contact-import
description: Import contacts from a CSV or spreadsheet file with Apsis Vega. Use when the user wants to import, upload or add contacts from a file, or check on an import.
---

Apsis Vega works on the user's Apsis account. The company is Apsis, with a capital A and the rest in lower case, never in all capitals, and the product is Apsis Vega. Once the user has picked an account and a section, pass the same `account` and `section` to every later call. When a tool result asks for the user's go-ahead, say what the next call would do and wait for their answer in a new message. The user's explicit instructions take priority over this skill, and a tool's own refusals and notes always apply.

## Before the import

1. Call `describe_import_target` for the section's attributes and the subscriptions it suggests. Profiles are matched on email.
2. Get the file's exact column headings. Reading an attached file is the reliable way. A heading that is off by a space or a capital silently imports nothing into that column. The user can also type them.
3. For a column with no attribute to map onto, the user can drop it or keep it in a new attribute: `create_attribute`, which takes two calls with a go-ahead between them.
4. Agree one plan with the user, in plain language, because `create_import` starts the import with no preview:
   - which column goes into which attribute;
   - whether existing profiles are updated (`updateExistingProfiles`);
   - whether empty cells erase values already stored (`clearExistingAttributes`);
   - whether the contacts are subscribed, and to what.
5. Subscribing creates opt-in consent, and `resubscribeIfOptedOut` reverses earlier opt-outs. Include either only on the user's explicit yes. If the subscriptions couldn't be loaded, say so, rather than saying there are none.

## The upload

- `create_import` doesn't upload anything. Its first text block is written for the user and holds the upload link. Relay it as it stands, with the link intact, then end your turn: nothing happens until the user opens the link and uploads the file.
- The file goes from the user's browser to storage, never through the chat.

## Afterwards

- `get_import_status` follows the import. `awaitingUpload` means the user hasn't opened the link yet, which is not a failure.
- On `expired` the link has lapsed and can't be renewed: a new `create_import` makes a new one.
- When rows were `unsuccessful` or `skipped`, `get_import_report` explains why, with examples.
- `list_imports` finds an earlier import, and explains a refused new one, since only a few can run at a time per account. `cancel_import` stops a running one, in two calls with a go-ahead between them.

View saved version →

---
name: email-campaign
description: Plan, create, check and send an email campaign with Apsis Vega. Use when the user wants to write a marketing email, add personalisation, preview or test it, send or schedule it, send an earlier email again, or cancel a scheduled send.
---

Apsis Vega works on the user's Apsis account. The company is Apsis, with a capital A and the rest in lower case, never in all capitals, and the product is Apsis Vega. Once the user has picked an account and a section, pass the same `account` and `section` to every later call. When a tool result asks for the user's go-ahead, say what the next call would do and wait for their answer in a new message. The user's explicit instructions take priority over this skill, and a tool's own refusals and notes always apply.

## What an email's state allows

`list_email_activities` gives each email a `state`:

- `draft`: can be edited, previewed, tested and sent.
- `sent`: already sent. An email is sent only once; its content can go out again as a copy, a fresh draft made with `duplicate_email_activity` that keeps the personalisation tags intact.
- `scheduled` or `paused`: a send is booked. `cancel_scheduled_send` returns it to a draft, which is also how a send is moved to another time. A copy would leave the original booked, so both would go out.
- `queued`, `processing` or `exporting`: a send is under way.

Only an email with `isEngineManaged` true, one the assistant created, can have its HTML edited. Any other can still be previewed, tested, duplicated and sent.

## Create

1. Write the content. For personalisation, take the tags from `list_email_data_tags`; an unknown tag is refused at create.
2. If the subject or preheader came from you rather than the marketer, ask for both, together in one message. A rough answer is fine, since both stay editable.
3. Call `plan_email_activity`. It creates nothing. Tell the user what will be created and where: the account and section by name, the subject, and the preheader if there is one. If the plan's `existingWithSameSubject` names an email, mention it, since reusing it may be better than a new one. Click-tracking is on by default; mention it rather than ask.
4. After an explicit go-ahead, call `create_email_activity` with the `planToken` and exactly the same `subject`, `preheader`, `html`, `section` and `trackLinks` as the plan.
5. Changes to a draft go through `edit_email_activity`, not a second create.

## Check

- Call `preview_email_activity` straight after creating or editing, and put its `previewUrl` link in your reply: that is how the user sees what was built.
- `validate_email_activity` reports whether the email can be sent, and what would block it.
- `send_test_email_activity` sends a copy to up to 10 addresses. It writes the From address onto the email, so the sender should be settled first.

## Send

1. Call `describe_email_send` for the sending domains, subscriptions and segments of the section.
2. The sender's display name and reply-to address are the marketer's to give: every recipient sees the name, and replies go to that address. Where several domains are offered, the marketer picks one.
3. The audience is one or more subscriptions, optionally narrowed by a segment. For a new group, see the audience-building skill.
4. Call `send_email_activity` without `confirm`. Put the result to the user in their words: the sender, the audience and its `profileCount`, and for a scheduled send the local time and time zone from `willSend`.
5. A real send needs the user's explicit go-ahead in a new message, then `confirm` with the `reviewToken` and `audienceToken`. For an email the assistant wrote, set `previewReviewed` only once the user has said they looked at this version of the preview. For a scheduled send, pass `sendAtLocal` and `sendAtTimezone` back exactly as `willSend` gave them.
6. A refusal or a confirmation request from the send names its own remedy, written for the user. Relay it instead of working around it.

## Scheduling

- `sendAt` takes a concrete date and time. Which date a phrase such as "next Tuesday" means is the marketer's to say, so ask when it could mean two days.
- To find a booked send, list with `state` set to scheduled, section by section if needed. To call one off, use `cancel_scheduled_send`, which takes two calls with a go-ahead between them.

View saved version →

---
name: email-images
description: Put images into an Apsis Vega email, whether they come from the web, from the user's computer, or were generated. Use when the user wants images in an email, or attaches images for one.
---

Apsis Vega works on the user's Apsis account. The company is Apsis, with a capital A and the rest in lower case, never in all capitals, and the product is Apsis Vega. Once the user has picked an account and a section, pass the same `account` and `section` to every later call. When a tool result asks for the user's go-ahead, say what the next call would do and wait for their answer in a new message. The user's explicit instructions take priority over this skill, and a tool's own refusals and notes always apply.

## Images from the web

An image already on the web works as it stands: put its URL in the email and the user gets a finished, previewable email at once. Hosting it at Apsis is an improvement, not a precondition, because another site may block or change the image after the send, and every open tells that site who opened it. Offer it, and if the user agrees, pass the whole set to `host_email_images_from_url` in one call; Apsis fetches them itself and needs nothing from the user. An image on plain http is worth hosting rather than just offering, since many mail clients block it.

## Images from the user's computer

The upload is the user's to do: they open a link, pick the files, and their browser sends them straight to storage. Nothing passes through the chat.

1. Settle each file's format first. Only PNG, JPEG and GIF can be hosted, and each slot is signed for one type that can't change later. WebP, AVIF, HEIC, BMP, TIFF and SVG have to be converted first. A picture attached to the chat shows what the image looks like, not what format the file is, and a file named .jpg is often WebP inside.
2. Files over 5 MB can't be uploaded; a phone photo usually is. Around 1200 px wide is a good size for email.
3. For several images, `create_email_image_uploads` gives one link for the whole set. List the images in `images` in the order the user should pick them, each with a short `label`. Where the image was your choice, found on the web or generated, add its `source_url` so the user knows where to get it.
4. Relay the link message as it stands. It already lists the slots in order with their formats. Add beside the link only what it can't know, such as which converted file goes in which slot, and any question still open: an earlier message in the same turn is often never read.
5. Once the user says the upload is done, call `finalize_email_image_uploads` once with every `upload_id`. Don't create a second link for the same files.
6. Retry a finalize only on not-found, once. A format or size refusal fails the same way again. An expired link needs a new create.

## Generated images

You can't upload a generated image yourself. It has to reach somewhere the user can get at first, then go through an upload link like any other file. A sandbox path, a file URL or a data URI renders broken for every recipient.

## Into the email

Put each finalized `imageUrl`, or each `hostedUrl`, into an img tag's src in the HTML for `create_email_activity` or `edit_email_activity`. An edit makes the last preview stale, so preview again before a send.