# List Transactional Mailings

**GET /transactional_mailings**

Retrieve a paginated collection of the notification emails Arta sent on your Organization's behalf, newest first unless `sort` says otherwise. Each record reports who the email was addressed to and how far it got.

The collection covers mailings created in the last 90 days, of the notification types `GET /metadata/email_notifications` publishes for your Organization.

This collection is narrowed with `filter`, over the fields it declares; `search` is not accepted here, and a clause `filter` cannot apply is refused rather than ignored.

Unrecognized query parameters, and any parameter sent more than once, are rejected with a `400`, as is a `sort` value the parameter does not declare.

To read past what paging reaches, narrow the collection with `created_at` rather than paging into it.

Requires API access to be enabled for your Organization, and answers `403` otherwise.


## Servers
- https://api.arta.io: https://api.arta.io ()



## Parameters
### Headers

- **Authorization** (string)
  Authorize your API calls with an Arta API token



### Query parameters

- **filter** (string)
  Narrow the returned collection with one or more clauses. Every clause is applied: a request returns exactly the records the filter describes, or is refused with a `400` naming what was at fault. A clause this parameter cannot express is never dropped silently. This syntax differs from the `search` parameter described under Search, so the rules below apply rather than those.

  Each clause names a field, an operator and a value. Clauses on different fields all have to hold. Repeating a text field matches any of its values, and repeating its negation excludes all of them:

  ```
  status:failed type:self_ship_label
  status:failed status:accepted
  ```

  **Operators**

  | Operator | Usage | Description | Example |
  |---|---|---|---|
  | `:` | `field:value` | Matches the value | `status:failed` returns records whose status is `failed` |
  | `-` | `-field:value` | Returns records holding a different value. Records holding no value are returned by neither the clause nor its negation; match them with `null`. Text fields only, except `-field:null`, which date fields take too | `-status:delivered` returns records with another status, and not those holding no status |
  | `null` | `field:null`, `-field:null` | Matches records holding no value for the field, or with `-`, those holding one. Text and date fields, written in upper or lower case, unless the endpoint's field table says otherwise | `status:null` returns records holding no status |
  | `>=`, `>`, `<=`, `<` | `field:>=value` | Compares a date field | `created_at:>=2026-09-01` returns records created on or after 1 September 2026 |
  | `..` | `field:from..to`, `field:from..`, `field:..to` | A range over a date field, both ends included. Either end may be left out, but not both | `created_at:2026-09-01..2026-09-07` returns records created in that week |

  Date fields are in UTC, and a bare date names the whole UTC day it falls in, so `created_at:2026-09-01` covers that day end to end, while `created_at:>2026-09-01` starts after it, at midnight on 2 September. Use `>=` and `<=` to include the day named.

  For a narrower bound give a timestamp in the form `"2026-09-01T09:30:00Z"`, quoted, since any value containing a `:` has to be. A timestamp takes `:`, `>`, `>=`, `<` and `<=`, while a range takes dates only. An offset in place of `Z` is resolved to the UTC instant it names:

  ```
  created_at:>="2026-09-01T09:30:00Z"
  ```

  A quoted timestamp names the second it is written to, or the fraction of a second it gives, as a bare date names its day, and every operator reads it the same way: `:` covers that span, `>` starts after it ends, `<=` runs to its end, and `>=` and `<` start at its beginning.

  A date field carries at most one lower bound and one upper bound across the whole filter, and a bare date sets both, so a bare date cannot be combined with another bound on the same field. Two comparisons that bound opposite sides are read as the span between them, as in `created_at:>=2026-09-01 created_at:<=2026-09-10`, while bounds that cross are refused.

  **No value**

  `null` names a record holding no value for a field. Repeating a text field with `null` matches its values or no value:

  ```
  status:null
  status:failed status:null
  -sent_at:null
  ```

  `null` takes no comparison or range. Beside `field:null`, a text field takes only further `field:value` clauses, which widen it as shown above. Any other clause on the same field is refused, since a record holding no value could never also hold it, so `status:null -status:failed` is refused. Quotes do not change it: `status:"null"` reads as `status:null`.

  **Refusals**

  A clause this endpoint cannot apply is refused with a `400` naming what was at fault — an unknown field, an operator the field does not support, a value it cannot read, `null` given as a bound, or a clause matching `null` beside another clause on its field. Wildcards and bare terms without a field are refused too. Clauses on different fields are combined with AND, and repeated values of one text field with OR, implicitly: the words `AND`, `OR` and `NOT`, and grouping with parentheses, are not part of the syntax. Those words and a clause opening with a parenthesis are refused, while a parenthesis inside a value is read as part of that value. A filter longer than 2,000 bytes is refused too.

  **Transactional Mailing filter fields**

  Each field is named after the response field it reads. Text values are matched without regard to case.

  | Field | Type | Notes |
  |---|---|---|
  | `id` | string | The mailing's own identifier. A value that is not a well-formed identifier is refused; a well-formed one naming no mailing of your Organization returns an empty page. `null` is refused, since every mailing carries one |
  | `status` | string | `accepted`, `delivered`, `failed`, `sending`, or `null` for a mailing whose send is still under way or did not complete. Another value returns an empty page rather than a refusal |
  | `type` | string | An `id` from `GET /metadata/email_notifications`. A value this endpoint does not serve returns an empty page rather than a refusal |
  | `request_id` | string | A Request identifier. One naming no Request of your Organization in the same mode as your API key is refused. `null` matches mailings sent about no Request |
  | `shipment_id` | string | A Shipment identifier. One naming no Shipment of your Organization in the same mode as your API key is refused. `null` matches mailings sent about no Shipment |
  | `created_at` | date | |
  | `sent_at` | date | `null` matches mailings not yet sent |

- **page** (integer)
  Page number of the results to fetch. A value outside 1 to 100 is rejected with a `400`.

- **page_size** (integer)
  Results per page. A value outside 1 to 50 is rejected with a `400`.

- **sort** (string)
  An optional sort order for the returned collection. Another value is rejected with a `400`.



## Responses
### 200
A collection of Transactional Mailings
#### Headers

- **content-type** (string)

- **x-arta-request-id** (string)
  A unique identifier for the Arta API call


#### Body: application/json (object)
- **items** (array[object])
  The delivery record of one notification email Arta sent on your Organization's behalf: who it was addressed to, how far it got, and which configuration produced it.

- **metadata** (object)


### 400
Bad Request
#### Headers

- **content-type** (string)

- **x-arta-request-id** (string)
  A unique identifier for the Arta API call


#### Body: application/json (object)
- **error** (string)
  What was at fault in the request.


### 403
Forbidden


[Powered by Bump.sh](https://bump.sh)