---
title: "useEmailStatus"
description: "useEmailStatus, auto-imported in the app: its options, return value and types."
canonical_url: "https://nuxt-backend.dev/docs/reference/api/use-email-status"
---
# useEmailStatus

## Interfaces

### EmailStatus

Defined in: [src/runtime/vue/composables/use-email-status.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts)

Email delivery status (mirrors the component `status` query).

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="status">
        
      </a>
      
       <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="errormessage">
        
      </a>
      
       <code>
        errorMessage
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
      
       | <code>
        null
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="bounced">
        
      </a>
      
       <code>
        bounced
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="complained">
        
      </a>
      
       <code>
        complained
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="failed">
        
      </a>
      
       <code>
        failed
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="deliverydelayed">
        
      </a>
      
       <code>
        deliveryDelayed
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="opened">
        
      </a>
      
       <code>
        opened
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="clicked">
        
      </a>
      
       <code>
        clicked
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### EmailApi

Defined in: [src/runtime/vue/composables/use-email-status.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts)

The `email` function group re-exported from your `backend/email.ts`.

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="getemailstatus">
        
      </a>
      
       <code>
        getEmailStatus?
      </code>
    </td>
    
    <td>
      <a href="https://docs.convex.dev/api/modules/server#functionreference" rel="nofollow">
        <code>
          FunctionReference
        </code>
      </a>
      
      <<code>
        "query"
      </code>
      
      , <code>
        "public"
      </code>
      
      , { <code>
        emailId
      </code>
      
      : <code>
        string
      </code>
      
      ; }, <a href="#emailstatus">
        <code>
          EmailStatus
        </code>
      </a>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### UseEmailStatusOptions

Defined in: [src/runtime/vue/composables/use-email-status.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="emailid">
        
      </a>
      
       <code>
        emailId
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        null
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      The email to track (a value, ref or getter), as <code>
        send
      </code>
      
       returned it. Tracking pauses while it is <code>
        null
      </code>
      
      , <code>
        undefined
      </code>
      
       or blank.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="api">
        
      </a>
      
       <code>
        api?
      </code>
    </td>
    
    <td>
      <a href="#emailapi">
        <code>
          EmailApi
        </code>
      </a>
    </td>
    
    <td>
      Override the injected <code>
        api.email
      </code>
      
       namespace (or the <code>
        getEmailStatus
      </code>
      
       ref).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### UseEmailStatusReturn

Defined in: [src/runtime/vue/composables/use-email-status.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="data">
        
      </a>
      
       <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<a href="#emailstatus">
        <code>
          EmailStatus
        </code>
      </a>
      
       | <code>
        null
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      The full status record: <code>
        null
      </code>
      
       if no such email, <code>
        undefined
      </code>
      
       until the first read lands, while paused, and after a failed read.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="status-1">
        
      </a>
      
       <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      The status string (<code>
        queued
      </code>
      
       | <code>
        sent
      </code>
      
       | <code>
        delivered
      </code>
      
       | <code>
        bounced
      </code>
      
       | …), or <code>
        undefined
      </code>
      
      .
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isloading">
        
      </a>
      
       <code>
        isLoading
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      <code>
        true
      </code>
      
       until the first status for the current id lands; <code>
        false
      </code>
      
       while paused.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="error">
        
      </a>
      
       <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      < | <a href="https://nuxt-backend.dev/docs/reference/api/functions#backenderror">
        <code>
          BackendError
        </code>
      </a>
      
       | <code>
        null
      </code>
      
      >
    </td>
    
    <td>
      Why the status could not be read, or <code>
        null
      </code>
      
      . A failed delivery is <code>
        isFailed
      </code>
      
      , not this.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isdelivered">
        
      </a>
      
       <code>
        isDelivered
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      <code>
        true
      </code>
      
       once the email is delivered.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isfailed">
        
      </a>
      
       <code>
        isFailed
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      <code>
        true
      </code>
      
       if the email bounced, was marked as spam, or failed to send.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts" rel="nofollow">
        src/runtime/vue/composables/use-email-status.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

## Functions

### useEmailStatus()

```ts
function useEmailStatus(options): UseEmailStatusReturn;
```

Defined in: [src/runtime/vue/composables/use-email-status.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-email-status.ts)

Reactive delivery status for a sent email. Updates live as delivery webhooks
advance the status (queued → sent → delivered/bounced). Reads through the
auto-provided `api.email` namespace; pass `{ api }` to override. It never
throws: a failed read shows in `error`.

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="#useemailstatusoptions">
        <code>
          UseEmailStatusOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`UseEmailStatusReturn`](#useemailstatusreturn)

#### Example

```vue
<script setup lang="ts">
const emailId = ref<string>()
const delivery = useEmailStatus({ emailId })
</script>
<template>
  <p v-if="delivery.isFailed.value">Not delivered: {{ delivery.status.value }}</p>
  <p v-else-if="delivery.status.value">Status: {{ delivery.status.value }}</p>
</template>
```


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.