# Email Operation Resource

An **Email Operation** represents a batch of emails created in a single send request. Use this resource to track the overall status and delivery statistics of your email sends.

When you send an email, the API returns an `operationId` that correlates all email resources created in that request. Use the Operation resource to monitor delivery progress and retrieve aggregate statistics.

Data retention is limited to 7 days after creation. Requests for older records may yield incomplete results.

## API Base URL

All URLs in the reference documentation use the following base URL:

```xml
https://comms.twilio.com/v1
```

## Operation Properties

<OperationTable type="properties" data={{"x-twilio-version":1,"title":"EmailOperation","type":"object","description":"An Email Operation represents the aggregate work to be completed for a POST request to the /Emails endpoint.\nThe work maybe be performed asynchronously and the Email Operation resource can be used to track the progress of the work.","required":["id","status","stats","createdAt","updatedAt"],"refName":"EmailOperation","modelName":"EmailOperation","properties":{"id":{"x-twilio-version":1,"description":"The Operation ID is an identifier that can be used to correlate all of the\nresources created in a request.\n\nIssue a GET request to the resource list location, using the Operation ID as a query parameter\nto retrieve the resources that correlate with the Operation.","title":"OperationId","type":"string","pattern":"^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}","example":"comms_operation_01h9krwprkeee8fzqspvwy6nq8","refName":"OperationId","modelName":""},"status":{"x-twilio-version":1,"title":"CommunicationOperationStatus","type":"string","description":"The status of an Operation.","enum":["SCHEDULED","PROCESSING","COMPLETED","CANCELED"],"refName":"CommunicationOperationStatus","modelName":"CommunicationOperationStatus"},"stats":{"x-twilio-version":1,"title":"EmailOperationStats","type":"object","example":{"total":1,"recipients":1,"attempts":1,"queued":0,"sent":0,"scheduled":0,"delivered":0,"opened":0,"undelivered":0,"failed":0,"canceled":0},"description":"Represents the stats of a sending operation of one or many `Emails`.\n- `total` is the total number of `Email` resources created in the `Operation`.\n\n  * To get the status for each individual `Email`, fetch the `Email` resource:\n    `GET /Email/{emailId}`.\n\n  * For `Emails` with multiple recipients, use `Receipts` e.g. `GET /Emails/{emailId}/Receipts`.\n\n- `recipients` is the total number of recipients targeted in an Operation.\n- `attempts` is the total number of sending attempts made by Twilio.\n- `scheduled` is the number of `Emails` that are scheduled to be sent by\n  Twilio in the future.\n\n- `queued` is the number of `Emails` that are queued in Twilio for sending.\n- `sent` is the number of `Emails` that have been sent by Twilio.\n- `delivered` is the number of `Emails` that have been successfully\n    delivered to recipients.\n\n- `opened` is the number of `Emails` that have been opened by unique recipients.\n- `undelivered` is the number of `Emails` that were successfully sent by Twilio\n  but have not been delivered to the recipient.\n\n- `failed` is the number of `Emails` that failed during processing by Twilio.\n  Get `Errors` with `GET /Emails/Operations/{operationId}/Errors` fore more detail.\n\n- `canceled` is the number of `Emails` that were canceled via API request.","required":["total","recipients","attempts","queued","sent","scheduled","delivered","opened","failed","undelivered","canceled"],"refName":"EmailOperationStats","modelName":"EmailOperationStats","properties":{"total":{"type":"integer","minimum":0},"recipients":{"type":"integer","minimum":0},"attempts":{"type":"integer","minimum":0},"queued":{"type":"integer","minimum":0},"sent":{"type":"integer","minimum":0},"scheduled":{"type":"integer","minimum":0},"delivered":{"type":"integer","minimum":0},"opened":{"type":"integer","minimum":0},"undelivered":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"canceled":{"type":"integer","minimum":0}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}} />

## Fetch an Email Operation

`GET https://comms.twilio.com/v1/Emails/Operations/{operationId}`

Retrieves a single Email Operation by its ID. Records are available for 7 days after creation.

### Path parameters

```json
[{"schema":{"x-twilio-version":1,"description":"The Operation ID is an identifier that can be used to correlate all of the\nresources created in a request.\n\nIssue a GET request to the resource list location, using the Operation ID as a query parameter\nto retrieve the resources that correlate with the Operation.","title":"OperationId","type":"string","pattern":"^comms_operation_[0-7][a-hjkmnpqrstv-z0-9]{25,34}","example":"comms_operation_01h9krwprkeee8fzqspvwy6nq8","refName":"OperationId","modelName":""},"x-twilio-version":1,"name":"operationId","in":"path","required":true}]
```

Fetch an Email Operation

```ts
import { TwilioClient } from "twilio-comms";

async function main() {
    const client = new TwilioClient({
        accountId: "TWILIO_ACCOUNT_SID",
        authToken: "TWILIO_AUTH_TOKEN",
    });
    await client.emails.fetchOperation("comms_operation_01h9krwprkeee8fzqspvwy6nq8");
}
main();
```

```py
from twilio_comms import TwilioComms

client = TwilioComms(
    account_id="TWILIO_ACCOUNT_SID",
    auth_token="TWILIO_AUTH_TOKEN",
)

client.emails.fetch_operation(
    operation_id="comms_operation_01h9krwprkeee8fzqspvwy6nq8",
)
```

```cs
using Twilio.Comms;
using System.Threading.Tasks;

public partial class Examples
{
    public async Task Example() {
        var client = new TwilioComms(
            accountId: "TWILIO_ACCOUNT_SID",
            authToken: "TWILIO_AUTH_TOKEN"
        );

        await client.Emails.FetchOperationAsync(
            "comms_operation_01h9krwprkeee8fzqspvwy6nq8"
        );
    }

}
```

```java
package com.example.usage;

import com.twilio.sdk.TwilioComms;

public class Example {
    public static void main(String[] args) {
        TwilioComms client = TwilioComms
            .builder()
            .credentials("TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN")
            .build();

        client.emails().fetchOperation("comms_operation_01h9krwprkeee8fzqspvwy6nq8");
    }
}
```

```go
package example

import (
    context "context"

    client "github.com/twilio/twilio-comms-go/twilio/client"
    option "github.com/twilio/twilio-comms-go/twilio/option"
)

func do() {
    client := client.NewWithOptions(
        option.WithBasicAuth(
            "TWILIO_ACCOUNT_SID",
            "TWILIO_AUTH_TOKEN",
        ),
    )
    client.Emails.FetchOperation(
        context.TODO(),
        "comms_operation_01h9krwprkeee8fzqspvwy6nq8",
    )
}
```

```php
<?php

namespace Example;

use Twilio\Comms\TwilioComms;

$client = new TwilioComms(
    accountId: 'TWILIO_ACCOUNT_SID',
    authToken: 'TWILIO_AUTH_TOKEN',
);
$client->emails->fetchOperation(
    'comms_operation_01h9krwprkeee8fzqspvwy6nq8',
);
```

```rb
require "twiliocomms"

client = TwilioComms::Client.new(
  account_id: "TWILIO_ACCOUNT_SID",
  auth_token: "TWILIO_AUTH_TOKEN"
)

client.emails.fetch_operation(operation_id: "comms_operation_01h9krwprkeee8fzqspvwy6nq8")
```

```bash
curl -X GET "https://comms.twilio.com/v1/Emails/Operations/comms_operation_01h9krwprkeee8fzqspvwy6nq8" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

## List Email Operations

`GET https://comms.twilio.com/v1/Emails/Operations`

Returns a paginated list of Email Operations. Data retention is limited to 7 days after creation.

### Query parameters

```json
[{"in":"query","name":"startDate","description":"Filter to Operations created after the specified date and time.","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"endDate","description":"Filter to Operations created before the specified date and time.","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"status","description":"Filter to Operations with the specified status.","schema":{"x-twilio-version":1,"title":"CommunicationOperationStatus","type":"string","description":"The status of an Operation.","enum":["SCHEDULED","PROCESSING","COMPLETED","CANCELED"],"refName":"CommunicationOperationStatus","modelName":"CommunicationOperationStatus"}},{"in":"query","name":"pageToken","description":"The token to retrieve the next page of results.","schema":{"x-twilio-version":1,"description":"The token that identifies the page of resources to fetch.","title":"PageToken","type":"string","refName":"PageToken","modelName":""}},{"in":"query","name":"pageSize","description":"The number of resources to return in a page.","schema":{"x-twilio-version":1,"description":"Total number of items returned in a single page, the minimum is 1 and maximum is 1000. Default is 50.","title":"PageSize","type":"integer","minimum":1,"maximum":1000,"default":50,"example":50,"refName":"PageSize","modelName":""}}]
```

List Email Operations

```ts
import { TwilioClient } from "twilio-comms";

async function main() {
    const client = new TwilioClient({
        accountId: "TWILIO_ACCOUNT_SID",
        authToken: "TWILIO_AUTH_TOKEN",
    });
    await client.emails.listOperations({
        startDate: new Date("2024-01-15T09:30:00Z"),
        endDate: new Date("2024-01-15T09:30:00Z"),
        status: "SCHEDULED",
        pageToken: "pageToken",
        pageSize: 50,
    });
}
main();
```

```py
from twilio_comms import TwilioComms
import datetime

client = TwilioComms(
    account_id="TWILIO_ACCOUNT_SID",
    auth_token="TWILIO_AUTH_TOKEN",
)

client.emails.list_operations(
    start_date=datetime.datetime.fromisoformat("2024-01-15T09:30:00+00:00"),
    end_date=datetime.datetime.fromisoformat("2024-01-15T09:30:00+00:00"),
    status="SCHEDULED",
    page_token="pageToken",
    page_size=50,
)
```

```cs
using Twilio.Comms;
using System.Threading.Tasks;
using System;
using System.Globalization;

public partial class Examples
{
    public async Task Example() {
        var client = new TwilioComms(
            accountId: "TWILIO_ACCOUNT_SID",
            authToken: "TWILIO_AUTH_TOKEN"
        );

        await client.Emails.ListOperationsAsync(
            new EmailsListOperationsRequest {
                StartDate = DateTime.Parse("2024-01-15T09:30:00Z", null, DateTimeStyles.AdjustToUniversal),
                EndDate = DateTime.Parse("2024-01-15T09:30:00Z", null, DateTimeStyles.AdjustToUniversal),
                Status = CommunicationOperationStatus.Scheduled,
                PageToken = "pageToken",
                PageSize = 50
            }
        );
    }

}
```

```java
package com.example.usage;

import com.twilio.sdk.TwilioComms;
import com.twilio.sdk.resources.emails.requests.EmailsListOperationsRequest;
import com.twilio.sdk.types.CommunicationOperationStatus;
import java.time.OffsetDateTime;

public class Example {
    public static void main(String[] args) {
        TwilioComms client = TwilioComms
            .builder()
            .credentials("TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN")
            .build();

        client.emails().listOperations(
            EmailsListOperationsRequest
                .builder()
                .startDate(OffsetDateTime.parse("2024-01-15T09:30:00Z"))
                .endDate(OffsetDateTime.parse("2024-01-15T09:30:00Z"))
                .status(CommunicationOperationStatus.SCHEDULED)
                .pageToken("pageToken")
                .pageSize(50)
                .build()
        );
    }
}
```

```go
package example

import (
    context "context"

    twiliocomms "github.com/twilio/twilio-comms-go/twilio"
    client "github.com/twilio/twilio-comms-go/twilio/client"
    option "github.com/twilio/twilio-comms-go/twilio/option"
)

func do() {
    client := client.NewWithOptions(
        option.WithBasicAuth(
            "TWILIO_ACCOUNT_SID",
            "TWILIO_AUTH_TOKEN",
        ),
    )
    request := &twiliocomms.EmailsListOperationsRequest{
        StartDate: twiliocomms.Time(
            twiliocomms.MustParseDateTime(
                "2024-01-15T09:30:00Z",
            ),
        ),
        EndDate: twiliocomms.Time(
            twiliocomms.MustParseDateTime(
                "2024-01-15T09:30:00Z",
            ),
        ),
        Status: twiliocomms.CommunicationOperationStatusScheduled.Ptr(),
        PageToken: twiliocomms.String(
            "pageToken",
        ),
        PageSize: twiliocomms.Int(
            50,
        ),
    }
    client.Emails.ListOperations(
        context.TODO(),
        request,
    )
}
```

```php
<?php

namespace Example;

use Twilio\Comms\TwilioComms;
use Twilio\Comms\Emails\Requests\EmailsListOperationsRequest;
use DateTime;
use Twilio\Comms\Types\CommunicationOperationStatus;

$client = new TwilioComms(
    accountId: 'TWILIO_ACCOUNT_SID',
    authToken: 'TWILIO_AUTH_TOKEN',
);
$client->emails->listOperations(
    new EmailsListOperationsRequest([
        'startDate' => new DateTime('2024-01-15T09:30:00Z'),
        'endDate' => new DateTime('2024-01-15T09:30:00Z'),
        'status' => CommunicationOperationStatus::Scheduled->value,
        'pageToken' => 'pageToken',
        'pageSize' => 50,
    ]),
);
```

```rb
require "twiliocomms"

client = TwilioComms::Client.new(
  account_id: "TWILIO_ACCOUNT_SID",
  auth_token: "TWILIO_AUTH_TOKEN"
)

client.emails.list_operations(
  start_date: "2024-01-15T09:30:00Z",
  end_date: "2024-01-15T09:30:00Z",
  status: "SCHEDULED",
  page_token: "pageToken",
  page_size: 50
)
```

```bash
curl -X GET "https://comms.twilio.com/v1/Emails/Operations?startDate=2024-01-15&endDate=2024-01-15&status=SCHEDULED&pageToken=pageToken&pageSize=50" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```