> ## Documentation Index
> Fetch the complete documentation index at: https://dugble.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Email overview

> Send, schedule, and track transactional email with Dugble

Dugble gives your application one API for sending transactional email. Send requests are accepted asynchronously, so your application gets an immediate response while Dugble handles delivery in the background.

## Before you send

You need:

* A Dugble team and a team token with the `email:send` permission
* A verified sender domain
* A `from` sender address
* At least one `to` recipient
* A subject
* An HTML body, a plain-text body, or both

<Note>
  Keep team tokens on your server. Never expose them in browser or mobile application code.
</Note>

## Send an email

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/emails \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: welcome-user-42" \
  --data '{
    "from": "Acme <onboarding@dugble.me>",
    "to": "Ada Lovelace <ada@example.com>",
    "subject": "Welcome to Acme",
    "html": "<h1>Welcome!</h1><p>Your account is ready.</p>",
    "text": "Welcome! Your account is ready.",
    "tags": [
      { "name": "category", "value": "welcome" }
    ]
  }'
```

A successful request returns `202 Accepted` with the Dugble message ID:

```json theme={null}
{
  "success": true,
  "data": {
    "object": "email",
    "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
  }
}
```

`202 Accepted` means Dugble accepted the message for delivery. It does not mean the recipient's mail server has delivered it.

## Address formats

The required `from` field and the `to`, `cc`, `bcc`, and `reply_to` fields accept friendly-name strings:

```json theme={null}
{
  "from": "Acme <onboarding@dugble.me>",
  "to": "Ada Lovelace <ada@example.com>"
}
```

They also accept structured objects:

```json theme={null}
{
  "from": {
    "email": "onboarding@dugble.me",
    "name": "Acme"
  },
  "to": {
    "email": "ada@example.com",
    "name": "Ada Lovelace"
  }
}
```

Recipient fields accept a single address or an array. An email can include up to 50 recipients across `to`, `cc`, and `bcc`.

## Message content

Provide at least one of:

* `html` for the HTML version
* `text` for the plain-text version

Each body can be up to 1 MiB. Providing both versions gives receiving clients a suitable fallback when HTML is unavailable.

## Track a message

Retrieve the message using the ID returned by the send request:

```bash theme={null}
curl --request GET \
  --url https://api.dugble.com/emails/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 \
  --header "Authorization: Bearer $DUGBLE_API_KEY"
```

The `last_event` field reports the latest known state, including `queued`, `processing`, `submitted`, `delivered`, `delayed`, `bounced`, `complained`, `rejected`, `failed`, or `canceled`.

## Next steps

<CardGroup cols={2}>
  <Card title="Sending email" icon="paper-plane" href="/docs/emails/sending-email">
    Learn the request fields and recommended sending workflow.
  </Card>

  <Card title="Attachments" icon="paperclip" href="/docs/emails/attachments">
    Attach Base64-encoded files to an email.
  </Card>

  <Card title="Schedule email" icon="clock" href="/docs/emails/schedule-email">
    Send later, reschedule, or cancel a scheduled email.
  </Card>

  <Card title="Delivery status" icon="signal-bars" href="/docs/emails/delivery-status">
    Understand the email delivery lifecycle.
  </Card>
</CardGroup>