# Delivery API

Use this API to inspect transactional delivery health and recipient-level delivery events from your backend systems. These endpoints use your normal Bento API keys and require Transactional Platform access for the site.


> ⚠️ **Warning**
> Call these endpoints from server-side code. Do not expose your Bento secret key in a browser or mobile app.


## Available Endpoints


---

## The Delivery Query Model


  
    Delivery queries are scoped by `site_uuid` and authenticated with your Bento publishable key and secret key. Date filters are optional. Bento defaults to a recent window when dates are omitted.

    
> Use ISO 8601 timestamps when you need exact hour/minute boundaries. Date-only values like `2026-07-08` are treated as calendar days.

  
  
    ### Common Query Parameters

    
      - **site_uuid** (`string`): 
        Your Bento site UUID. Required on every request.
      
      - **start_date** (`datetime`): 
        Optional start of the delivery window. Alias: `from`.
      
      - **end_date** (`datetime`): 
        Optional end of the delivery window. Alias: `to`.
      
    
  


---

## Delivery Report {{ tag: 'GET', label: '/v1/delivery/report' }}


  
    Returns delivery report data for the site. If you do not pass dates, Bento returns the last 24 hours.

    ### Required Attributes

    
      - **site_uuid** (`string`): 
        Your Bento site UUID.
      
    

    ### Optional Attributes

    
      - **start_date** (`datetime`): 
        Start of the report window. Alias: `from`.
      
      - **end_date** (`datetime`): 
        End of the report window. Alias: `to`.
      
    

  
  
    
  


  
    ### Response

    Returns JSON delivery report data for the requested site and date range.

    
      - **data** (`object`): 
        Report payload for the selected window.
      
      - **meta** (`object`): 
        Metadata returned with the report when available.
      
      - **error** (`string`): 
        Error message when delivery data cannot be loaded.
      
    
  


---

## Recipient Events {{ tag: 'GET', label: '/v1/delivery/events' }}


  
    Returns delivery events for one recipient email address. If you do not pass dates, Bento searches up to the last 30 days.

    ### Required Attributes

    
      - **site_uuid** (`string`): 
        Your Bento site UUID.
      
      - **email** (`string`): 
        Recipient email address to investigate.
      
    

    ### Optional Attributes

    
      - **start_date** (`datetime`): 
        Start of the event window. Alias: `from`.
      
      - **end_date** (`datetime`): 
        End of the event window. Alias: `to`.
      
      - **limit** (`integer`): 
        Number of events to return. Defaults to `100` and cannot exceed `100`.
      
    

  
  
    
  


  
    ### Response

    Returns matching delivery events for the requested recipient.

    
      - **events** (`array`): 
        Delivery events for the requested recipient.
      
      - **meta** (`object`): 
        Metadata returned with the event search when available.
      
      - **error** (`string`): 
        Error message when delivery events cannot be loaded.
      
    

    ### Common Errors

    
      - **400** (`status`): 
        Missing email, invalid date, invalid limit, or a start date after the end date.
      
      - **401** (`status`): 
        Missing or invalid API credentials, or a `site_uuid` your API key cannot access.
      
      - **403** (`status`): 
        Transactional Platform access is required for this site.
      
      - **503** (`status`): 
        Delivery data is unavailable. Retry later.