Purpose: Send a one-off email to specific recipients, with an inline subject and body or a template id.

Not for: Mail to a list or segment — that is a campaign (plunk_create_campaign then plunk_send_campaign), which respects unsubscribes properly.

Returns: Confirmation of the send.

Use when: Messaging a named person or small set of people: a receipt, a reply, a notification.

Note: Supply subject and body, or template. from is optional and falls back to the project's default sender. Sending to more than one recipient asks for confirmation first. Pass idempotencyKey to make a retry safe after a timeout.

Purpose: Record that a contact did something. Events drive workflow triggers and segment filters, and the contact is created if it does not exist.

Not for: Reading events back — that is plunk_list_events or plunk_get_contact_events. This writes one.

Returns: Confirmation that the event was recorded.

Use when: Something happened that automation should react to, or that you want to segment on later.

Note: Omitting subscribed preserves the contact's current subscription state; passing true would resubscribe someone who opted out. Works with or without PLUNK_PUBLIC_KEY: with it, one request; without it, the contact is upserted first and the event recorded against it. Pass idempotencyKey to make a retry safe after a timeout.

Purpose: Check whether an address is plausibly deliverable: syntax, disposable-domain lists, plus-addressing and MX records.

Not for: Checking whether someone is already a contact — use plunk_get_contact or plunk_lookup_contacts. This validates an address, not your database.

Returns: A verdict on the address with the reasons behind it.

Use when: Before adding an address a user typed, or when investigating bounces.

Purpose: Browse or search contacts, with cursor pagination, email search, subscription filter and sorting.

Not for: Resolving a batch of known addresses to contacts — plunk_lookup_contacts does that in one call instead of searching repeatedly.

Returns: A page of contacts with a cursor for the next page.

Use when: Exploring who is in the project, or finding a contact whose exact address you do not have.

Note: Prefer narrowing with search or subscribed over paging through everything. The subscribed filter and sorting require Plunk v0.12+.

Purpose: Fetch one contact by id, including custom data and subscription state.

Not for: Looking someone up by email address — use plunk_lookup_contacts, which takes addresses directly.

Returns: The complete contact record.

Use when: You already have a contact id and need the full picture.

Purpose: Create a contact, or update it if the email already exists. Safe to call twice.

Not for: Adding many at once, which is plunk_import_contacts.

Returns: The created or updated contact.

Use when: Adding a single person, or ensuring one exists before acting on them.

Note: Emails are normalised server-side for case and whitespace on Plunk v0.12+.

Purpose: Change a contact's email address or custom data. Only the fields supplied are modified.

Not for: Changing subscription state, which has its own tools: plunk_subscribe_contact and plunk_unsubscribe_contact.

Returns: The updated contact.

Use when: Correcting an address or setting custom fields.

Note: In the data object, null deletes a key, empty strings are ignored, and reserved keys are filtered. Changing an email to one already in use returns 409.

Purpose: Permanently delete one contact and their event history.

Not for: Stopping mail to someone, which is plunk_unsubscribe_contact — deleting loses the record that they opted out, so they can be re-added by a later import.

Returns: Confirmation of the deletion.

Use when: Genuine erasure is wanted, such as a data-deletion request.

Purpose: Opt a contact back in to marketing email.

Not for: Creating someone who does not exist yet, which is plunk_create_contact.

Returns: The updated subscription state.

Use when: Someone has asked to start receiving mail again. Do not use this to reverse an unsubscribe they chose.

Purpose: Opt a contact out of marketing email. Transactional mail is unaffected.

Not for: Erasing them, which is plunk_delete_contact. Unsubscribing keeps the record that they opted out, which is what prevents them being mailed again.

Returns: The updated subscription state.

Use when: Someone asks to stop receiving mail. This is almost always the right tool rather than deletion.

Note: If they only want a break rather than to leave, plunk_snooze_contact pauses email for a set period and resubscribes them afterwards.

