> ## 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.

# Sending keys

> Create a sending key for the email send API, choose between a domain key and an organization-wide key, and rotate keys safely.

export const Screenshot = ({id, src, srcDark, alt, caption}) => {
  if (!src) {
    return <Placeholder id={id} kind="screenshot" label="Screenshot coming soon" description={alt} icon={<ImageIcon />} />;
  }
  return <figure className="brd-media" data-media-id={id}>
      <img className="brd-media-frame block dark:hidden" src={src} alt={alt} />
      <img className="brd-media-frame hidden dark:block" src={srcDark || src} alt={alt} />
      {caption && <figcaption className="brd-media-caption">{caption}</figcaption>}
    </figure>;
};

Create a key your application uses to send email through the send API.

<Screenshot id="ss-email-sending-keys-hero-tab" alt="A sending domain's Sending Keys tab listing keys with their key ID, description, last used date and Active status" />

A sending key goes in the `Authorization: Bearer` header of calls to
`POST https://mailing-service.prod.brudcast.com/api/v1/send`. It starts with `bk_live_`.

<Info>
  **Before you start:** you need a sending domain of your own. Sending keys aren't available on the
  managed sending address.
</Info>

## Domain key or organization-wide key

|            | Domain sending key                                      | Organization-wide key                                     |
| ---------- | ------------------------------------------------------- | --------------------------------------------------------- |
| Created in | The domain's **Sending Keys** tab                       | **Developers > API Keys**, with the `messages:send` scope |
| Sends from | Only the domain it belongs to                           | Any sending domain your organization owns                 |
| Can also   | Nothing else. It carries only the `messages:send` scope | Whatever other scopes you give it on the platform API     |
| Best for   | One application sending from one domain                 | One application sending from several domains              |

Prefer domain keys. If a domain key leaks, it can only send from that one domain, and it can't read
contacts, change domains or touch billing.

To use an organization-wide key, add the `messages:send` scope when you create it. The scope can't be
added to an existing key later. See [API keys](/developers/api-keys).

## Create a domain sending key

<Steps>
  <Step title="Open the domain's Sending Keys tab">
    Go to **Channels > Email**, open the **Domains** tab, select the domain, then select the
    **Sending Keys** tab.
  </Step>

  <Step title="Add a key">
    Select **Add Sending Key**. In **Description**, name the application that will hold it, for
    example `Checkout service`. Select **Create Key**.
  </Step>

  <Step title="Copy the secret">
    The **Sending Key Created** dialog shows the **API Key ID** and the **API Secret Key**. The
    secret is shown once. Copy it into your application's secret store, then select **Done**.

    <Screenshot id="ss-email-sending-keys-01-created-dialog" alt="The Sending Key Created dialog showing the API Key ID and a masked API Secret Key with a warning that it is shown only once" />
  </Step>
</Steps>

The key shows **Provisioning** for a few seconds, then **Active**. It's ready to send once it's
**Active**. The **Last Used** column shows when it last authenticated.

## Use it

```bash theme={"system"}
curl -X POST https://mailing-service.prod.brudcast.com/api/v1/send \
  -H "Authorization: Bearer your_sending_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "name": "Example Co", "address": "hello@mail.example.com" },
    "to": [{ "address": "jane@example.com" }],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>"
  }'
```

The send API only accepts the key in the `Authorization: Bearer` header. For a domain key, the `from`
address must be on that key's domain. Otherwise the call fails with
`From address domain 'x' does not match sending key domain 'y'`.

More examples are in [Send your first email](/channels/email/send-your-first-email) and
[Send email over HTTP](/developers/sending/http-api).

## Regenerate a key

On the key's row, open the **More actions** menu (the three-dot icon) and select
**Regenerate Secret Key**, then **Regenerate**. The new secret is
shown once, and the old one stops working straight away, so every service using it needs the new
value.

For a change with no gap, create a second key, deploy it everywhere, then delete the first.

## Delete a key

On the key's row, open the **More actions** menu (the three-dot icon), select **Delete**, then
**Delete Key**. Anything using it fails on its next
request. Delete a key as soon as you suspect it has leaked, then create a new one.

## Related

<Columns cols={2}>
  <Card title="Send email over HTTP" icon="code" href="/developers/sending/http-api">
    The full request and response reference.
  </Card>

  <Card title="API keys" icon="key-round" href="/developers/api-keys">
    Platform API keys, scopes and organization-wide sending.
  </Card>

  <Card title="SMTP users" icon="server" href="/channels/email/smtp-users">
    Credentials for the SMTP relay.
  </Card>
</Columns>