canonical: https://jentic.com/apis/indiepitcher.com/indiepitcher

# IndiePitcher OpenAPI Spec

The IndiePitcher API sends transactional emails and mailing-list campaigns, and keeps the contact records behind them in sync with your product. It adds, finds, updates, and removes contacts by email address, accepts batch contact imports in a single call, and lets you attach custom properties and list subscriptions to each contact. Email bodies can be written in markdown or HTML, with optional open and link-click tracking, and a portal session endpoint gives each contact a hosted page to manage their own list subscriptions.

## For AI agents

Send transactional or mailing-list emails in markdown or HTML, and add, find, update, or remove IndiePitcher contacts and their list subscriptions.

## Scope

Does not handle SMS, inbound email parsing, domain DNS setup, or visual campaign design. Use for sending emails and managing IndiePitcher contacts and mailing list subscriptions only.

## Capabilities

- Send a one-off transactional email to any address with a markdown or HTML body via `/email/transactional`
- Email one or more registered contacts in the context of a mailing list, with optional delaySeconds or delayUntilDate scheduling
- Broadcast an email to every contact subscribed to a mailing list via `/email/list`
- Add a single contact or import many in one call, with name, userId, languageCode, and customProperties
- Look up a contact by email and update its list subscriptions with addedListSubscripitons and removedListSubscripitons
- Generate a hosted portal session URL where a contact manages their own mailing list subscriptions

## Use cases

### Agent-driven product emails through Jentic

An AI agent connected through Jentic sends the emails a small product needs: a welcome message on signup, a receipt, or a one-off notice to a single user. It calls the transactional send operation with a subject, a markdown body, and a bodyFormat of markdown, and can turn on trackEmailOpens and trackEmailLinkClicks when you want engagement data. The API key stays in your own Jentic One instance, so the agent never handles it.

Example prompt: Call POST `/email/transactional` with to 'jane@example.com', subject 'Welcome to Acme', body '**Thanks for signing up.**', and bodyFormat 'markdown', then confirm the response reports success

### Signup-to-mailing-list sync

Keep IndiePitcher contacts aligned with your own user table. When someone signs up, create the contact with their email, name, and userId, and subscribe them to lists through subscribedToLists. Setting updateIfExists lets the same call refresh an existing record instead of failing, and the batch import operation moves a backlog of users in one request.

Example prompt: Call POST `/contacts/create` with email 'sam@example.com', name 'Sam Lee', userId 'u_1842', subscribedToLists ['changelog'], and updateIfExists true

### Newsletter and changelog broadcasts

Send a release note or newsletter to every contact on a mailing list with one call to the list send operation, passing the list name, subject, body, and bodyFormat. Use delayUntilDate to schedule the send for a specific time rather than sending it immediately.

Example prompt: Call GET /lists to confirm the 'changelog' list exists, then POST `/email/list` with list 'changelog', subject 'What shipped in March', a markdown body, and bodyFormat 'markdown'

### Self-serve subscription management

Give each contact a hosted page to manage their own mailing list subscriptions instead of building preference screens yourself. The portal session operation takes the contactEmail and a returnURL and returns a URL you can link from your settings page or an email footer.

Example prompt: Call POST `/lists/portal_session` with contactEmail 'sam@example.com' and returnURL 'https://acme.example/settings', then return the generated portal URL to the user

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/email/transactional` | Send an email to a specified address |
| POST | `/email/list` | Send an email to contacts in a mailing list |
| POST | `/email/contact` | Send an email to one or more registered contacts |
| POST | `/contacts/create` | Add a new contact |
| POST | `/contacts/create_many` | Add multiple contacts in one call |
| GET | `/contacts/find` | Find a contact by email |
| PATCH | `/contacts/update` | Update an existing contact |
| POST | `/lists/portal_session` | Create a subscription portal session URL |

## Key resources

- **Contacts** — List, find by email, add singly or in batch, update, and remove contacts with custom properties and list subscriptions
- **Emails** — Send transactional emails, emails to specific contacts, and broadcasts to a mailing list
- **Mailing lists** — List the project's mailing lists and create portal sessions for contacts to manage subscriptions

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 52 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 93 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 26 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 66 / 100
- **View full report:** https://jentic.com/apis/indiepitcher.com/indiepitcher/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring IndiePitcher by hand means managing a project-scoped bearer key, staying under its 10 requests per second limit, and shaping markdown or HTML send payloads yourself. Through Jentic you install once, import IndiePitcher from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** IndiePitcher identifies contacts and lists by email and list name inside the request body or query string, not the URL path, so rules bound which operations your agent may call, not which contact or list. You choose the operations it may call, so ones like contact deletion or list-wide sends are not included unless you add them.
- **Credential handling:** Your IndiePitcher API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a transactional email' or 'add a contact to a mailing list', and Jentic returns the matching IndiePitcher operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Resend API** — Developer email API focused on transactional sending with domains and audiences
- **Loops API** — Email platform for SaaS with contacts, events, and transactional sends
- **Postmark Server API** — Transactional email delivery with templates, bounces, and message streams
- **Mailchimp Marketing API** — Marketing campaigns, audiences, and automation for larger email programs

## FAQ

### Is there an IndiePitcher MCP server?

You don't need an MCP server to give your agent IndiePitcher. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. The agent discovers the IndiePitcher operations it needs on demand, so no extra server's tool definitions sit in its context.

### Can I limit what my agent is allowed to do with the IndiePitcher API?

Yes. For a welcome-email agent, write a rule that allows only POST `/email/transactional` and GET `/contacts/find.` The agent can look up a contact and send it a message, but it cannot remove contacts, import batches, or broadcast to a whole mailing list, and every call it makes is logged.

### What authentication does the IndiePitcher API use?

Per its OpenAPI spec, the IndiePitcher API uses HTTP bearer authentication: send your project API key in the `Authorization` header as `Bearer <key>`. API keys are tied to a single IndiePitcher project. Through Jentic, the key is stored encrypted by your own Jentic One instance and injected when the call runs.

### Can I schedule an email for later with the IndiePitcher API?

Yes, for contact and mailing-list sends. POST `/email/contact` and POST `/email/list` accept delaySeconds to postpone the send or delayUntilDate to send at a specific time. The transactional send operation does not take these scheduling fields in the spec.

### What are the rate limits for the IndiePitcher API?

The IndiePitcher OpenAPI spec states a limit of 10 requests per second across all API keys tied to a project, after which the API returns 429 Too Many Requests and the limit resets after one second. The spec recommends batch operations such as POST `/contacts/create_many` to reduce request volume.

### How do I send a mailing-list email with the IndiePitcher API through Jentic?

Install Jentic One with `curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh`, import IndiePitcher from the API Directory, and store your API key. Your agent searches for 'send an email to a mailing list', gets POST `/email/list` with its input schema, and calls it with list, subject, body, and bodyFormat. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Does the IndiePitcher API support HTML emails?

Yes. Every send operation requires a bodyFormat field set to markdown or html, so you can write the body in markdown and let IndiePitcher render it, or pass your own HTML.