Purpose: Pause marketing email to a contact for a fixed period, after which they resubscribe automatically.

Not for: A permanent opt-out, which is plunk_unsubscribe_contact. Snoozing is a break, not a goodbye.

Returns: The contact with its subscription state and the date the snooze expires.

Use when: Someone wants a rest from your email rather than to leave. Offering this instead of unsubscribing keeps the relationship and avoids a spam complaint.

Note: Requires Plunk v0.15+. While snoozed the contact counts as unsubscribed and is excluded from every send. Durations: 2_weeks, 1_month, 6_months, 1_year.

Purpose: Resolve up to 500 email addresses to contacts in one call. Reads only; nothing is created.

Not for: Browsing or searching by partial address, which is plunk_list_contacts.

Returns: The matching contacts, and which addresses had no match.

Use when: You hold a list of addresses and need their ids or subscription states — far better than one lookup per address.

Purpose: Import many contacts at once. Runs as a background job.

Not for: One person, which is plunk_create_contact.

Returns: A job id to poll with plunk_get_import_status.

Use when: Loading a list from elsewhere.

Note: Only import addresses that consented to hear from you. Importing an unconsented list is how a sending domain gets burned.

Purpose: Check how an import job started by plunk_import_contacts is progressing.

Not for: Bulk subscribe, unsubscribe or delete jobs — those are polled with plunk_get_bulk_job_status.

Returns: The job's state, progress and any errors.

Use when: After starting an import, to confirm it finished and see what failed.

Purpose: Opt up to 1000 existing contacts back in to marketing email.

Not for: Reversing unsubscribes people chose for themselves. Only use this where consent genuinely exists.

Returns: A job id to poll with plunk_get_bulk_job_status.

Use when: Correcting a mistaken mass unsubscribe, or migrating consent recorded elsewhere.

Purpose: Opt up to 1000 contacts out of marketing email.

Not for: Deleting them, which is plunk_bulk_delete_contacts.

Returns: A job id to poll with plunk_get_bulk_job_status.

Use when: Honouring a batch of opt-out requests, or suppressing a cohort that should not be mailed.

Note: Asks for confirmation before running.

Purpose: Permanently delete up to 1000 contacts and their event histories.

Not for: Stopping mail to them, which is plunk_bulk_unsubscribe_contacts — deletion loses the opt-out record, so a later import can re-add them.

Returns: A job id to poll with plunk_get_bulk_job_status.

Use when: Genuine erasure of a cohort is required.

Note: Asks for confirmation before running.

Purpose: Check how a bulk subscribe, unsubscribe or delete job is progressing.

Not for: Import jobs, which are polled with plunk_get_import_status.

Returns: The job's state, progress and any errors.

Use when: After starting a bulk operation, to confirm it completed.

Purpose: List the custom data fields in use across contacts.

Not for: The values stored in a field, which is plunk_get_field_values.

Returns: The field names in use.

Use when: Before writing a segment filter, so the field named is one that exists.

Purpose: List the distinct values stored in one custom field.

Not for: How many contacts have the field set at all, which is plunk_get_field_usage.

Returns: The distinct values for this field.

Use when: Building a segment filter and needing to know what to match against.

Purpose: Report how widely a custom field is populated across contacts.

Not for: The values themselves, which is plunk_get_field_values.

Returns: Usage figures for this field.

Use when: Deciding whether a field is worth segmenting on, or safe to delete.

Purpose: Remove a custom field and its values from every contact.

Not for: Clearing it on one contact — pass null for that key via plunk_update_contact instead.

Returns: Confirmation of the deletion.

Use when: A field is genuinely obsolete. Check plunk_get_field_usage first; segments filtering on it will stop matching.

Purpose: List campaigns with their status — draft, scheduled, sending or sent.

Not for: Performance figures. This tells you a campaign exists and what state it is in; plunk_get_campaign_stats tells you how it did.

