> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brudcast.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Build on Brudcast
> The three ways to integrate with Brudcast: the platform API, the email send API and the SMTP relay, and when to use each.
Brudcast has three integration surfaces. The **platform API** manages everything in your organization.
The **email send API** and the **SMTP relay** deliver individual emails from your own application.
Most integrations use the platform API plus one of the two sending surfaces.
## The three surfaces
| Surface | What it's for | Base URL or host | Credential |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Platform API | Contacts, lists, campaigns, templates, sending domains, sender identities, mailboxes, webhooks, reports and the message log | `https://core-service.prod.brudcast.com/api/v1/user` | [API key](/developers/api-keys) |
| Email send API | Sending one email per request over HTTPS, as JSON | `POST https://mailing-service.prod.brudcast.com/api/v1/send` | Sending key, or an API key with the **Send Messages** permission |
| SMTP relay | Sending from software that already speaks SMTP: frameworks, CMSs, older systems | `out-smtp.prod.brudcast.com` on port `465` (TLS), or `587`, `2525` or `25` (STARTTLS) | SMTP user |
Each credential belongs to one organization, so you never pass an organization ID. See
[Authentication](/developers/authentication) for how each one is sent.
```mermaid theme={"system"}
flowchart LR
App["Your application"]
App -->|"API key"| Platform["Platform API"]
App -->|"Sending key"| Send["Email send API"]
App -->|"SMTP user"| Relay["SMTP relay"]
Platform -->|"campaigns"| Delivery["Brudcast delivery"]
Send --> Delivery
Relay --> Delivery
Delivery --> Servers["Recipients' mail servers"]
Delivery -.->|"webhooks"| App
```
## Which one to use
| You want to | Use |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Send transactional email from your code: receipts, password resets, alerts | The [email send API](/developers/sending/http-api). It accepts Bcc, Reply-To, custom headers and attachments |
| Send from software that only supports SMTP | The [SMTP relay](/developers/sending/smtp-relay). It rebuilds each message, so Bcc-only recipients, Reply-To and custom headers are not delivered |
| Send marketing email, SMS or push to a list | [Campaigns](/campaigns/overview), from the dashboard or the platform API's campaign endpoints |
| Keep contacts in sync with your product | The platform API. See [Sync contacts from your app](/developers/guides/sync-contacts-from-your-app) |
| Find out what happened to a message | The [message log](/developers/sending/message-status) on the platform API |
| Be told when a message is delivered, bounces or is opened | [Webhooks](/developers/webhooks/overview) |
If you can choose, pick the email send API over SMTP. It keeps every field you send, returns a
job ID you can look up later, and fails with a clear HTTP error instead of an SMTP reply code.
## What's the same everywhere
* **JSON over HTTPS.** Both APIs take and return JSON. Call them from your server with any HTTP
client.
* **Versioned paths.** Both APIs carry the version in the path: `/api/v1`. See
[Versioning](#versioning) below.
* **Two envelopes.** Platform API responses carry `success`, `message`, `data` and sometimes
`meta`. The email send API carries `status`, `message` and `data`. See
[Response format](/developers/response-format).
* **Accepted is not delivered.** A successful send means Brudcast queued the message. Delivery to
the receiving mail server comes later, and you learn about it from the message log or a webhook.
## Versioning
The version sits in the path, and `v1` is the only version there is.
| API | Versioned path |
| -------------- | ------------------------------------------------------- |
| Platform API | `https://core-service.prod.brudcast.com/api/v1/user/…` |
| Email send API | `https://mailing-service.prod.brudcast.com/api/v1/send` |
There's no version header to send. Change the path, and you change the version. The SMTP relay isn't
versioned, because it speaks standard SMTP.
Two API key scopes have been renamed: `email:send` is now `messages:send`, and `email:read` is now
`messages:read`. Keys created with the old names keep working, because Brudcast reads `email:send`
as `messages:send` and `email:read` as `messages:read` wherever it checks a scope. Use the current
names in anything new, including your own code that checks a key's scopes. See
[API keys](/developers/api-keys#scopes).
To keep your client working as the API grows, ignore response fields you don't recognize, treat an
unfamiliar status value as unknown rather than as an error, and branch on `code` and the HTTP status
rather than on `message` text.
Create a key, send an email and check its status.
Which credential works where, and how to send it.
The full request and response reference.
Every platform API endpoint.