# API basics

Keys, request rules and pages, then every route by area.

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

```text Base URL
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](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.

```sh An authenticated request
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](https://sendocado.com/docs/errors). The API allows 120 requests every 60 seconds per account; see [Rate limits](https://sendocado.com/docs/rate-limits).

## Routes by area

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