Returns: A page of campaigns with ids, names, subjects and statuses.

Use when: You need a campaign id, or the user asks what campaigns exist or what is scheduled.

Note: Archived campaigns are hidden by default; pass archived true to see them. Search, sort and the archived filter require Plunk v0.15+.

Purpose: Fetch one campaign in full: subject, body, sender, audience configuration and status.

Not for: How it performed after sending — that is plunk_get_campaign_stats.

Returns: The complete campaign record, including its audience configuration.

Use when: Reviewing a draft before sending, or checking who a campaign is configured to reach.

Purpose: Create a campaign as a draft. It is never sent by this call.

Not for: A one-off message to specific people — that is plunk_send_transactional. A campaign targets an audience.

Returns: The created draft including its id.

Use when: Composing a newsletter or announcement for a list, segment or filtered audience.

Note: audienceType ALL reaches every subscribed contact; SEGMENT needs segmentId; FILTERED takes an inline audienceCondition. Sending is a separate, confirmed step.

Purpose: Replace a draft campaign's fields — subject, body, sender or audience.

Not for: A campaign that has already gone out. Sent mail cannot be edited; duplicate it instead with plunk_duplicate_campaign.

Returns: The updated campaign.

Use when: Revising a draft before it is sent.

Purpose: Permanently delete one campaign and its record.

Not for: Stopping a campaign that is scheduled or in flight — use plunk_cancel_campaign, which halts the send and keeps the history.

Returns: Confirmation of the deletion.

Use when: A draft is genuinely unwanted. Deleting a sent campaign also discards its performance history.

Purpose: Copy a campaign into a new draft, content and audience settings included.

Not for: Sending the same campaign again to the same people — that is usually not what is wanted, and the copy is a fresh draft either way.

Returns: The new draft including its own id.

Use when: Basing a new send on one that worked, or recovering an editable version of something already sent.

Purpose: Permanently delete up to 1000 draft campaigns in one atomic call.

Not for: A single campaign (plunk_delete_campaign), or stopping a send (plunk_cancel_campaign).

Returns: The outcome of the batch.

Use when: Clearing out accumulated drafts.

Note: Requires Plunk v0.12+. Only draft campaigns can be bulk-deleted. Asks for confirmation before running.

Purpose: Hide a campaign from the default list while keeping it and all its performance history intact.

Not for: Getting rid of one for good, which is plunk_delete_campaign and discards the history with it.

Returns: The archived campaign.

Use when: Tidying up finished or abandoned campaigns without losing the record of how they did.

Note: Requires Plunk v0.15+. Fully reversible with plunk_unarchive_campaign. Scheduled and sending campaigns cannot be archived, since they still need attention.

Purpose: Bring an archived campaign back into the default list.

Not for: Recovering a deleted campaign. Deletion is permanent; only archiving can be undone.

Returns: The restored campaign.

Use when: An archived campaign is needed again, to review or to duplicate.

Note: Requires Plunk v0.15+.

Purpose: Archive or restore up to 1000 campaigns in one call.

Not for: Deleting them, which is plunk_bulk_delete_campaigns and cannot be undone.

Returns: The outcome of the batch.

Use when: Clearing a backlog of finished campaigns out of the way in bulk.

Note: Requires Plunk v0.15+. Reversible: pass archived false to restore. No confirmation is asked because nothing is lost.

Purpose: List the individual recipients whose mail bounced, or who marked a campaign as spam.

Not for: The totals, which are in plunk_get_campaign_stats. This names the actual addresses behind those numbers.

Returns: A page of recipients with a cursor for the next page.

Use when: A campaign shows a worrying bounce or complaint rate and you need to see who, so the addresses can be cleaned up.

Note: Requires Plunk v0.15+. Capped at 100 per page. Repeated bounces and complaints are what damage a sending domain's reputation, so act on these rather than just reading them.

