API basics

Everything you can do in the app, you can do with the API. The base URL is:

https://sendocado.com/api/v1

The full API as an OpenAPI 3.1 document, for code generators and agents: https://sendocado.com/api/v1/openapi.json.

Authentication

Create a key in Settings → API keys and send it as a Bearer token. Keys start with sc_, are shown once, and work for every project you own. MCP clients that signed in with OAuth send their sco_ token the same way.

curl "https://sendocado.com/api/v1/projects/$PROJECT_ID/contacts?tag=trial&limit=50" \
  -H "Authorization: Bearer $SENDOCADO_API_KEY"

A missing or wrong key is 401 unauthorized.

Projects in the path

Everything lives in a project. Lists and creates go under the project, like /projects/{project_id}/contacts; a single thing has its own path, like /contacts/{contact_id}. An id from another account answers 404, exactly like an id that does not exist.

Request rules

• Fields are snake_case.
• Bodies are JSON. Send every field; use null for a value you do not set. A field you leave out is an error, never a silent default.
• Updates are PUT with the whole object. Changing a status (setting a campaign live, sending a broadcast) is an update with the new status.
• A create answers 201 with the full object; a delete answers 204 with no body.
• Times are milliseconds since 1970 UTC (created_at: 1790000000000). Days in stats are YYYY-MM-DD in UTC.
• Ids are opaque strings.

Lists and pages

Lists return a page of results and next_cursor. Pass it back as cursor for the next page; null means you have them all. limit is 50 by default and at most 200. Lists that can only be short (projects, API keys, webhook endpoints, sending domains) return everything at once.

Errors and limits

Errors are JSON with a type you can branch on and a message you can show; see Errors. The API allows 120 requests every 60 seconds per account; see Rate limits.

Routes by area

• Projects: A project holds its own contacts, campaigns, sender and settings. Every other route works inside one project.
• Account and keys: Your account, plan and usage, API keys, and the apps you connected over OAuth.
• Contacts: The people you email: create, update in batches, search, read their history, export or erase them.
• Unsubscribes and blocks: Who may not be emailed and why: unsubscribes, resubscribes with consent, manual blocks and unblocks.
• Campaigns: Automated series of emails: the audience, the steps and their branches, status changes, enrollments, stats and AI drafts.
• Broadcasts: One-off emails to an audience, sent now or at a time you choose.
• Transactional and test emails: One email to one address: receipts and resets from your app, and tests to your own inbox.
• Templates: Reusable content that steps, broadcasts and transactional emails can copy.
• Sends and events: Every email the project sent, what happened to it, and the event stream by type.
• Replies: Answers to your emails, received for you and tied to the email they answer.
• Senders and domains: The email provider a project sends through and the domains verified with it.
• Webhooks: Signed HTTP calls to your server when emails are delivered, bounce, get replies and more.
• Images: Images hosted for use in your emails.
• Overview: A project’s numbers over the last 7, 30 or 90 days.