{
  "x-generator": "NSwag v14.7.1.0 (NJsonSchema v11.6.1.0 (Newtonsoft.Json v13.0.0.0))",
  "openapi": "3.0.0",
  "info": {
    "title": "Azimea API",
    "description": "Send contacts, events, catalogue items and transactional email from your own systems, and read contacts and orders. Every request carries an API key made in Settings › API keys: `Authorization: Bearer azm_live_…`. Each key holds only the permissions given to it. Every answer has the same envelope: `{ isSuccess, value, status, errors, fieldErrors }`; an error carries a `code`, listed in the docs' error codes catalog.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.azimea.com/v1",
      "description": "Production (EU)"
    }
  ],
  "paths": {
    "/contact-attributes": {
      "post": {
        "tags": [
          "Contact-Attributes"
        ],
        "summary": "Create a contact field",
        "description": "Defines a custom attribute before any contact carries it, so its type is fixed: a value is then stored as that type everywhere, and a rule like greater than 5000 means one thing in every segment. The key is lowercase letters, digits and underscores, starting with a letter, up to 40 characters (audience.attribute_key_invalid); a built-in field's name is refused (audience.attribute_reserved), an existing key gives 409 audience.attribute_exists, and a company has at most 100 fields (audience.attribute_limit_reached). The label defaults to the key made readable. Needs contacts:write.",
        "operationId": "createContactAttribute",
        "requestBody": {
          "x-name": "CreateContactAttributeRequestDto",
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateContactAttributeRequestDto"
              }
            }
          },
          "required": true,
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "The field as defined",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfContactAttributeDefinitionDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "key": "plan",
                    "label": "Plan",
                    "type": "Text",
                    "description": "The subscription plan the person is on.",
                    "createdFrom": "Api",
                    "createdAt": "2026-10-05T09:30:00+00:00",
                    "archivedAt": null
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:write permission"
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      },
      "get": {
        "tags": [
          "Contact-Attributes"
        ],
        "summary": "List contact fields",
        "description": "The company's own contact fields (custom attributes), archived ones included, ordered by key: the keys you can send in a contact's attributes and use in segment rules, each with its type (Text, Number, Boolean, Date, DateTime, TextList) and where it was created (Ui, Api, Csv). Needs contacts:read.",
        "operationId": "getContactAttributes",
        "responses": {
          "200": {
            "description": "Every contact field definition",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfIReadOnlyListOfContactAttributeDefinitionDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": [
                    {
                      "key": "plan",
                      "label": "Plan",
                      "type": "Text",
                      "description": "The subscription plan the person is on.",
                      "createdFrom": "Api",
                      "createdAt": "2026-10-05T09:30:00+00:00",
                      "archivedAt": null
                    }
                  ],
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:read permission"
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/contacts/{reference}": {
      "delete": {
        "tags": [
          "Contacts"
        ],
        "summary": "Erase a contact",
        "description": "Erases a person at their request (GDPR right to erasure), the same way the dashboard does: their name, address, attributes, tags and consent history are removed, a single anonymous row remains so a later import does not bring them back, and the other parts of Azimea erase theirs (timeline, flow runs, messages, orders, reports). It cannot be undone. `reference` is the contact's Azimea id, `ext:<your id>` or `email:<address>`; the last two find only contacts your system or an import created, a store's customers are found by their Azimea id. A contact already erased is not found again (404): nothing is left to erase. Needs the `contacts:erase` permission, which no other permission includes.",
        "operationId": "eraseContact",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The erased contact's id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfErasedContactDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "id": "01a10900-0000-7000-8000-000000000101"
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:erase permission"
          },
          "404": {
            "description": "audience.contact_not_found: no contact matches the reference, or it was already erased",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      },
      "get": {
        "tags": [
          "Contacts"
        ],
        "summary": "Get a contact",
        "description": "One contact, named by Azimea's id (any contact, store ones included), by ext:<your user id> or by email:<address>. The ext: and email: forms find only contacts your own systems created (API or import), not those a connected store brings: a store's customers are found by their Azimea id. A reference in none of the three forms is refused with audience.contact_reference_invalid. Needs contacts:read.",
        "operationId": "getContactByReference",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The contact, with its consent status, tags and custom attributes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfContactDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "id": "01a10a3c-5e2f-7b41-9c0d-4f7a2b6e1d90",
                    "storeId": null,
                    "email": "emma.clarke@example.com",
                    "firstName": "Emma",
                    "lastName": "Clarke",
                    "phone": "+447700900123",
                    "city": "Manchester",
                    "countryCode": "GB",
                    "consentStatus": "Subscribed",
                    "isPayingCustomer": false,
                    "orderCount": 0,
                    "totalSpent": 0,
                    "lastOrderAt": null,
                    "sourceCreatedAt": null,
                    "lastSyncedAt": null,
                    "fromOrders": false,
                    "consentSource": "api",
                    "consentUpdatedAt": "2026-10-05T09:30:00+00:00",
                    "storeConsentMode": null,
                    "marketingDeclared": false,
                    "tags": [
                      "trial"
                    ],
                    "attributes": {
                      "plan": "pro",
                      "seats": 12
                    },
                    "lastOpenAt": null,
                    "lastClickAt": null,
                    "lastEmailedAt": null,
                    "language": "en",
                    "addedAt": "2026-10-05T09:30:00+00:00",
                    "lastConversionAt": null
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:read permission"
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "audience.contact_not_found: no contact matches the reference",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/contacts": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "summary": "List contacts",
        "description": "A page of the company's contacts for its own systems, newest first: everyone (store, import and API contacts alike), or only the people of one segment (segment, an id from GET /segments), the same people a campaign or a flow aimed at that segment would reach. page from 1, pageSize 1 to 200 (default 50); totalCount tells how many pages there are. Needs contacts:read.",
        "operationId": "listContacts",
        "parameters": [
          {
            "name": "segment",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "guid",
              "nullable": true
            },
            "example": "01a10a3c-6b7d-7c52-8e1f-2a3b4c5d6e7f"
          },
          {
            "name": "page",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 100
          }
        ],
        "responses": {
          "200": {
            "description": "A page of contacts with the total count",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfContactPageDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "items": [
                      {
                        "id": "01a10a3c-5e2f-7b41-9c0d-4f7a2b6e1d90",
                        "storeId": null,
                        "email": "emma.clarke@example.com",
                        "firstName": "Emma",
                        "lastName": "Clarke",
                        "phone": "+447700900123",
                        "city": "Manchester",
                        "countryCode": "GB",
                        "consentStatus": "Subscribed",
                        "isPayingCustomer": false,
                        "orderCount": 0,
                        "totalSpent": 0,
                        "lastOrderAt": null,
                        "sourceCreatedAt": null,
                        "lastSyncedAt": null,
                        "fromOrders": false,
                        "consentSource": "api",
                        "consentUpdatedAt": "2026-10-05T09:30:00+00:00",
                        "storeConsentMode": null,
                        "marketingDeclared": false,
                        "tags": [
                          "trial"
                        ],
                        "attributes": {
                          "plan": "pro",
                          "seats": 12
                        },
                        "lastOpenAt": null,
                        "lastClickAt": null,
                        "lastEmailedAt": null,
                        "language": "en",
                        "addedAt": "2026-10-05T09:30:00+00:00",
                        "lastConversionAt": null
                      }
                    ],
                    "page": 1,
                    "pageSize": 100,
                    "totalCount": 1
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:read permission"
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      },
      "post": {
        "tags": [
          "Contacts"
        ],
        "summary": "Create or update a contact",
        "description": "Writes one person from your own system. The contact is found by id, then externalId (your user id), then email, and created when none matches (an email is then required: audience.contact_email_required); a user id and an email that point at two different contacts are refused, never merged (409 audience.contact_identity_conflict). Fields left out stay as they are; attributes is a patch (a key sent is set, null removes it), and an unknown attribute key is created when the contact settings allow it, refused with audience.attribute_unknown otherwise. consent only moves up: Customer makes an existing customer, Subscribed needs proof.text (audience.consent_proof_required) and also brings back someone who unsubscribed, Unsubscribed stops marketing only; a bounce or a complaint is never lifted. topics turns topics on or off by key (topics.not_found, topics.archived). A store's contact keeps the email, id and consent the store syncs (audience.contact_store_managed), except an unsubscribe, which is always honoured. A new contact counts toward the plan (audience.contact_limit_reached). Sending the same contact twice leaves it as the first call did, so retries are safe. Needs contacts:write.",
        "operationId": "upsertContact",
        "requestBody": {
          "x-name": "UpsertContactRequestDto",
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpsertContactRequestDto"
              }
            }
          },
          "required": true,
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "The contact as stored, and whether it was created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfUpsertContactResponseDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "contact": {
                      "id": "01a10a3c-5e2f-7b41-9c0d-4f7a2b6e1d90",
                      "storeId": null,
                      "email": "emma.clarke@example.com",
                      "firstName": "Emma",
                      "lastName": "Clarke",
                      "phone": "+447700900123",
                      "city": "Manchester",
                      "countryCode": "GB",
                      "consentStatus": "Subscribed",
                      "isPayingCustomer": false,
                      "orderCount": 0,
                      "totalSpent": 0,
                      "lastOrderAt": null,
                      "sourceCreatedAt": null,
                      "lastSyncedAt": null,
                      "fromOrders": false,
                      "consentSource": "api",
                      "consentUpdatedAt": "2026-10-05T09:30:00+00:00",
                      "storeConsentMode": null,
                      "marketingDeclared": false,
                      "tags": [
                        "trial"
                      ],
                      "attributes": {
                        "plan": "pro",
                        "seats": 12
                      },
                      "lastOpenAt": null,
                      "lastClickAt": null,
                      "lastEmailedAt": null,
                      "language": "en",
                      "addedAt": "2026-10-05T09:30:00+00:00",
                      "lastConversionAt": null
                    },
                    "created": true
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:write permission"
          },
          "404": {
            "description": "audience.contact_not_found: the id sent belongs to no contact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/segments": {
      "get": {
        "tags": [
          "Segments"
        ],
        "summary": "List segments",
        "description": "The company's saved segments with their live counts: count is everyone the segment's rule picks now, sendableCount those Azimea may email. Pass a segment's id to GET /contacts?segment= to read its people. Needs contacts:read.",
        "operationId": "listSegments",
        "responses": {
          "200": {
            "description": "Every segment, with its rule and counts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfIReadOnlyListOfSegmentListItemDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": [
                    {
                      "id": "01a10a3c-6b7d-7c52-8e1f-2a3b4c5d6e7f",
                      "name": "Pro plan",
                      "description": "Everyone on the pro plan.",
                      "definition": {
                        "join": "All",
                        "rules": [
                          {
                            "fieldKey": "plan",
                            "operator": "Equals",
                            "value": "pro"
                          }
                        ]
                      },
                      "builtInKey": null,
                      "count": 412,
                      "sendableCount": 377
                    }
                  ],
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:read permission"
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/topics": {
      "get": {
        "tags": [
          "Topics"
        ],
        "summary": "List topics",
        "description": "The company's active email topics, the keys a contact's topics can turn on or off in POST /contacts. Archived topics are left out: they can no longer be set. Needs contacts:read.",
        "operationId": "listTopics",
        "responses": {
          "200": {
            "description": "Every active topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfIReadOnlyListOfTopicDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": [
                    {
                      "id": "01a10a3c-7a8b-7d63-9f20-3b4c5d6e7f80",
                      "key": "product_news",
                      "name": "Product news",
                      "description": "New features and changes, about once a month.",
                      "isArchived": false
                    }
                  ],
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:read permission"
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/contact-attributes/{key}": {
      "patch": {
        "tags": [
          "Contact-Attributes"
        ],
        "summary": "Update a contact field",
        "description": "Renames or describes a custom attribute, or archives it (archived: true hides it from pickers and keeps every stored value; false brings it back). Its key and type never change: rules and stored values rely on them. Needs contacts:write.",
        "operationId": "updateContactAttribute",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "x-name": "UpdateContactAttributeRequestDto",
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateContactAttributeRequestDto"
              }
            }
          },
          "required": true,
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "The field as it is now",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfContactAttributeDefinitionDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "key": "plan",
                    "label": "Subscription plan",
                    "type": "Text",
                    "description": "The subscription plan the person is on.",
                    "createdFrom": "Api",
                    "createdAt": "2026-10-05T09:30:00+00:00",
                    "archivedAt": null
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:write permission"
          },
          "404": {
            "description": "audience.attribute_not_found: no field has this key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/contacts/batch": {
      "post": {
        "tags": [
          "Contacts"
        ],
        "summary": "Create or update contacts in bulk",
        "description": "Up to 1,000 contacts in one call, each written exactly as POST /contacts would and each refused on its own: one invalid contact does not stop the others. The answer lists every contact in the order sent, with its status (Created, Updated or Failed), its id or its errors (code, field, params), and the totals. More than 1,000 is refused with audience.batch_too_large. The whole batch counts as one call for the rate limit. Needs contacts:write.",
        "operationId": "upsertContactsBatch",
        "requestBody": {
          "x-name": "UpsertContactsBatchRequestDto",
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpsertContactsBatchRequestDto"
              }
            }
          },
          "required": true,
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "Totals and one result per contact, in the order sent",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfUpsertContactsBatchResponseDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "created": 1,
                    "updated": 0,
                    "failed": 1,
                    "results": [
                      {
                        "index": 0,
                        "status": "Created",
                        "id": "01a10a3c-5e2f-7b41-9c0d-4f7a2b6e1d90",
                        "errors": null
                      },
                      {
                        "index": 1,
                        "status": "Failed",
                        "id": null,
                        "errors": [
                          {
                            "code": "validation.email",
                            "field": "Email",
                            "params": null
                          }
                        ]
                      }
                    ]
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the contacts:write permission"
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/items/{externalId}": {
      "delete": {
        "tags": [
          "Items"
        ],
        "summary": "Delete a catalogue item",
        "description": "Removes one of the items your system sent, by your own id (`externalId`), so emails stop recommending it. To keep its history instead, send it again with `active: false`. Items synced from a connected store cannot be deleted here. Needs the `items:write` permission.",
        "operationId": "deleteItem",
        "parameters": [
          {
            "name": "externalId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": true,
                  "value": null,
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the items:write permission"
          },
          "404": {
            "description": "No item with this id (catalog.item_not_found)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      },
      "get": {
        "tags": [
          "Items"
        ],
        "summary": "Get a catalogue item",
        "description": "Reads one of the items your system sent, by your own id (`externalId`). Items synced from a connected store are not found here. Needs the `items:read` permission.",
        "operationId": "getItem",
        "parameters": [
          {
            "name": "externalId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfCatalogItemDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "id": "01a10900-0000-7000-8000-000000000001",
                    "source": "api",
                    "storeId": null,
                    "externalId": "plan-pro",
                    "kind": "plan",
                    "name": "Pro plan",
                    "description": "Unlimited projects and priority support.",
                    "url": "https://example.com/pricing#pro",
                    "imageUrl": "https://example.com/img/pro.png",
                    "price": 49,
                    "comparePrice": 59,
                    "currency": "EUR",
                    "inStock": true,
                    "stockQuantity": null,
                    "categories": [
                      "plans"
                    ],
                    "attributes": {
                      "billing": "monthly",
                      "seats": 5
                    },
                    "active": true,
                    "createdAt": "2026-10-05T09:00:00+00:00",
                    "updatedAt": null
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the items:read permission"
          },
          "404": {
            "description": "No item with this id (catalog.item_not_found)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/items": {
      "post": {
        "tags": [
          "Items"
        ],
        "summary": "Create or update a catalogue item",
        "description": "Adds a product, plan or service from your own system to the catalogue Azimea recommends in emails, or updates it. `id` is your own id for the item: sending the same id again updates the same item, and a field left out keeps its value. A new item defaults to a product, in stock and active; `kind` is `product`, `plan`, `service` or `other`. To stop recommending an item but keep its history, send `active: false` instead of deleting it. Items synced from a connected store are not written here. Needs the `items:write` permission. Refusals come back as `catalog.*` codes on the field, for example `catalog.item_name_missing`, `catalog.item_currency_invalid`, or `catalog.items_limit` once the catalogue holds 100,000 items.",
        "operationId": "upsertItem",
        "requestBody": {
          "x-name": "CatalogItemRequestDto",
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CatalogItemRequestDto"
              }
            }
          },
          "required": true,
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "The item as stored",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfCatalogItemDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "id": "01a10900-0000-7000-8000-000000000001",
                    "source": "api",
                    "storeId": null,
                    "externalId": "plan-pro",
                    "kind": "plan",
                    "name": "Pro plan",
                    "description": "Unlimited projects and priority support.",
                    "url": "https://example.com/pricing#pro",
                    "imageUrl": "https://example.com/img/pro.png",
                    "price": 49,
                    "comparePrice": 59,
                    "currency": "EUR",
                    "inStock": true,
                    "stockQuantity": null,
                    "categories": [
                      "plans"
                    ],
                    "attributes": {
                      "billing": "monthly",
                      "seats": 5
                    },
                    "active": true,
                    "createdAt": "2026-10-05T09:00:00+00:00",
                    "updatedAt": null
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the items:write permission"
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/items/batch": {
      "post": {
        "tags": [
          "Items"
        ],
        "summary": "Create or update many catalogue items",
        "description": "The same as `POST /items` for up to 1,000 items in one call, which counts as a single call for the rate limit. Each item is written or refused on its own: the answer counts the created, updated and failed items and gives one result per item, by its position in the request, with the reasons as `catalog.*` codes. More than 1,000 items refuses the whole call with `catalog.batch_too_large`. Needs the `items:write` permission.",
        "operationId": "upsertItemsBatch",
        "requestBody": {
          "x-name": "CatalogItemsBatchRequestDto",
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CatalogItemsBatchRequestDto"
              }
            }
          },
          "required": true,
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "What happened to each item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfCatalogItemsBatchResponseDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "created": 0,
                    "updated": 1,
                    "failed": 0,
                    "results": [
                      {
                        "index": 0,
                        "status": "updated",
                        "id": "01a10900-0000-7000-8000-000000000001",
                        "errors": null
                      }
                    ]
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the items:write permission"
          },
          "400": {
            "description": "Validation failed: see errors[].code (catalog.batch_too_large)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/commerce/orders": {
      "get": {
        "tags": [
          "Commerce"
        ],
        "summary": "List orders",
        "description": "The orders of your connected stores, newest first, in pages (`page` from 1, `pageSize` 1–200, default 50). Statuses are the same for every platform: `Pending`, `Paid`, `Completed`, `Cancelled`, `Refunded`, `Failed`, `Draft`. Filter by `storeId`, by `status`, by `view` (`All`, `Paid` = paid or completed, `Pending`, `Abandoned` = orders left at checkout, `Refunded`), by the last `days` (1–3660, by placement date), or with `search` over the order number, email and name (at most 100 characters). Needs the `orders:read` permission.",
        "operationId": "getOrders",
        "parameters": [
          {
            "name": "storeId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "guid",
              "nullable": true
            },
            "example": null
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string",
              "nullable": true
            },
            "example": null
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "nullable": true,
              "allOf": [
                {
                  "$ref": "#/components/schemas/OrderStatus"
                }
              ]
            },
            "example": null
          },
          {
            "name": "view",
            "in": "query",
            "required": true,
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/OrderView"
                }
              ]
            },
            "example": "Paid"
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32",
              "nullable": true
            },
            "example": 30
          },
          {
            "name": "page",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 1
          },
          {
            "name": "pageSize",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            },
            "example": 50
          }
        ],
        "responses": {
          "200": {
            "description": "One page of orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfOrderPageDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "items": [
                      {
                        "id": "01a10900-0000-7000-8000-000000000101",
                        "storeId": "01a10900-0000-7000-8000-000000000201",
                        "number": "1042",
                        "status": "Paid",
                        "currency": "EUR",
                        "total": 129.9,
                        "email": "emma@example.com",
                        "customerName": "Emma Clarke",
                        "placedAt": "2026-10-04T18:12:00+00:00",
                        "paidAt": "2026-10-04T18:13:00+00:00",
                        "lineCount": 2
                      }
                    ],
                    "page": 1,
                    "pageSize": 50,
                    "totalCount": 1
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the orders:read permission"
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/events": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Track events from your product",
        "description": "Tells Azimea what people did in your product (`user.signed_up`, `trial.ending`, `kyc.completed`). Each event is recorded on the person's timeline and starts every published flow whose trigger is that event name; the person is found, or created, from `contact` (the same object `POST /contacts` takes, with at least `id`, `externalId` or `email`). Send up to 100 events per call; a call counts once for the rate limit. `id` is your own id, unique in your account: sending it again is counted as a duplicate, so retries are safe. Names use lowercase letters, digits, `_` and `.`, start with a letter, at most 64 characters; the prefixes `order.`, `cart.`, `customer.`, `subscriber.`, `contact.`, `email.` and `azimea.` are reserved. `occurredAt` may be up to 30 days in the past and not in the future; `properties` is a JSON object of at most 16 KB and 3 levels. Each event is accepted or rejected on its own, with `activity.*` codes per field. Needs the `events:write` permission.",
        "operationId": "trackEvents",
        "requestBody": {
          "x-name": "TrackEventsRequestDto",
          "description": "",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrackEventsRequestDto"
              }
            }
          },
          "required": true,
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "How many events were accepted, were duplicates, or were rejected (with the reasons per event)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfTrackEventsResponseDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "accepted": 1,
                    "duplicates": 0,
                    "rejected": []
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: no events, or more than 100 (activity.batch_too_large)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks the events:write permission"
          },
          "429": {
            "description": "Too many requests for this key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/sending/emails/{id}": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Retrieve a transactional email",
        "description": "Returns the submission and each recipient's current status and reason. Use the id returned by POST /sending/emails. The account's API key needs emails:read. BCC addresses are visible only to the sending account, never in email headers.",
        "operationId": "getTransactionalEmail",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "guid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The submission and its recipient deliveries",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfTransactionalEmailResultDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "id": "01a10900-0000-7000-8000-000000000301",
                    "status": "Delivered",
                    "reason": null,
                    "recipients": [
                      {
                        "id": "01a10900-0000-7000-8000-000000000301",
                        "email": "emma@example.com",
                        "name": "Emma",
                        "kind": "To",
                        "status": "Delivered",
                        "reason": null
                      }
                    ],
                    "sendAt": null,
                    "templateId": null,
                    "metadata": {},
                    "tags": {}
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "The email does not exist in this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this key. Wait the number of seconds in the `Retry-After` header, then send again."
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/sending/emails": {
      "post": {
        "tags": [
          "Sending"
        ],
        "summary": "Send a transactional email",
        "description": "Queues a transactional email with To, CC and BCC recipient lists (at most 50 addresses combined). A single address string remains accepted. To and CC are visible; BCC is never written in recipient headers. Each recipient has its own delivery id, status, suppression decision, retry and quota usage. Choose from on a verified company domain, or omit it to use the default sender; without a verified default, the request is refused. Supports replyTo, HTML and/or text, base64 attachments (including inline contentId), templateId with variables, metadata, tags, safe custom headers, sendAt (up to 30 days ahead), and tracking restrictions. Templates are resolved and rendered at acceptance; subject may be omitted when the template supplies it. At most 10 attachments with 5 MiB decoded combined, and 8 MiB total request size. Bounced, complained and protected addresses are suppressed. This endpoint is not for newsletters. The response id identifies the submission; recipients[].id matches delivery webhooks' message_id. Mixed means recipients have different statuses. Idempotency-Key (up to 150 visible ASCII characters) deduplicates the whole request across the account; different content under an existing new key returns 409. Paused companies and canceled or expired trial subscriptions return 403 without adding recipients, including retries with an existing key. An exhausted daily or monthly quota returns 429 with resetAt and upgradeUrl in the error parameters; no new delivery is queued unless sendAt is after the reset. Keys created before recipient lists retain their original replay behavior. Without a key, retries create new deliveries. Subject is at most 300 characters and HTML 500,000 characters. Needs emails:send.",
        "operationId": "sendEmail",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": {
              "type": "string",
              "nullable": true
            },
            "example": null
          }
        ],
        "requestBody": {
          "x-name": "SendTransactionalEmailRequestDto",
          "description": "Choose a complete HTML/text or saved-template example below. Together they cover all 16 payload fields and the nested attachment and tracking options. `html` and `templateId` cannot be sent together.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendTransactionalEmailRequestDto"
              },
              "examples": {
                "Complete HTML and text": {
                  "summary": "All options for direct content",
                  "description": "This example supplies `html` and `text`; `templateId` is intentionally absent. Replace the example addresses and use a verified domain for `from.email`. Replace `sendAt` with a timestamp up to 30 days ahead, or omit it to send immediately; a past timestamp sends immediately. The attachment data is a small text file and a one-pixel PNG; replace it with your files. Multiple recipients require SMTP. Send `Idempotency-Key` as an HTTP header, not a payload field. See [field limits and defaults](/build/email-payload/).",
                  "value": {
                    "from": {
                      "email": "orders@example.com",
                      "name": "Example Store"
                    },
                    "to": [
                      {
                        "email": "emma@example.net",
                        "name": "Emma"
                      }
                    ],
                    "cc": [
                      {
                        "email": "finance@example.com",
                        "name": "Finance"
                      }
                    ],
                    "bcc": [
                      {
                        "email": "archive@example.com",
                        "name": "Archive"
                      }
                    ],
                    "replyTo": [
                      {
                        "email": "support@example.com",
                        "name": "Support"
                      }
                    ],
                    "subject": "Your order {{orderId}} is confirmed",
                    "html": "<p>Hello {{name}},</p><p>Order {{orderId}} is confirmed.</p><img src=\"cid:store-logo\" alt=\"Store logo\">",
                    "text": "Hello {{name}}, your order {{orderId}} is confirmed.",
                    "variables": {
                      "name": "Emma",
                      "orderId": "1042"
                    },
                    "attachments": [
                      {
                        "fileName": "order-1042.txt",
                        "content": "T3JkZXIgMTA0Mg==",
                        "contentType": "text/plain"
                      },
                      {
                        "fileName": "logo.png",
                        "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=",
                        "contentType": "image/png",
                        "contentId": "store-logo"
                      }
                    ],
                    "metadata": {
                      "orderId": "1042",
                      "customerId": "cus_89"
                    },
                    "tags": {
                      "category": "order-confirmation",
                      "store": "main"
                    },
                    "headers": {
                      "X-Order-ID": "1042"
                    },
                    "sendAt": "2026-10-11T09:00:00Z",
                    "tracking": {
                      "opens": false,
                      "clicks": false
                    }
                  }
                },
                "Complete template": {
                  "summary": "All options with a saved template",
                  "description": "Replace `templateId` with a template from your account. Its HTML replaces the `html` field. The supplied `subject` overrides the template subject; omit it to inherit the saved subject. Use `{{name}}`, `{{orderId}}` and `cid:store-logo` in the template as needed. Replace the example addresses and use a verified domain for `from.email`. Replace `sendAt` with a timestamp up to 30 days ahead, or omit it to send immediately; a past timestamp sends immediately. The attachment data is a small text file and a one-pixel PNG; replace it with your files. Multiple recipients require SMTP. Send `Idempotency-Key` as an HTTP header, not a payload field. See [field limits and defaults](/build/email-payload/).",
                  "value": {
                    "from": {
                      "email": "orders@example.com",
                      "name": "Example Store"
                    },
                    "to": [
                      {
                        "email": "emma@example.net",
                        "name": "Emma"
                      }
                    ],
                    "cc": [
                      {
                        "email": "finance@example.com",
                        "name": "Finance"
                      }
                    ],
                    "bcc": [
                      {
                        "email": "archive@example.com",
                        "name": "Archive"
                      }
                    ],
                    "replyTo": [
                      {
                        "email": "support@example.com",
                        "name": "Support"
                      }
                    ],
                    "subject": "Your order {{orderId}} is confirmed",
                    "text": "Hello {{name}}, your order {{orderId}} is confirmed.",
                    "variables": {
                      "name": "Emma",
                      "orderId": "1042"
                    },
                    "attachments": [
                      {
                        "fileName": "order-1042.txt",
                        "content": "T3JkZXIgMTA0Mg==",
                        "contentType": "text/plain"
                      },
                      {
                        "fileName": "logo.png",
                        "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=",
                        "contentType": "image/png",
                        "contentId": "store-logo"
                      }
                    ],
                    "metadata": {
                      "orderId": "1042",
                      "customerId": "cus_89"
                    },
                    "tags": {
                      "category": "order-confirmation",
                      "store": "main"
                    },
                    "headers": {
                      "X-Order-ID": "1042"
                    },
                    "sendAt": "2026-10-11T09:00:00Z",
                    "tracking": {
                      "opens": false,
                      "clicks": false
                    },
                    "templateId": "01a10900-0000-7000-8000-000000000401"
                  }
                }
              }
            }
          },
          "required": true,
          "x-position": 1
        },
        "responses": {
          "200": {
            "description": "The message id and its status: Queued, or Suppressed with the reason",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfTransactionalEmailResultDto"
                },
                "example": {
                  "isSuccess": true,
                  "value": {
                    "id": "01a10900-0000-7000-8000-000000000301",
                    "status": "Queued",
                    "reason": null,
                    "recipients": [
                      {
                        "id": "01a10900-0000-7000-8000-000000000301",
                        "email": "emma@example.com",
                        "name": null,
                        "kind": "To",
                        "status": "Queued",
                        "reason": null
                      }
                    ],
                    "sendAt": null,
                    "templateId": null,
                    "metadata": {},
                    "tags": {}
                  },
                  "status": 0,
                  "errors": [],
                  "fieldErrors": null
                }
              }
            }
          },
          "400": {
            "description": "Validation failed: see errors[].code and fieldErrors",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                },
                "example": {
                  "isSuccess": false,
                  "value": null,
                  "status": 5,
                  "errors": [
                    {
                      "code": "validation.required",
                      "message": "Fill in this field.",
                      "params": null
                    }
                  ],
                  "fieldErrors": {
                    "email": [
                      {
                        "code": "validation.required",
                        "message": "Fill in this field.",
                        "params": null
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "403": {
            "description": "The key lacks emails:send, or sending for this company or subscription is stopped"
          },
          "404": {
            "description": "The template does not exist in this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "413": {
            "description": "The request body exceeds 8 MiB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "409": {
            "description": "The idempotency key was already used with a different payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiEnvelopeOfObject"
                }
              }
            }
          },
          "429": {
            "description": "Per-key rate limit or sending quota reached; quota responses include resetAt and upgradeUrl"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ApiEnvelopeOfContactAttributeDefinitionDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContactAttributeDefinitionDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "ContactAttributeDefinitionDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "description": "The field's key: lowercase letters, digits and `_`, starting with a letter, at most 40 characters. It never changes."
          },
          "label": {
            "type": "string",
            "description": "The name shown in the dashboard."
          },
          "type": {
            "description": "How values are stored and compared in segments. Fixed once the field exists.",
            "$ref": "#/components/schemas/ContactAttributeType"
          },
          "description": {
            "type": "string",
            "description": "A note for your team about what the field holds; `null` when none was written.",
            "nullable": true
          },
          "createdFrom": {
            "description": "Where the field was made: the dashboard (`Ui`), the API (`Api`) or a file import (`Csv`).",
            "$ref": "#/components/schemas/ContactAttributeSource"
          },
          "createdAt": {
            "type": "string",
            "description": "When the field was created.",
            "format": "date-time"
          },
          "archivedAt": {
            "type": "string",
            "description": "When the field was archived; `null` while it is active. An archived field is hidden from pickers and keeps every stored value.",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "ContactAttributeType": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Text",
          "Number",
          "Boolean",
          "Date",
          "DateTime",
          "TextList"
        ],
        "enum": [
          "Text",
          "Number",
          "Boolean",
          "Date",
          "DateTime",
          "TextList"
        ]
      },
      "ContactAttributeSource": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Ui",
          "Api",
          "Csv"
        ],
        "enum": [
          "Ui",
          "Api",
          "Csv"
        ]
      },
      "ApiError": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "description": "A stable code such as `audience.contact_not_found`. Branch on this, never on `message`. Every code is listed in the error codes catalog."
          },
          "message": {
            "type": "string",
            "description": "An English sentence for your logs. Do not show it to end users: it can change."
          },
          "params": {
            "type": "object",
            "description": "The numbers the message mentions (a minimum, a maximum), when there are any.",
            "nullable": true,
            "additionalProperties": {}
          }
        }
      },
      "CreateContactAttributeRequestDto": {
        "type": "object",
        "example": {
          "key": "plan",
          "label": "Plan",
          "type": "Text",
          "description": "The subscription plan the person is on."
        },
        "additionalProperties": false,
        "properties": {
          "key": {
            "type": "string",
            "description": "Required. Lowercase letters, digits and `_`, starting with a letter, at most 40 characters. A built-in field's name is refused, and so is a key that already exists.",
            "example": "plan"
          },
          "label": {
            "type": "string",
            "description": "The name shown in the dashboard. Made from the key when left out.",
            "maxLength": 80,
            "minLength": 0,
            "nullable": true,
            "example": "Plan"
          },
          "type": {
            "description": "Required. How values are stored and compared. It cannot be changed afterwards.",
            "example": "Text",
            "$ref": "#/components/schemas/ContactAttributeType"
          },
          "description": {
            "type": "string",
            "description": "A note for your team about what the field holds.",
            "maxLength": 300,
            "minLength": 0,
            "nullable": true,
            "example": "The subscription plan the person is on."
          }
        }
      },
      "ApiEnvelopeOfErasedContactDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/ErasedContactDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "ErasedContactDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "The id of the contact that was erased.",
            "format": "guid"
          }
        }
      },
      "ApiEnvelopeOfIReadOnlyListOfContactAttributeDefinitionDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "type": "array",
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/ContactAttributeDefinitionDto"
            }
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "ApiEnvelopeOfContactDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContactDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "ContactDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Azimea's id for this contact.",
            "format": "guid"
          },
          "storeId": {
            "type": "string",
            "description": "The connected store the contact comes from; `null` for contacts your own systems made (the API or an import).",
            "format": "guid",
            "nullable": true
          },
          "email": {
            "type": "string",
            "description": "The contact's email address."
          },
          "firstName": {
            "type": "string",
            "description": "First name.",
            "nullable": true
          },
          "lastName": {
            "type": "string",
            "description": "Last name.",
            "nullable": true
          },
          "phone": {
            "type": "string",
            "description": "Phone number, as it was given.",
            "nullable": true
          },
          "city": {
            "type": "string",
            "description": "City.",
            "nullable": true
          },
          "countryCode": {
            "type": "string",
            "description": "Two-letter country code (ISO 3166-1), such as `GB`.",
            "nullable": true
          },
          "consentStatus": {
            "description": "What Azimea may send this person. See the consent statuses catalog for what each value allows.",
            "$ref": "#/components/schemas/EmailConsentStatus"
          },
          "isPayingCustomer": {
            "type": "boolean",
            "description": "`true` once the person has a paid order."
          },
          "orderCount": {
            "type": "integer",
            "description": "How many orders Azimea has recorded for them.",
            "format": "int32"
          },
          "totalSpent": {
            "type": "number",
            "description": "How much they have spent in total, from their orders.",
            "format": "decimal"
          },
          "lastOrderAt": {
            "type": "string",
            "description": "When they last ordered; `null` if they never did.",
            "format": "date-time",
            "nullable": true
          },
          "sourceCreatedAt": {
            "type": "string",
            "description": "When the person was created in their store; `null` for contacts that do not come from a store.",
            "format": "date-time",
            "nullable": true
          },
          "lastSyncedAt": {
            "type": "string",
            "description": "When Azimea last updated this contact from the store; `null` for contacts that do not come from a store.",
            "format": "date-time",
            "nullable": true
          },
          "fromOrders": {
            "type": "boolean",
            "description": "`true` when they bought without a store account: known from orders only, missing from the store's customer list."
          },
          "consentSource": {
            "type": "string",
            "description": "Where the consent basis comes from, such as `store_import`, `store_purchase`, `signup_form` or `api`.",
            "nullable": true
          },
          "consentUpdatedAt": {
            "type": "string",
            "description": "When the consent status last changed.",
            "format": "date-time",
            "nullable": true
          },
          "storeConsentMode": {
            "description": "How the connected store collects consent: `Explicit`, `Notice`, `OwnConsent` or `None`. `null` until it is chosen.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/ConsentMode"
              }
            ]
          },
          "marketingDeclared": {
            "type": "boolean",
            "description": "`true` once the store has declared how it collects consent. Until then no marketing goes to anyone in it."
          },
          "tags": {
            "type": "array",
            "description": "Free-form labels, added by a flow's Tag step. Flows and segments can filter on them.",
            "nullable": true,
            "items": {
              "type": "string"
            }
          },
          "attributes": {
            "type": "object",
            "description": "Your own fields, by key. Each value is stored as its field's type.",
            "nullable": true,
            "additionalProperties": {}
          },
          "lastOpenAt": {
            "type": "string",
            "description": "When the person last opened an email. A mail privacy feature or a link scanner opening it does not count.",
            "format": "date-time",
            "nullable": true
          },
          "lastClickAt": {
            "type": "string",
            "description": "When the person last clicked a link. A scanner clicking does not count.",
            "format": "date-time",
            "nullable": true
          },
          "lastEmailedAt": {
            "type": "string",
            "description": "When the last campaign, flow or cart email went out to them.",
            "format": "date-time",
            "nullable": true
          },
          "language": {
            "type": "string",
            "description": "The language they read, as a lowercase two-letter code (`en`, `ro`). It picks the language version of a campaign they get; `null` when not known.",
            "nullable": true
          },
          "addedAt": {
            "type": "string",
            "description": "When the contact came into Azimea. What \"new contacts\" counts from.",
            "format": "date-time",
            "nullable": true
          },
          "lastConversionAt": {
            "type": "string",
            "description": "When they last did something your company counts as a conversion.",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "EmailConsentStatus": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Unknown",
          "SoftOptIn",
          "Subscribed",
          "Unsubscribed",
          "Bounced",
          "Complained",
          "CheckoutStarted",
          "PendingConfirmation"
        ],
        "enum": [
          "Unknown",
          "SoftOptIn",
          "Subscribed",
          "Unsubscribed",
          "Bounced",
          "Complained",
          "CheckoutStarted",
          "PendingConfirmation"
        ]
      },
      "ConsentMode": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Explicit",
          "Notice",
          "OwnConsent",
          "None"
        ],
        "enum": [
          "Explicit",
          "Notice",
          "OwnConsent",
          "None"
        ]
      },
      "ApiEnvelopeOfContactPageDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContactPageDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "ContactPageDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "description": "The contacts on this page, newest first.",
            "items": {
              "$ref": "#/components/schemas/ContactDto"
            }
          },
          "page": {
            "type": "integer",
            "description": "The page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "How many contacts a full page holds.",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "How many contacts match in all, across every page.",
            "format": "int32"
          }
        }
      },
      "ListContactsRequestDto": {
        "type": "object",
        "additionalProperties": false
      },
      "ApiEnvelopeOfIReadOnlyListOfSegmentListItemDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "type": "array",
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/SegmentListItemDto"
            }
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "SegmentListItemDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "The segment's id. Use it as `segment` in `GET /contacts`.",
            "format": "guid"
          },
          "name": {
            "type": "string",
            "description": "The segment's name."
          },
          "description": {
            "type": "string",
            "description": "A note about the segment; `null` when none was written.",
            "nullable": true
          },
          "definition": {
            "description": "The rules that decide who is in the segment.",
            "$ref": "#/components/schemas/RuleFilter"
          },
          "builtInKey": {
            "type": "string",
            "description": "A stable key for Azimea's own segments; `null` for segments your team made.",
            "nullable": true
          },
          "count": {
            "type": "integer",
            "description": "How many contacts are in the segment now.",
            "format": "int32"
          },
          "sendableCount": {
            "type": "integer",
            "description": "How many of them can receive marketing email, because they have a consent basis.",
            "format": "int32"
          }
        }
      },
      "RuleFilter": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "join": {
            "description": "`All`: a contact must match every rule. `Any`: matching one is enough.",
            "$ref": "#/components/schemas/RuleJoin"
          },
          "rules": {
            "type": "array",
            "description": "The rules.",
            "items": {
              "$ref": "#/components/schemas/FilterRule"
            }
          }
        }
      },
      "RuleJoin": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "All",
          "Any"
        ],
        "enum": [
          "All",
          "Any"
        ]
      },
      "FilterRule": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "fieldKey": {
            "type": "string",
            "description": "The field the rule looks at: a built-in field, or the key of one of your custom fields."
          },
          "operator": {
            "description": "How the field is compared with the value.",
            "$ref": "#/components/schemas/RuleOperator"
          },
          "value": {
            "description": "What it is compared with. Its type follows the field: text, a number, a date, or a number of days."
          }
        }
      },
      "RuleOperator": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Equals",
          "NotEquals",
          "Contains",
          "GreaterThan",
          "LessThan",
          "Before",
          "After",
          "NotContains",
          "WithinLastDays",
          "NotWithinLastDays"
        ],
        "enum": [
          "Equals",
          "NotEquals",
          "Contains",
          "GreaterThan",
          "LessThan",
          "Before",
          "After",
          "NotContains",
          "WithinLastDays",
          "NotWithinLastDays"
        ]
      },
      "ApiEnvelopeOfIReadOnlyListOfTopicDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "type": "array",
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/TopicDto"
            }
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "TopicDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "The topic's id.",
            "format": "guid"
          },
          "key": {
            "type": "string",
            "description": "The key you send in `topics` when writing a contact. It is also what segment rules use."
          },
          "name": {
            "type": "string",
            "description": "The name people see in the preference centre."
          },
          "description": {
            "type": "string",
            "description": "What the topic covers; `null` when none was written.",
            "nullable": true
          },
          "isArchived": {
            "type": "boolean",
            "description": "`true` for a topic that was retired. It can no longer be set on a contact."
          }
        }
      },
      "UpdateContactAttributeRequestDto": {
        "type": "object",
        "example": {
          "label": "Subscription plan",
          "description": null,
          "archived": false
        },
        "additionalProperties": false,
        "properties": {
          "label": {
            "type": "string",
            "description": "A new display name. Left out, the current one stays.",
            "maxLength": 80,
            "minLength": 0,
            "nullable": true,
            "example": "Subscription plan"
          },
          "description": {
            "type": "string",
            "description": "A new note for your team. Left out, the current one stays.",
            "maxLength": 300,
            "minLength": 0,
            "nullable": true,
            "example": null
          },
          "archived": {
            "type": "boolean",
            "description": "`true` hides the field from pickers and keeps every stored value; `false` brings it back. Left out, nothing changes.",
            "nullable": true,
            "example": false
          }
        }
      },
      "ApiEnvelopeOfUpsertContactResponseDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/UpsertContactResponseDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "UpsertContactResponseDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "contact": {
            "description": "The contact as it is now.",
            "$ref": "#/components/schemas/ContactDto"
          },
          "created": {
            "type": "boolean",
            "description": "`true` when the contact was created by this call, `false` when an existing one was updated."
          }
        }
      },
      "UpsertContactRequestDto": {
        "type": "object",
        "example": {
          "id": null,
          "externalId": "user_4821",
          "email": "emma.clarke@example.com",
          "firstName": "Emma",
          "lastName": "Clarke",
          "phone": "+447700900123",
          "city": "Manchester",
          "countryCode": "GB",
          "language": "en",
          "attributes": {
            "plan": "pro",
            "seats": 12
          },
          "consent": {
            "basis": "Subscribed",
            "proof": {
              "text": "Send me product news and offers from Notely.",
              "textVersion": "2",
              "locale": "en_GB",
              "ipAddress": "203.0.113.7",
              "givenAt": "2026-10-05T09:30:00+00:00"
            }
          },
          "topics": {
            "product_news": true
          }
        },
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Azimea's id, if you have it. A contact is looked up by `id` first, then by `externalId`, then by `email`.",
            "format": "guid",
            "nullable": true,
            "example": null
          },
          "externalId": {
            "type": "string",
            "description": "Your own id for this person (your user id). It is the best way to find them again, at most 64 characters.",
            "maxLength": 64,
            "minLength": 0,
            "nullable": true,
            "example": "user_4821"
          },
          "email": {
            "type": "string",
            "description": "The email address. Required when the contact does not exist yet.",
            "nullable": true,
            "example": "emma.clarke@example.com"
          },
          "firstName": {
            "type": "string",
            "description": "First name, at most 100 characters. Left out, the current value stays.",
            "maxLength": 100,
            "minLength": 0,
            "nullable": true,
            "example": "Emma"
          },
          "lastName": {
            "type": "string",
            "description": "Last name. Left out, the current value stays.",
            "maxLength": 100,
            "minLength": 0,
            "nullable": true,
            "example": "Clarke"
          },
          "phone": {
            "type": "string",
            "description": "Phone number. Left out, the current value stays.",
            "maxLength": 50,
            "minLength": 0,
            "nullable": true,
            "example": "+447700900123"
          },
          "city": {
            "type": "string",
            "description": "City. Left out, the current value stays.",
            "maxLength": 100,
            "minLength": 0,
            "nullable": true,
            "example": "Manchester"
          },
          "countryCode": {
            "type": "string",
            "description": "Two-letter country code (ISO 3166-1), such as `GB`.",
            "pattern": "^[A-Za-z]{2}$",
            "nullable": true,
            "example": "GB"
          },
          "language": {
            "type": "string",
            "description": "The language they read: a code such as `en`, or a locale such as `en_GB` (read as `en`).",
            "pattern": "^[A-Za-z]{2,3}([_-][A-Za-z0-9]{2,8})*$",
            "nullable": true,
            "example": "en"
          },
          "attributes": {
            "type": "object",
            "description": "Your custom fields, by key. A patch: a key you send is set, a key sent as `null` is removed, the others stay. Each key must be defined first.",
            "nullable": true,
            "example": {
              "plan": "pro",
              "seats": 12
            },
            "additionalProperties": {}
          },
          "consent": {
            "description": "What the person agreed to. Left out, their consent stays as it is.",
            "nullable": true,
            "example": {
              "basis": "Subscribed",
              "proof": {
                "text": "Send me product news and offers from Notely.",
                "textVersion": "2",
                "locale": "en_GB",
                "ipAddress": "203.0.113.7",
                "givenAt": "2026-10-05T09:30:00+00:00"
              }
            },
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContactConsentRequestDto"
              }
            ]
          },
          "topics": {
            "type": "object",
            "description": "The person's topic choices: topic key → `true` or `false`. Read the keys from `GET /topics`.",
            "nullable": true,
            "example": {
              "product_news": true
            },
            "additionalProperties": {
              "type": "boolean"
            }
          }
        }
      },
      "ContactConsentRequestDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "basis": {
            "description": "`Customer` (an existing customer), `Subscribed` (they agreed to receive your emails, which needs `proof`) or `Unsubscribed` (they no longer want marketing).",
            "example": "Subscribed",
            "$ref": "#/components/schemas/ContactConsentBasis"
          },
          "proof": {
            "description": "Required with `Subscribed`: the words they agreed to. It is kept in the person's consent history.",
            "nullable": true,
            "example": {
              "text": "Send me product news and offers from Notely.",
              "textVersion": "2",
              "locale": "en_GB",
              "ipAddress": "203.0.113.7",
              "givenAt": "2026-10-05T09:30:00+00:00"
            },
            "oneOf": [
              {
                "$ref": "#/components/schemas/ContactConsentProofRequestDto"
              }
            ]
          }
        }
      },
      "ContactConsentBasis": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Customer",
          "Subscribed",
          "Unsubscribed"
        ],
        "enum": [
          "Customer",
          "Subscribed",
          "Unsubscribed"
        ]
      },
      "ContactConsentProofRequestDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "text": {
            "type": "string",
            "description": "The exact words the person agreed to, such as the checkbox label.",
            "maxLength": 2000,
            "minLength": 0,
            "nullable": true,
            "example": "Send me product news and offers from Notely."
          },
          "textVersion": {
            "type": "string",
            "description": "Your own label for that wording, such as `2`, so you can tell which version they saw.",
            "maxLength": 64,
            "minLength": 0,
            "nullable": true,
            "example": "2"
          },
          "locale": {
            "type": "string",
            "description": "The language the text was shown in, such as `en_GB`.",
            "maxLength": 16,
            "minLength": 0,
            "nullable": true,
            "example": "en_GB"
          },
          "ipAddress": {
            "type": "string",
            "description": "The address they agreed from.",
            "nullable": true,
            "example": "203.0.113.7"
          },
          "givenAt": {
            "type": "string",
            "description": "When they agreed. Now, when left out.",
            "format": "date-time",
            "nullable": true,
            "example": "2026-10-05T09:30:00+00:00"
          }
        }
      },
      "ApiEnvelopeOfUpsertContactsBatchResponseDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/UpsertContactsBatchResponseDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "UpsertContactsBatchResponseDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "created": {
            "type": "integer",
            "description": "How many contacts were created.",
            "format": "int32"
          },
          "updated": {
            "type": "integer",
            "description": "How many existing contacts were updated.",
            "format": "int32"
          },
          "failed": {
            "type": "integer",
            "description": "How many contacts were refused. The others were still written.",
            "format": "int32"
          },
          "results": {
            "type": "array",
            "description": "One entry per contact, in the order you sent them.",
            "items": {
              "$ref": "#/components/schemas/ContactBatchItemResultDto"
            }
          }
        }
      },
      "ContactBatchItemResultDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "index": {
            "type": "integer",
            "description": "The contact's position in your request, starting at 0.",
            "format": "int32"
          },
          "status": {
            "description": "`Created`, `Updated` or `Failed`.",
            "$ref": "#/components/schemas/ContactBatchItemStatus"
          },
          "id": {
            "type": "string",
            "description": "The contact's Azimea id; `null` when it failed.",
            "format": "guid",
            "nullable": true
          },
          "errors": {
            "type": "array",
            "description": "Why the contact was refused; `null` when it was written.",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/ContactBatchItemErrorDto"
            }
          }
        }
      },
      "ContactBatchItemStatus": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Created",
          "Updated",
          "Failed"
        ],
        "enum": [
          "Created",
          "Updated",
          "Failed"
        ]
      },
      "ContactBatchItemErrorDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "description": "A stable error code, listed in the error codes catalog."
          },
          "field": {
            "type": "string",
            "description": "The request field the problem is about; `null` when it is about the whole contact.",
            "nullable": true
          },
          "params": {
            "type": "object",
            "description": "The numbers the code refers to (a minimum, a maximum), when there are any.",
            "nullable": true,
            "additionalProperties": {}
          }
        }
      },
      "UpsertContactsBatchRequestDto": {
        "type": "object",
        "example": {
          "contacts": [
            {
              "id": null,
              "externalId": "user_4821",
              "email": "emma.clarke@example.com",
              "firstName": "Emma",
              "lastName": "Clarke",
              "phone": "+447700900123",
              "city": "Manchester",
              "countryCode": "GB",
              "language": "en",
              "attributes": {
                "plan": "pro",
                "seats": 12
              },
              "consent": {
                "basis": "Subscribed",
                "proof": {
                  "text": "Send me product news and offers from Notely.",
                  "textVersion": "2",
                  "locale": "en_GB",
                  "ipAddress": "203.0.113.7",
                  "givenAt": "2026-10-05T09:30:00+00:00"
                }
              },
              "topics": {
                "product_news": true
              }
            },
            {
              "id": null,
              "externalId": null,
              "email": "not-an-address",
              "firstName": null,
              "lastName": null,
              "phone": null,
              "city": null,
              "countryCode": null,
              "language": null,
              "attributes": null,
              "consent": null,
              "topics": null
            }
          ]
        },
        "additionalProperties": false,
        "required": [
          "contacts"
        ],
        "properties": {
          "contacts": {
            "type": "array",
            "description": "The contacts to write, up to 1,000. Each is written exactly as `POST /contacts` would write it.",
            "minLength": 1,
            "nullable": false,
            "example": [
              {
                "id": null,
                "externalId": "user_4821",
                "email": "emma.clarke@example.com",
                "firstName": "Emma",
                "lastName": "Clarke",
                "phone": "+447700900123",
                "city": "Manchester",
                "countryCode": "GB",
                "language": "en",
                "attributes": {
                  "plan": "pro",
                  "seats": 12
                },
                "consent": {
                  "basis": "Subscribed",
                  "proof": {
                    "text": "Send me product news and offers from Notely.",
                    "textVersion": "2",
                    "locale": "en_GB",
                    "ipAddress": "203.0.113.7",
                    "givenAt": "2026-10-05T09:30:00+00:00"
                  }
                },
                "topics": {
                  "product_news": true
                }
              },
              {
                "id": null,
                "externalId": null,
                "email": "not-an-address",
                "firstName": null,
                "lastName": null,
                "phone": null,
                "city": null,
                "countryCode": null,
                "language": null,
                "attributes": null,
                "consent": null,
                "topics": null
              }
            ],
            "items": {
              "$ref": "#/components/schemas/UpsertContactRequestDto"
            }
          }
        }
      },
      "ApiEnvelopeOfObject": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "ApiEnvelopeOfCatalogItemDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/CatalogItemDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "CatalogItemDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Azimea's id for the item.",
            "format": "guid"
          },
          "source": {
            "type": "string",
            "description": "Where the item comes from: `store` (synced from a connected shop, edited only there), `file` (an import) or `api`."
          },
          "storeId": {
            "type": "string",
            "description": "The connected store the item belongs to; `null` for items from a file or the API.",
            "format": "guid",
            "nullable": true
          },
          "externalId": {
            "type": "string",
            "description": "Your own id for the item, the one you sent as `id`."
          },
          "kind": {
            "type": "string",
            "description": "`product`, `plan`, `service` or `other`."
          },
          "name": {
            "type": "string",
            "description": "The item's name."
          },
          "description": {
            "type": "string",
            "description": "A description, up to 5,000 characters.",
            "nullable": true
          },
          "url": {
            "type": "string",
            "description": "Where the item can be bought or read about: a full address starting with `https://`.",
            "nullable": true
          },
          "imageUrl": {
            "type": "string",
            "description": "An image of the item: a full address starting with `https://`.",
            "nullable": true
          },
          "price": {
            "type": "number",
            "description": "The current price, in `currency`.",
            "format": "decimal",
            "nullable": true
          },
          "comparePrice": {
            "type": "number",
            "description": "The price before a discount. Higher than `price` when set.",
            "format": "decimal",
            "nullable": true
          },
          "currency": {
            "type": "string",
            "description": "The three-letter currency code, such as `EUR` or `GBP`.",
            "nullable": true
          },
          "inStock": {
            "type": "boolean",
            "description": "`true` when the item can be bought."
          },
          "stockQuantity": {
            "type": "integer",
            "description": "How many are left; `null` when you do not track it.",
            "format": "int32",
            "nullable": true
          },
          "categories": {
            "type": "array",
            "description": "The item's categories. They drive the \"one category\" and \"for each person\" recommendations in emails.",
            "items": {
              "type": "string"
            }
          },
          "attributes": {
            "type": "object",
            "description": "Extra fields you attached, by key.",
            "additionalProperties": {}
          },
          "active": {
            "type": "boolean",
            "description": "`false` stops recommending the item and keeps its history."
          },
          "createdAt": {
            "type": "string",
            "description": "When the item was added.",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "description": "When it last changed; `null` if it never did.",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "CatalogItemRequestDto": {
        "type": "object",
        "example": {
          "id": "plan-pro",
          "kind": "plan",
          "name": "Pro plan",
          "description": "Unlimited projects and priority support.",
          "url": "https://example.com/pricing#pro",
          "imageUrl": "https://example.com/img/pro.png",
          "price": 49,
          "comparePrice": 59,
          "currency": "EUR",
          "inStock": true,
          "stockQuantity": null,
          "categories": [
            "plans"
          ],
          "attributes": {
            "billing": "monthly",
            "seats": 5
          },
          "active": true
        },
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Required. Your own id for the item, at most 100 characters. Sending the same id again updates the item.",
            "nullable": true,
            "example": "plan-pro"
          },
          "kind": {
            "type": "string",
            "description": "`product`, `plan`, `service` or `other`. A new item is a `product` unless you say otherwise.",
            "nullable": true,
            "example": "plan"
          },
          "name": {
            "type": "string",
            "description": "Required, at most 300 characters.",
            "nullable": true,
            "example": "Pro plan"
          },
          "description": {
            "type": "string",
            "description": "At most 5,000 characters.",
            "nullable": true,
            "example": "Unlimited projects and priority support."
          },
          "url": {
            "type": "string",
            "description": "A full address starting with `https://`, at most 2,000 characters.",
            "nullable": true,
            "example": "https://example.com/pricing#pro"
          },
          "imageUrl": {
            "type": "string",
            "description": "A full address starting with `https://`, at most 2,000 characters.",
            "nullable": true,
            "example": "https://example.com/img/pro.png"
          },
          "price": {
            "type": "number",
            "description": "Zero or more.",
            "format": "decimal",
            "nullable": true,
            "example": 49
          },
          "comparePrice": {
            "type": "number",
            "description": "The price before a discount. Must be higher than `price`.",
            "format": "decimal",
            "nullable": true,
            "example": 59
          },
          "currency": {
            "type": "string",
            "description": "The three-letter currency code, such as `EUR` or `GBP`.",
            "nullable": true,
            "example": "EUR"
          },
          "inStock": {
            "type": "boolean",
            "description": "A new item is in stock unless you say otherwise.",
            "nullable": true,
            "example": true
          },
          "stockQuantity": {
            "type": "integer",
            "description": "A whole number of zero or more.",
            "format": "int32",
            "nullable": true,
            "example": null
          },
          "categories": {
            "type": "array",
            "description": "At most 20, each a short name.",
            "nullable": true,
            "example": [
              "plans"
            ],
            "items": {
              "type": "string"
            }
          },
          "attributes": {
            "type": "object",
            "description": "At most 50 fields, each a short lowercase key with a text, number or yes/no value.",
            "nullable": true,
            "example": {
              "billing": "monthly",
              "seats": 5
            },
            "additionalProperties": {}
          },
          "active": {
            "type": "boolean",
            "description": "A new item is active. `false` stops recommending it but keeps its history.",
            "nullable": true,
            "example": true
          }
        }
      },
      "ApiEnvelopeOfCatalogItemsBatchResponseDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/CatalogItemsBatchResponseDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "CatalogItemsBatchResponseDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "created": {
            "type": "integer",
            "description": "How many items were created.",
            "format": "int32"
          },
          "updated": {
            "type": "integer",
            "description": "How many existing items were updated.",
            "format": "int32"
          },
          "failed": {
            "type": "integer",
            "description": "How many items were refused. The others were still written.",
            "format": "int32"
          },
          "results": {
            "type": "array",
            "description": "One entry per item, in the order you sent them.",
            "items": {
              "$ref": "#/components/schemas/CatalogBatchItemResultDto"
            }
          }
        }
      },
      "CatalogBatchItemResultDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "index": {
            "type": "integer",
            "description": "The item's position in your request, starting at 0.",
            "format": "int32"
          },
          "status": {
            "type": "string",
            "description": "`created`, `updated` or `failed`."
          },
          "id": {
            "type": "string",
            "description": "The item's Azimea id; `null` when it failed.",
            "format": "guid",
            "nullable": true
          },
          "errors": {
            "type": "array",
            "description": "Why the item was refused; `null` when it was written.",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/CatalogBatchItemErrorDto"
            }
          }
        }
      },
      "CatalogBatchItemErrorDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "description": "A stable error code, listed in the error codes catalog."
          },
          "field": {
            "type": "string",
            "description": "The request field the problem is about; `null` when it is about the whole item.",
            "nullable": true
          },
          "params": {
            "type": "object",
            "description": "The numbers the code refers to (a minimum, a maximum), when there are any.",
            "nullable": true,
            "additionalProperties": {}
          }
        }
      },
      "CatalogItemsBatchRequestDto": {
        "type": "object",
        "example": {
          "items": [
            {
              "id": "plan-pro",
              "kind": "plan",
              "name": "Pro plan",
              "description": "Unlimited projects and priority support.",
              "url": "https://example.com/pricing#pro",
              "imageUrl": "https://example.com/img/pro.png",
              "price": 49,
              "comparePrice": 59,
              "currency": "EUR",
              "inStock": true,
              "stockQuantity": null,
              "categories": [
                "plans"
              ],
              "attributes": {
                "billing": "monthly",
                "seats": 5
              },
              "active": true
            }
          ]
        },
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "description": "The items to write, up to 1,000. Each is written exactly as `POST /items` would write it.",
            "nullable": true,
            "example": [
              {
                "id": "plan-pro",
                "kind": "plan",
                "name": "Pro plan",
                "description": "Unlimited projects and priority support.",
                "url": "https://example.com/pricing#pro",
                "imageUrl": "https://example.com/img/pro.png",
                "price": 49,
                "comparePrice": 59,
                "currency": "EUR",
                "inStock": true,
                "stockQuantity": null,
                "categories": [
                  "plans"
                ],
                "attributes": {
                  "billing": "monthly",
                  "seats": 5
                },
                "active": true
              }
            ],
            "items": {
              "$ref": "#/components/schemas/CatalogItemRequestDto"
            }
          }
        }
      },
      "ApiEnvelopeOfOrderPageDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/OrderPageDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "OrderPageDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "items": {
            "type": "array",
            "description": "The orders on this page, newest first.",
            "items": {
              "$ref": "#/components/schemas/OrderDto"
            }
          },
          "page": {
            "type": "integer",
            "description": "The page number, starting at 1.",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "description": "How many orders a full page holds.",
            "format": "int32"
          },
          "totalCount": {
            "type": "integer",
            "description": "How many orders match in all, across every page.",
            "format": "int32"
          }
        }
      },
      "OrderDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Azimea's id for the order.",
            "format": "guid"
          },
          "storeId": {
            "type": "string",
            "description": "The connected store the order came from.",
            "format": "guid"
          },
          "number": {
            "type": "string",
            "description": "The order number as the buyer sees it; it can differ from the store's internal id.",
            "nullable": true
          },
          "status": {
            "description": "Where the order stands. See the order statuses catalog.",
            "$ref": "#/components/schemas/OrderStatus"
          },
          "currency": {
            "type": "string",
            "description": "The three-letter currency code of `total`.",
            "nullable": true
          },
          "total": {
            "type": "number",
            "description": "The order's total, in `currency`.",
            "format": "decimal"
          },
          "email": {
            "type": "string",
            "description": "The buyer's email address.",
            "nullable": true
          },
          "customerName": {
            "type": "string",
            "description": "The buyer's name.",
            "nullable": true
          },
          "placedAt": {
            "type": "string",
            "description": "When the order was placed.",
            "format": "date-time",
            "nullable": true
          },
          "paidAt": {
            "type": "string",
            "description": "When it was paid; `null` while it is not.",
            "format": "date-time",
            "nullable": true
          },
          "lineCount": {
            "type": "integer",
            "description": "How many lines (products) the order has.",
            "format": "int32"
          }
        }
      },
      "OrderStatus": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Pending",
          "Paid",
          "Completed",
          "Cancelled",
          "Refunded",
          "Failed",
          "Draft"
        ],
        "enum": [
          "Pending",
          "Paid",
          "Completed",
          "Cancelled",
          "Refunded",
          "Failed",
          "Draft"
        ]
      },
      "GetOrdersRequestDto": {
        "type": "object",
        "additionalProperties": false
      },
      "OrderView": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "All",
          "Paid",
          "Pending",
          "Abandoned",
          "Refunded"
        ],
        "enum": [
          "All",
          "Paid",
          "Pending",
          "Abandoned",
          "Refunded"
        ]
      },
      "ApiEnvelopeOfTrackEventsResponseDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/TrackEventsResponseDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "TrackEventsResponseDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "accepted": {
            "type": "integer",
            "description": "How many events were accepted.",
            "format": "int32"
          },
          "duplicates": {
            "type": "integer",
            "description": "How many were ignored because their `id` was already used.",
            "format": "int32"
          },
          "rejected": {
            "type": "array",
            "description": "The events that were refused, each with its position and reasons.",
            "items": {
              "$ref": "#/components/schemas/TrackEventRejectionDto"
            }
          }
        }
      },
      "TrackEventRejectionDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "index": {
            "type": "integer",
            "description": "The event's position in your request, starting at 0.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "Why it was refused.",
            "items": {
              "$ref": "#/components/schemas/TrackEventErrorDto"
            }
          }
        }
      },
      "TrackEventErrorDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "description": "A stable error code, listed in the error codes catalog."
          },
          "field": {
            "type": "string",
            "description": "The event field the problem is about."
          },
          "params": {
            "type": "object",
            "description": "The numbers the code refers to (a minimum, a maximum), when there are any.",
            "nullable": true,
            "additionalProperties": {}
          }
        }
      },
      "TrackEventsRequestDto": {
        "type": "object",
        "example": {
          "events": [
            {
              "id": "evt_7f3c2a",
              "name": "user.signed_up",
              "occurredAt": "2026-10-05T09:30:00+00:00",
              "contact": {
                "externalId": "user_123",
                "email": "emma@example.com"
              },
              "properties": {
                "plan": "trial",
                "source": "landing-page"
              }
            }
          ]
        },
        "additionalProperties": false,
        "required": [
          "events"
        ],
        "properties": {
          "events": {
            "type": "array",
            "description": "The events, up to 100 per call. Each is accepted or rejected on its own.",
            "minLength": 1,
            "nullable": false,
            "example": [
              {
                "id": "evt_7f3c2a",
                "name": "user.signed_up",
                "occurredAt": "2026-10-05T09:30:00+00:00",
                "contact": {
                  "externalId": "user_123",
                  "email": "emma@example.com"
                },
                "properties": {
                  "plan": "trial",
                  "source": "landing-page"
                }
              }
            ],
            "items": {
              "$ref": "#/components/schemas/TrackEventDto"
            }
          }
        }
      },
      "TrackEventDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "Your own id for this event, unique in your account. Sending it again counts as a duplicate, so retries are safe.",
            "nullable": true,
            "example": "evt_7f3c2a"
          },
          "name": {
            "type": "string",
            "description": "What happened: lowercase letters, digits, `_` and `.`, starting with a letter, at most 64 characters. The prefixes `order.`, `cart.`, `customer.`, `subscriber.`, `contact.`, `email.` and `azimea.` are reserved.",
            "nullable": true,
            "example": "user.signed_up"
          },
          "occurredAt": {
            "type": "string",
            "description": "When it happened: at most 30 days in the past, never in the future. Now, when left out.",
            "format": "date-time",
            "nullable": true,
            "example": "2026-10-05T09:30:00+00:00"
          },
          "contact": {
            "description": "Who did it: the same object `POST /contacts` takes, with at least a user id (`externalId`) or an `email`.",
            "nullable": true,
            "example": {
              "externalId": "user_123",
              "email": "emma@example.com"
            }
          },
          "properties": {
            "description": "Anything about the event, as a JSON object of at most 16 KB and 3 levels deep. Flows can filter on it and emails can show it.",
            "nullable": true,
            "example": {
              "plan": "trial",
              "source": "landing-page"
            }
          }
        }
      },
      "ApiEnvelopeOfTransactionalEmailResultDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "isSuccess": {
            "type": "boolean",
            "description": "`true` when the call worked, `false` when `errors` say why it did not."
          },
          "value": {
            "description": "The answer itself; `null` when the call failed.",
            "nullable": true,
            "oneOf": [
              {
                "$ref": "#/components/schemas/TransactionalEmailResultDto"
              }
            ]
          },
          "status": {
            "type": "integer",
            "description": "An internal result number. Rely on the HTTP status code instead.",
            "format": "int32"
          },
          "errors": {
            "type": "array",
            "description": "What went wrong, one entry per problem; empty when the call worked.",
            "items": {
              "$ref": "#/components/schemas/ApiError"
            }
          },
          "fieldErrors": {
            "type": "object",
            "description": "The same problems grouped by the request field they belong to; `null` when none is tied to a field.",
            "nullable": true,
            "additionalProperties": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ApiError"
              }
            }
          }
        }
      },
      "TransactionalEmailResultDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "The submission id. Use it to retrieve all recipient statuses. For a single recipient it is also the delivery id.",
            "format": "guid"
          },
          "status": {
            "type": "string",
            "description": "The common delivery status, or Mixed when recipients have different statuses. Inspect recipients for the individual outcomes."
          },
          "reason": {
            "type": "string",
            "description": "The common reason when all recipients share one; null otherwise. Inspect recipients[].reason for individual problems.",
            "nullable": true
          },
          "recipients": {
            "type": "array",
            "description": "All recipient deliveries, including suppressed ones. Each has independent status, retries, tracking and quota usage.",
            "items": {
              "$ref": "#/components/schemas/EmailRecipientResultDto"
            }
          },
          "sendAt": {
            "type": "string",
            "description": "Requested UTC schedule, or null for immediate sends. Queued also covers a future schedule.",
            "format": "date-time",
            "nullable": true
          },
          "templateId": {
            "type": "string",
            "description": "The template used at acceptance, if any.",
            "format": "guid",
            "nullable": true
          },
          "metadata": {
            "type": "object",
            "description": "Caller correlation data; removed when retention erases message content.",
            "additionalProperties": {
              "type": "string"
            }
          },
          "tags": {
            "type": "object",
            "description": "Caller labels; removed when retention erases message content.",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "EmailRecipientResultDto": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "description": "The delivery id for this recipient. Matches message_id in delivery webhooks.",
            "format": "guid"
          },
          "email": {
            "type": "string",
            "description": "The normalized recipient address. Empty after retention removes personal data."
          },
          "name": {
            "type": "string",
            "description": "The optional recipient display name.",
            "nullable": true
          },
          "kind": {
            "description": "Whether the recipient was requested as To, Cc or Bcc.",
            "$ref": "#/components/schemas/EmailRecipientKind"
          },
          "status": {
            "description": "This recipient's current delivery status. Queued and Sent do not mean Delivered.",
            "$ref": "#/components/schemas/EmailDeliveryStatus"
          },
          "reason": {
            "type": "string",
            "description": "The reason for suppression, waiting or failure, when present.",
            "nullable": true
          }
        }
      },
      "EmailRecipientKind": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "To",
          "Cc",
          "Bcc"
        ],
        "enum": [
          "To",
          "Cc",
          "Bcc"
        ]
      },
      "EmailDeliveryStatus": {
        "type": "string",
        "description": "",
        "x-enumNames": [
          "Queued",
          "Sent",
          "Failed",
          "Suppressed",
          "Delivered",
          "Bounced",
          "HandingOff",
          "Accepted",
          "Unknown",
          "PendingReview"
        ],
        "enum": [
          "Queued",
          "Sent",
          "Failed",
          "Suppressed",
          "Delivered",
          "Bounced",
          "HandingOff",
          "Accepted",
          "Unknown",
          "PendingReview"
        ]
      },
      "SendTransactionalEmailRequestDto": {
        "type": "object",
        "example": {
          "to": [
            {
              "email": "emma@example.com",
              "name": null
            }
          ],
          "subject": "Your order 1042 is confirmed",
          "html": "<p>Hi Emma,</p><p>Thank you for your order 1042. We will let you know when it ships.</p>"
        },
        "not": {
          "required": [
            "html",
            "templateId"
          ],
          "properties": {
            "html": {
              "type": "string",
              "minLength": 1
            },
            "templateId": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false,
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "description": "Required visible recipients: an array of { email, name? } objects, or one address string for compatibility. At most 50 addresses across To, CC and BCC; duplicates are rejected.",
            "nullable": false,
            "example": [
              {
                "email": "emma@example.com",
                "name": null
              }
            ],
            "oneOf": [
              {
                "type": "array",
                "maxItems": 50,
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/EmailAddress"
                }
              },
              {
                "type": "string",
                "format": "email",
                "maxLength": 320
              }
            ]
          },
          "subject": {
            "type": "string",
            "description": "The subject line, at most 300 characters after rendering, with no control characters. Required unless templateId supplies one.",
            "maxLength": 300,
            "minLength": 0,
            "nullable": true,
            "example": "Your order 1042 is confirmed"
          },
          "html": {
            "type": "string",
            "description": "HTML body, at most 500,000 characters after rendering. Required unless text or templateId supplies content. Cannot be combined with templateId.",
            "maxLength": 500000,
            "minLength": 0,
            "nullable": true,
            "example": "<p>Hi Emma,</p><p>Thank you for your order 1042. We will let you know when it ships.</p>"
          },
          "from": {
            "description": "Optional { email, name? } sender on a verified domain belonging to this account. Omit to use the default sender. Checked at acceptance and delivery.",
            "nullable": true,
            "example": null,
            "oneOf": [
              {
                "$ref": "#/components/schemas/EmailAddress"
              }
            ]
          },
          "replyTo": {
            "description": "Optional reply recipients: 1 to 10 mailbox objects, or a single address string. Omit to use the saved sender reply-to. These do not receive a delivery.",
            "nullable": true,
            "example": null,
            "oneOf": [
              {
                "type": "array",
                "maxItems": 10,
                "minItems": 1,
                "items": {
                  "$ref": "#/components/schemas/EmailAddress"
                }
              },
              {
                "type": "string",
                "format": "email",
                "maxLength": 320
              }
            ]
          },
          "text": {
            "type": "string",
            "description": "Plain-text body, up to 500,000 characters after rendering. Supply html, text, or templateId; both html and text produce multipart/alternative.",
            "maxLength": 500000,
            "minLength": 0,
            "nullable": true,
            "example": null
          },
          "templateId": {
            "type": "string",
            "description": "Saved template UUID in this account or sandbox. Its current HTML and subject are snapshotted at acceptance. Cannot be combined with html. Subject can override the template subject.",
            "format": "guid",
            "nullable": true,
            "example": null
          },
          "variables": {
            "type": "object",
            "description": "String values for {{key}} substitutions in subject, HTML and text. Up to 100 keys (1-64 letters, digits, underscore, dot or dash; first character alphanumeric or underscore), values up to 10,000 characters. Missing variables fail. HTML substitutions are escaped; no loops or raw HTML.",
            "maxProperties": 100,
            "nullable": true,
            "example": null,
            "additionalProperties": {
              "type": "string"
            }
          },
          "attachments": {
            "type": "array",
            "description": "Up to 10 base64 attachments, at most 5 MiB decoded combined. Entire JSON request is limited to 8 MiB. No remote URLs. Optional contentId embeds a file as an inline MIME resource.",
            "maxItems": 10,
            "example": [],
            "items": {
              "$ref": "#/components/schemas/EmailAttachmentRequestDto"
            }
          },
          "headers": {
            "type": "object",
            "description": "Up to 20 custom headers: X-* except X-Azimea-*, plus In-Reply-To and References. Names at most 64 ASCII letters, digits or dashes; values at most 998 characters without controls. Case-insensitive duplicates and routing/MIME headers are rejected.",
            "maxProperties": 20,
            "example": {},
            "additionalProperties": {
              "type": "string"
            }
          },
          "metadata": {
            "type": "object",
            "description": "Up to 20 string pairs for internal correlation, returned by status and webhooks. Values up to 500 characters; keys follow variables rules. Not added to email headers.",
            "maxProperties": 20,
            "example": {},
            "additionalProperties": {
              "type": "string"
            }
          },
          "tags": {
            "type": "object",
            "description": "Up to 20 string labels, returned by status and webhooks. Values up to 100 characters; keys follow variables rules. Not added to email headers.",
            "maxProperties": 20,
            "example": {},
            "additionalProperties": {
              "type": "string"
            }
          },
          "sendAt": {
            "type": "string",
            "description": "ISO 8601 timestamp with timezone, at most 30 days ahead. Stored in UTC; past timestamps are due immediately. Delivery can occur later because of queue limits or retries. Not an exact arrival guarantee.",
            "format": "date-time",
            "nullable": true,
            "example": null
          },
          "tracking": {
            "description": "Optional opens/clicks restrictions. false disables that measurement; true or omission follows account and recipient policy and cannot override an opt-out. Plain-text links are not rewritten.",
            "nullable": true,
            "example": null,
            "oneOf": [
              {
                "$ref": "#/components/schemas/EmailTrackingOptions"
              }
            ]
          },
          "cc": {
            "description": "Optional visible copy recipients, using the same mailbox format as to. Everyone sees To and CC.",
            "nullable": false,
            "example": [],
            "oneOf": [
              {
                "type": "array",
                "maxItems": 50,
                "items": {
                  "$ref": "#/components/schemas/EmailAddress"
                }
              },
              {
                "type": "string",
                "format": "email",
                "maxLength": 320
              }
            ]
          },
          "bcc": {
            "description": "Optional blind copy recipients. These addresses are never included in recipient headers. Returned only to the authenticated sending account.",
            "nullable": false,
            "example": [],
            "oneOf": [
              {
                "type": "array",
                "maxItems": 50,
                "items": {
                  "$ref": "#/components/schemas/EmailAddress"
                }
              },
              {
                "type": "string",
                "format": "email",
                "maxLength": 320
              }
            ]
          }
        },
        "anyOf": [
          {
            "required": [
              "subject"
            ],
            "properties": {
              "subject": {
                "type": "string",
                "minLength": 1
              }
            },
            "anyOf": [
              {
                "required": [
                  "html"
                ],
                "properties": {
                  "html": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              },
              {
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              }
            ]
          },
          {
            "required": [
              "templateId"
            ],
            "properties": {
              "templateId": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        ]
      },
      "EmailRecipientList": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/EmailAddress"
        }
      },
      "EmailAddress": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "email",
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "One bare mailbox address, at most 320 characters. Put a display name in name, not inside this field.",
            "maxLength": 320,
            "minLength": 0,
            "nullable": false,
            "example": "emma@example.com"
          },
          "name": {
            "type": "string",
            "description": "Optional display name, at most 100 characters. Control characters are rejected.",
            "maxLength": 100,
            "minLength": 0,
            "nullable": true,
            "example": null
          }
        }
      },
      "EmailAttachmentRequestDto": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "fileName",
          "content"
        ],
        "properties": {
          "fileName": {
            "type": "string",
            "description": "Attachment filename, 1-255 characters; no path separators, control characters or filesystem-reserved punctuation.",
            "maxLength": 255,
            "minLength": 1
          },
          "content": {
            "type": "string",
            "description": "Base64 encoded file bytes. At most 5 MiB decoded across all attachments. File URLs are not accepted.",
            "maxLength": 6990508,
            "minLength": 1
          },
          "contentType": {
            "type": "string",
            "description": "MIME media type without parameters, such as application/pdf or image/png. Defaults to application/octet-stream. multipart types are rejected."
          },
          "contentId": {
            "type": "string",
            "description": "Optional unique inline content id (1-127 letters, digits, underscore, dot, @ or dash). Reference as cid:value in HTML; omit angle brackets.",
            "maxLength": 127,
            "nullable": true
          }
        }
      },
      "EmailTrackingOptions": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "opens": {
            "type": "boolean",
            "description": "false disables the open pixel; true/null follows existing account and recipient policy.",
            "nullable": true
          },
          "clicks": {
            "type": "boolean",
            "description": "false disables HTML link tracking; true/null follows existing account and recipient policy.",
            "nullable": true
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "description": "An API key from Settings › API keys, sent as a bearer token.",
        "scheme": "bearer",
        "bearerFormat": "azm_live_…"
      }
    }
  }
}