Purpose: Send a campaign to its configured audience, immediately or at a scheduled time.

Not for: Checking how it will look — plunk_test_campaign sends one copy to a project member without touching the audience.

Returns: Confirmation that the send has started or been scheduled.

Use when: The draft is final, the audience is right, and the mail should actually go out.

Note: Irreversible once sending begins. Asks for confirmation first, stating the real recipient count. Send a test first if the content has not been seen.

Purpose: Stop a scheduled or in-flight campaign. Mail already delivered cannot be recalled.

Not for: Removing the campaign entirely, which is plunk_delete_campaign.

Returns: Confirmation of the cancellation.

Use when: A send was started in error, or a scheduled send should no longer happen.

Note: Only stops recipients not yet reached; delivered mail cannot be recalled. On Plunk v0.15+ a cancelled campaign returns to an editable draft, so it can be fixed and sent again.

Purpose: Send one copy of a campaign to a project member, so the rendered result can be checked.

Not for: The real send, which is plunk_send_campaign. This reaches one mailbox, not the audience.

Returns: Confirmation that the test was sent.

Use when: Always, before plunk_send_campaign, when nobody has seen the rendered email yet.

Purpose: Delivery and engagement figures for one campaign: sends, opens, clicks, bounces and complaints.

Not for: A campaign's content or audience settings (plunk_get_campaign), or a comparison across campaigns (plunk_get_top_campaigns).

Returns: Counts and rates for this campaign.

Use when: The user asks how a specific campaign performed.

Note: For the actual addresses behind the bounce and complaint counts, use plunk_list_campaign_recipients.

Purpose: List saved audience segments with their names, types and current sizes.

Not for: The contacts inside a segment — that is plunk_list_segment_contacts. This returns the segments themselves.

Returns: All segments with ids, types, conditions and counts.

Use when: You need a segment id for a campaign, or the user asks what audiences exist and how big they are.

Purpose: Fetch one segment in full, including its filter condition tree.

Not for: Its members, which is plunk_list_segment_contacts.

Returns: The complete segment record with its condition.

Use when: Working out why a segment matches who it matches, before editing its filter.

Purpose: List the contacts currently in a segment.

Not for: The segment's definition, which is plunk_get_segment.

Returns: The contacts in this segment.

Use when: Checking who a campaign would actually reach before sending to this segment.

Purpose: Create a reusable audience. A DYNAMIC segment re-evaluates its filter continuously, so contacts join and leave on their own; a STATIC one holds a membership you manage by hand.

Not for: A one-off audience for a single campaign — plunk_create_campaign accepts an inline filter via audienceType FILTERED, with no segment to maintain afterwards.

Returns: The created segment including its id.

Use when: The same audience will be reused, or the user wants to see it in the dashboard.

Note: DYNAMIC requires a condition. trackMembership emits entry and exit events that workflows can trigger on.

Purpose: Change a segment's name, description or filter condition.

Not for: Adding or removing individual people from a STATIC segment — use plunk_add_segment_members and plunk_remove_segment_members.

Returns: The updated segment.

Use when: Refining who a dynamic segment should match.

Note: Changing the condition of a DYNAMIC segment changes who is in it, which changes who any campaign targeting it will reach.

Purpose: Permanently delete a segment. The contacts themselves are untouched.

Not for: Removing people from the segment while keeping it, which is plunk_remove_segment_members.

Returns: Confirmation of the deletion.

Use when: A segment is no longer needed. Campaigns configured to target it will lose their audience.

Purpose: Add contacts to a STATIC segment by email address, optionally creating any that do not exist yet.

Not for: A DYNAMIC segment, whose membership is decided by its filter — edit the condition with plunk_update_segment instead.

Returns: The result of the membership change.

Use when: Hand-curating an audience, or importing a list someone supplied.

Note: Up to 500 emails per call. createMissing decides whether unknown addresses become new contacts.

