concinno-skills-marketing 0.1.0

Marketing / email / form agent skills for Concinno — Mailchimp + Typeform + SendGrid via pure httpx REST (no vendor SDK bloat).

concinno-skills-marketing

Marketing / email / form agent skills for Concinno. Native Python REST wrappers — zero vendor SDK dependencies, pure httpx + MIT throughout. Covers the three most common stacks agents hit when automating marketing workflows: Mailchimp (newsletters), Typeform (surveys / lead capture), SendGrid (transactional email).

Status

MVP (0.1.0) — three one-shot tools:

Tool class	Platform	Underlying transport	Licence
MailchimpCampaign	Mailchimp	httpx (REST v3)	MIT
TypeformForm	Typeform	httpx (REST)	MIT
SendGridSend	SendGrid	httpx (REST v3 Mail)	MIT

All three platforms are reached via httpx directly; this package therefore adds zero runtime dependencies beyond httpx (already a Concinno main dep) and Concinno itself.

Install

pip install concinno-skills-marketing

Credentials

Each platform's credentials live under well-known keys in the Concinno CredentialStore, which reads (in order):

1. Process runtime overrides via CredentialStore.set(...).
2. Env var CONCINNO_CRED_<UPPER_KEY>.
3. ~/.concinno/credentials.json.

Mailchimp

Key	Env var
mailchimp_api_key	CONCINNO_CRED_MAILCHIMP_API_KEY
mailchimp_dc	CONCINNO_CRED_MAILCHIMP_DC (optional)

The data-center suffix (e.g. us21) is auto-parsed from the API key's trailing -us21 / -us1 segment when mailchimp_dc isn't provided explicitly.

Typeform

Key	Env var
typeform_token	CONCINNO_CRED_TYPEFORM_TOKEN

SendGrid

Key	Env var
sendgrid_api_key	CONCINNO_CRED_SENDGRID_API_KEY

Example ~/.concinno/credentials.json:

{
  "mailchimp_api_key": "abc123def456-us21",
  "typeform_token": "tfp_xxxxxxxxxxxxxxxxxxx",
  "sendgrid_api_key": "SG.xxxxxxxxxxxxxxxx"
}

If a token is missing the tool returns {"error": "no <service> credentials — set via CredentialStore / env"} rather than crashing.

Usage via Concinno ToolRegistry

When the consumer sets CONCINNO_LOAD_PLUGINS=1, the default registry auto-mounts every marketing tool:

import os
os.environ["CONCINNO_LOAD_PLUGINS"] = "1"

from concinno.tools.registry import get_default_registry

reg = get_default_registry()
assert {"MailchimpCampaign", "TypeformForm", "SendGridSend"} <= set(
    reg.list_deferred()
)

mc = reg.get("MailchimpCampaign")
mc.call(action="list_campaigns", limit=20)

Direct Python usage

from concinno_skills_marketing import (
    MailchimpCampaign,
    TypeformForm,
    SendGridSend,
)

# Mailchimp: list campaigns, list members, add a subscriber.
MailchimpCampaign().call(action="list_campaigns", limit=20)
MailchimpCampaign().call(action="list_members", list_id="abc123")
MailchimpCampaign().call(
    action="add_member",
    list_id="abc123",
    email_address="[e-mail]",
    status="subscribed",
)

# Typeform: read a form definition, list responses, export as CSV.
TypeformForm().call(action="get_form", form_id="Xy7aBc")
TypeformForm().call(
    action="list_responses", form_id="Xy7aBc", page_size=20
)
TypeformForm().call(
    action="export_csv", form_id="Xy7aBc", page_size=100
)

# SendGrid: transactional email.
SendGridSend().call(
    action="send",
    to="[e-mail]",
    from_email="[e-mail]",
    subject="Welcome!",
    body="Thanks for signing up.",
)

All tools return {"ok": True, ...} or a structured payload on success, or {"error": "..."} on failure — same shape as the other Concinno built-in tools. No exceptions escape the call() surface.

Concurrency

All three tools set is_concurrency_safe = False. Mailchimp enforces per-account concurrency caps (typically 10 simultaneous connections), Typeform applies tenant-scoped rate limits, and SendGrid orders message sends per API key. The Concinno scheduler will honour this automatically.

Safety caps

• Mailchimp limit clamped to 1000 (API per-page cap).
• Typeform page_size clamped to 1000 (API per-page cap).
• Typeform export_csv output capped at 1 MB of CSV bytes.
• SendGrid body ≤ 1 000 000 chars; attachments list (if supplied) must be already base64-encoded.

Licence

MIT — see LICENSE.