Purpose: Remove contacts from a STATIC segment. The contacts themselves are not deleted.

Not for: Deleting contacts (plunk_delete_contact) or unsubscribing them (plunk_unsubscribe_contact). This only changes membership.

Returns: The result of the membership change.

Use when: Pruning a hand-curated audience.

Note: Up to 500 emails per call.

Purpose: Force a DYNAMIC segment to re-evaluate its filter now rather than waiting for its normal refresh.

Not for: Refreshing only the displayed count, which is the cheaper plunk_refresh_segment_count.

Returns: The recomputed segment state.

Use when: Contacts or events changed and the segment must be current before you send to it.

Purpose: Recalculate a segment's cached member count.

Not for: Re-evaluating membership itself, which is plunk_compute_segment. This updates the number, not who is in it.

Returns: The refreshed count.

Use when: A displayed size looks stale and you only need the figure corrected.

Purpose: List every reusable email template in the project, with its id, name and subject.

Not for: Finding out where a template is used — that is plunk_get_template_usage. This returns the templates themselves, not their bodies in full.

Returns: All templates with ids, names and subjects.

Use when: You need a template id to reference from a send, campaign or workflow step, or the user asks what templates exist.

Purpose: Fetch one template in full, including its HTML body and subject.

Not for: Browsing what exists — use plunk_list_templates, which is far cheaper than fetching bodies one by one.

Returns: The complete template record.

Use when: You are about to edit a template and need its current body, or the user asks what a specific template says.

Purpose: Create a reusable email template that sends, campaigns and workflow steps can reference by id.

Not for: A one-off email. plunk_send_transactional takes an inline subject and body directly, with no template needed.

Returns: The created template including its id.

Use when: The same email will be sent more than once, or a workflow step needs something to point at.

Purpose: Change fields on an existing template. Only the fields supplied are modified.

Not for: Creating a variant while keeping the original — duplicate it first with plunk_duplicate_template, then edit the copy.

Returns: The updated template.

Use when: Editing copy in place, where every campaign and workflow referencing this template should pick up the change.

Note: Live campaigns and workflows referencing this template will use the new content on their next send.

Purpose: Permanently delete one template.

Not for: Clearing out many at once — plunk_bulk_delete_templates handles up to 1000 in a single atomic call.

Returns: Confirmation of the deletion.

Use when: A template is genuinely unwanted. Check plunk_get_template_usage first; the call fails if a campaign or workflow still references it.

Purpose: Copy a template, body and all, into a new independent template.

Not for: Editing the original, which is plunk_update_template.

Returns: The new copy including its own id.

Use when: Building a variant of something that works, without risking the version already in use.

Purpose: Permanently delete up to 1000 templates in one atomic call.

Not for: A single template — plunk_delete_template is clearer and its failure message is more specific.

Returns: The outcome of the batch.

Use when: Clearing out many templates at once, typically after an audit.

Note: Requires Plunk v0.12+. Atomic: if any template in the batch is still referenced by a campaign or workflow, none are deleted. Asks for confirmation before running.

Purpose: List the campaigns and workflows that reference a template.

Not for: Delivery numbers. This reports references, not opens or clicks — those are plunk_get_campaign_stats.

Returns: The campaigns and workflows pointing at this template.

Use when: Before deleting or editing a template, to see what a change would affect.

Purpose: List automation workflows with their names, triggers and enabled state.

Not for: What is currently running inside one — that is plunk_list_workflow_executions.

Returns: All workflows with ids, triggers and status.

Use when: You need a workflow id, or the user asks what automations exist and which are live.

Purpose: List the fields available to workflow conditions and template interpolation.

Not for: Contact custom fields in general, which is plunk_list_contact_fields.

Returns: The field names usable inside workflow steps and conditions.

Use when: Before writing a workflow condition or a step that interpolates values, so the reference resolves.

Purpose: Fetch one workflow in full: its trigger, every step, and the transitions connecting them.

Not for: Its run history, which is plunk_list_workflow_executions.

Returns: The complete workflow graph.

Use when: Always, before editing a workflow. Steps and transitions reference each other by id, and you need the current graph to change it safely.

Purpose: Create a workflow with its trigger. Steps and transitions are added afterwards.

Not for: A finished automation in one call. A usable workflow needs plunk_add_workflow_step and plunk_add_workflow_transition after this.

Returns: The created workflow including its id.

Use when: Starting a new automation. Create it, add steps, connect them, then enable it.

Purpose: Change a workflow's name, trigger or enabled state.

Not for: Changing what the workflow does — that is plunk_update_workflow_step and the transition tools.

Returns: The updated workflow.

Use when: Enabling or disabling an automation, or changing what sets it off.

Note: Enabling a workflow makes it live: matching contacts begin entering it, and steps that send mail will send.

Purpose: Permanently delete a workflow, its steps and its execution history.

Not for: Stopping it temporarily — set enabled to false via plunk_update_workflow, which is reversible.

Returns: Confirmation of the deletion.

Use when: An automation is genuinely retired. Contacts partway through it are dropped.

Purpose: Copy a workflow with all its steps and transitions into a new one.

Not for: Editing the original, which is plunk_update_workflow.

Returns: The new copy including its own id.

Use when: Reworking an automation without disturbing the one currently running.

Note: Requires Plunk v0.11+. The copy is created disabled and with no execution state, so it cannot start sending by accident.

Purpose: Permanently delete up to 1000 workflows, including their execution histories.

Not for: A single workflow, which is plunk_delete_workflow.

Returns: The outcome of the batch.

Use when: Clearing out abandoned automations.

Note: Requires Plunk v0.12+. Asks for confirmation before running.

Purpose: Add a step to a workflow — send an email, wait, branch on a condition, call a webhook, or update the contact.

Not for: Slotting a step between two that are already connected — plunk_insert_workflow_step does that in one call and rewires both sides. A step added here is orphaned until plunk_add_workflow_transition wires it in.

Returns: The created step including its id, needed for transitions.

Use when: Building out what an automation does, one step at a time.

Note: DELAY is capped at 365 days. WEBHOOK url, headers and body interpolate template variables on v0.12+. UPDATE_CONTACT accepts subscriptionAction to change subscription state as part of the step.

Purpose: Change an existing step's configuration or position.

Not for: Changing which step follows which — that is the transition tools.

Returns: The updated step.

Use when: Adjusting a delay, swapping the template a send step uses, or fixing a condition.

Note: Editing a step in an enabled workflow affects contacts already partway through it.

Purpose: Remove one step from a workflow.

Not for: Deleting the whole workflow, which is plunk_delete_workflow.

Returns: Confirmation of the deletion.

Use when: Removing a step from the graph.

Note: Transitions into and out of this step are left dangling. Fetch the workflow with plunk_get_workflow afterwards and reconnect the graph, or contacts will stall where the step used to be.

Purpose: Connect one step to another, defining what happens next and under which condition.

Not for: Creating the steps themselves, which is plunk_add_workflow_step. Both ends must exist first.

Returns: The created transition including its id.

Use when: Wiring a newly added step into the workflow, or branching on a condition.

Purpose: Add a step in the middle of an existing connection, so A to B becomes A to the new step to B, with both connections rewired for you.

Not for: Adding a step at the end or start of a branch — plunk_add_workflow_step plus plunk_add_workflow_transition is the way to do that.

Returns: The created step including its id.

Use when: Slotting a step into a workflow that already runs. This is safer than deleting a connection and rebuilding it by hand, because the graph is never left broken partway through.

Note: Requires Plunk v0.13+. Plunk validates the resulting connections, so a change that would strand contacts is rejected rather than half-applied.

Purpose: Remove a connection between two steps.

Not for: Deleting either step, which is plunk_delete_workflow_step.

Returns: Confirmation of the deletion.

Use when: Rerouting a workflow. Removing a transition can strand the steps downstream of it, so check the graph afterwards.

Purpose: Put one contact into a workflow immediately, without waiting for its trigger to fire.

Not for: Testing what a workflow does. This is a real run against a real contact, and steps that send mail will send it.

Returns: The created execution including its id.

Use when: A contact should go through an automation that its trigger would not catch.

Note: Irreversible once mail goes out. Cancel with plunk_cancel_workflow_execution, which only stops steps that have not run yet.

Purpose: List runs of a workflow: which contacts are in it, where they have reached, and which have finished.

Not for: The workflow's definition, which is plunk_get_workflow.

Returns: Executions with their contacts, states and current steps.

Use when: Checking whether an automation is working, or how many people are partway through it.

Purpose: Fetch one execution in detail: the steps taken, the current position and what is scheduled next.

Not for: A list of runs, which is plunk_list_workflow_executions.

Returns: The full execution record.

Use when: Working out why one specific contact is stuck, or what they have already been sent.

Purpose: Stop one contact's run of a workflow. Mail already sent cannot be recalled.

Not for: Stopping the workflow for everyone, which is plunk_cancel_all_workflow_executions, or disabling it via plunk_update_workflow.

Returns: Confirmation of the cancellation.

Use when: One contact should not continue — they replied, unsubscribed, or entered by mistake.

Purpose: Stop every in-flight run of a workflow at once.

Not for: Preventing new entries. Disable the workflow with plunk_update_workflow, or contacts will keep entering after this.

Returns: The number of executions cancelled.

Use when: An automation is misbehaving and everyone in it should stop where they are.

Note: Contacts stop mid-flow and scheduled steps do not run. Asks for confirmation before running.

Purpose: List event records across the project — what fired, for whom, and when.

Not for: The distinct set of event names (plunk_list_event_names), or one contact's history (plunk_get_contact_events).

Returns: Event records.

Use when: Investigating what has actually been tracked, rather than what could be.

Purpose: Aggregate statistics across tracked events.

Not for: A ranking of the busiest events, which is plunk_get_top_events.

Returns: Aggregate event figures.

Use when: Summarising event volume for the project.

Purpose: List the distinct event names that have been tracked, which are the valid values for workflow triggers and segment filters.

Not for: Delivery activity types like open and bounce — those are plunk_list_activity_types.

Returns: The distinct event names in use.

Use when: Before building a workflow trigger or an event-based segment filter, so the name used is one that actually fires.

Purpose: List every event recorded for one contact, in order.

Not for: Delivery activity for that contact — opens and clicks live in plunk_get_activity.

Returns: That contact's event history.

Use when: Working out why a contact did or did not enter a workflow or segment.

Purpose: Show where an event name is referenced — which workflows trigger on it and which segments filter by it.

Not for: How often it fired, which is plunk_get_event_stats or plunk_get_top_events.

Returns: The workflows and segments referencing this event.

Use when: Before deleting or renaming an event, to see what would break.

Purpose: Delete an event and its recorded history from the project.

Not for: Removing one contact's event record. This removes the event across the project.

Returns: Confirmation of the deletion.

Use when: An event name was created in error and nothing references it. Check plunk_get_event_usage first — workflows and segments that trigger on it will stop working.

Purpose: List the project's sending domains and whether each is verified.

Not for: Checking whether one address is deliverable, which is plunk_verify_email.

Returns: Domains with their verification status and DNS records.

Use when: Before sending, to confirm the from address sits on a verified domain.

Note: Requires the project UUID, which is not derivable from the API key. It is in the dashboard URL.

Purpose: Register a new sending domain and get the DKIM and SPF records to place in DNS.

Not for: Re-checking a domain already added — that is plunk_verify_domain.

Returns: The created domain with the DNS records that must be configured.

Use when: Setting up a new from address on a domain Plunk does not yet know about.

Note: Adding a domain via an API key skips the admin-role check the dashboard applies, so this grants authority a non-admin project member does not have.

Purpose: Re-check a domain's DNS records and report whether verification now passes.

Not for: Adding the domain in the first place (plunk_add_domain) or validating a single address (plunk_verify_email).

Returns: Current verification status per record.

Use when: DNS records were just published and you want to know whether they have propagated.

Purpose: Remove a sending domain from the project.

Not for: Temporarily pausing sending. There is no undo short of re-adding the domain and verifying DNS again.

Returns: Confirmation of removal.

Use when: A domain is genuinely retired. Nothing can be sent from it afterwards.

Note: Asks for confirmation before running. Like plunk_add_domain, this skips the admin-role check when called with an API key.

Purpose: Read the project activity feed: sends, opens, clicks, bounces and complaints as they happened, newest first.

Not for: Aggregate numbers. For totals use plunk_get_activity_stats; for one campaign's performance use plunk_get_campaign_stats.

Returns: A page of individual activity records.

Use when: Investigating what actually happened to a specific contact or in a specific window, rather than how much happened overall.

Purpose: Aggregate counts across the activity feed — totals per activity type for the project.

Not for: Per-campaign performance (plunk_get_campaign_stats) or a movement over time (plunk_get_analytics_timeseries).

Returns: Totals by activity type.

Use when: The user wants project-wide numbers rather than individual events.

Purpose: A single cached number: how much activity the project has seen recently.

Not for: Anything you intend to break down. It is one figure, cached for speed, with no dimensions to slice.

Returns: One count.

Use when: Answering whether anything is happening at all, cheaply, before deciding what to look at properly.

Purpose: List the activity types this Plunk instance records, which are the valid filter values for the activity feed.

Not for: Event names you track yourself — those are plunk_list_event_names. These are delivery-level types like open and bounce.

Returns: The available activity type identifiers.

Use when: Before filtering plunk_get_activity, so the filter uses a type this instance actually records.

Purpose: List mail that is scheduled but has not gone out yet, across campaigns and workflows.

Not for: What has already been sent, which is plunk_get_activity.

Returns: Scheduled sends with their times.

Use when: Checking what is about to go out — worth doing before sending anything else, and before cancelling a campaign.

Purpose: Email metrics bucketed over a time range, so a trend can be read rather than a single total.

Not for: One campaign's numbers (plunk_get_campaign_stats) or a ranking (plunk_get_top_campaigns). This is the shape of a movement over time.

Returns: Time-bucketed metric series.

Use when: The question is about direction — whether opens are rising, whether bounces spiked, what a given week looked like.

Purpose: Rank campaigns by performance across a period.

Not for: A full list of campaigns (plunk_list_campaigns) or one campaign in depth (plunk_get_campaign_stats). This is a leaderboard.

Returns: Campaigns ordered by performance.

Use when: The user asks what worked best, or you need the strongest performers without fetching every campaign.

Purpose: Comparative campaign statistics across the project, broken down for analysis.

Not for: A single campaign's headline numbers — plunk_get_campaign_stats is the direct answer for that.

Returns: Per-campaign statistics across the selected range.

Use when: Comparing campaigns against each other rather than reading one in isolation.

Purpose: Rank tracked events by how often they fired across a period.

Not for: One event's detail (plunk_get_event_stats) or the list of event names that exist (plunk_list_event_names).

Returns: Events ordered by volume.

Use when: Finding out what your contacts actually do most, or which events are worth building a workflow around.

Purpose: Upload an image to Plunk's storage and get back a URL usable in template and campaign HTML.

Not for: File attachments on an email — those go inline as base64 in plunk_send_transactional's attachments field.

Returns: The hosted URL of the uploaded image.

Use when: A template or campaign body needs an image that is not already hosted somewhere public.